Opulent API

Programmatic access to Opulent as a complete AI agent — not just text generation, but full task execution

What is the Opulent API?

The Opulent API is a RESTful API that gives developers programmatic access to the full Opulent agent. Instead of calling an endpoint and getting a text completion back, you send a task, and Opulent plans the approach, uses tools, browses the web, queries your data, writes and runs code, and delivers a complete result.

This is the difference between an AI API and an AI agent API.

Why the Opulent API is Different

Traditional AI API:

Send a prompt → receive a text response
Model has no tools, no memory, no ability to act

Opulent API:

Send a task → agent plans, executes, delivers
Agent has: browser, code execution, connectors, memory, file system
Output can be: a report, a slide deck, a populated spreadsheet, deployed code, a Notion page, a Slack message

# Traditional AI API
response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Research Acme Corp"}]
)
# Returns: text about how it would research Acme Corp

# Opulent API
task = opulent.tasks.create(
    prompt="Research Acme Corp — funding, headcount, products, recent news. Deliver as a structured brief.",
    connectors=["web_search", "crunchbase"],
    output={"slack_channel": "#sales-prep"}
)
# Returns: task_id
# Agent actually researches, synthesizes, and posts to Slack

Quick Start

Install the SDK

npm install @opulentia/sdk
# or
pip install opulentia

Create a Task

import { Opulent } from '@opulentia/sdk';

const client = new Opulent({ apiKey: process.env.OPULENT_API_KEY });

const task = await client.tasks.create({
  prompt: 'Research the top 10 enterprise AI platforms and create a comparison table covering: pricing, key features, target ICP, and G2 rating.',
  connectors: ['web_search'],
  output: { format: 'markdown' }
});

// Poll for completion
const result = await client.tasks.waitForCompletion(task.id);
console.log(result.output);

from opulentia import Opulent

client = Opulent(api_key=os.environ["OPULENT_API_KEY"])

task = client.tasks.create(
    prompt="Analyze our Q4 Stripe revenue. MRR, churn, top 10 accounts. Return as JSON.",
    connectors=["stripe"],
    output={"format": "json"}
)

result = client.tasks.wait_for_completion(task.id)
print(result.output)

Core Endpoints

Tasks

Method	Endpoint	Description
`POST`	`/v1/tasks`	Create a new task
`GET`	`/v1/tasks/{id}`	Get task status and result
`GET`	`/v1/tasks`	List all tasks
`DELETE`	`/v1/tasks/{id}`	Cancel or delete a task

Create Task Request

{
  "prompt": "Research the Series A funding landscape for AI startups in Q4 2025. Identify top 20 rounds, investors, and deal terms.",
  "connectors": ["web_search", "crunchbase"],
  "thread_id": "optional-existing-thread-id",
  "output": {
    "format": "markdown",
    "deliver_to": {
      "slack_channel": "#research",
      "email": "analyst@company.com"
    }
  },
  "options": {
    "model": "accounts/fireworks/models/kimi-k2p5",
    "max_steps": 80
  }
}

Task Response

{
  "id": "task_abc123",
  "status": "completed",
  "created_at": "2026-02-21T19:00:00Z",
  "completed_at": "2026-02-21T19:04:32Z",
  "output": {
    "text": "# Q4 2025 AI Startup Funding Analysis\n\n...",
    "format": "markdown",
    "files": [
      {
        "name": "funding-analysis.md",
        "url": "https://..."
      }
    ]
  },
  "usage": {
    "steps": 12,
    "tools_called": 8
  }
}

Threads

Threads maintain conversation context across multiple tasks:

// Create a thread for a project
const thread = await client.threads.create({
  title: 'Q4 Investor Research',
  workspace_id: 'ws_abc'
});

// All tasks in this thread share context
await client.tasks.create({
  thread_id: thread.id,
  prompt: 'Research Sequoia Capital portfolio companies'
});

await client.tasks.create({
  thread_id: thread.id,
  prompt: 'Now compare to a16z's portfolio from the same period'
  // Agent remembers the Sequoia research above
});

Streaming

For real-time results, use Server-Sent Events:

const stream = await client.tasks.stream({
  prompt: 'Write a detailed technical specification for a payment processing microservice'
});

for await (const event of stream) {
  if (event.type === 'tool_call') {
    console.log('Agent using tool:', event.tool);
  }
  if (event.type === 'text_delta') {
    process.stdout.write(event.text);
  }
  if (event.type === 'complete') {
    console.log('\nTask complete');
  }
}

Enabling Connectors via API

Specify which connectors the agent can use for a given task:

{
  "prompt": "Pull Q4 MRR from Stripe and update the Notion revenue dashboard",
  "connectors": ["stripe", "notion"],
  "connector_options": {
    "stripe": { "account_id": "acct_xxx" },
    "notion": { "database_id": "db_xxx" }
  }
}

Available connector IDs: stripe, salesforce, hubspot, github, slack, notion, google_drive, postgresql, snowflake, web_search, email, and all others from the Connectors list.

Webhooks (Outbound)

POST /v1/webhooks
{
  "url": "https://yourapp.com/opulent-webhook",
  "events": ["task.completed", "task.failed"],
  "secret": "your-signing-secret"
}

Opulent will POST to your URL when tasks complete:

{
  "event": "task.completed",
  "task_id": "task_abc123",
  "output": { ... },
  "timestamp": "2026-02-21T19:04:32Z"
}

Rate Limits

Plan	Tasks per minute	Concurrent tasks
Starter	10	3
Growth	60	20
Enterprise	Custom	Custom

Use Cases for the API

Embed Opulent in Your Product

User requests a competitive analysis report in your SaaS app
→ Your backend calls Opulent API with the research prompt
→ Opulent researches and produces a formatted report
→ Report displayed to user in your UI

Build Intelligent Internal Tools

Slack bot receives a slash command: /briefing COMPANY_NAME
→ Your Slack app calls Opulent API
→ Opulent researches the company
→ Summary posted back to Slack automatically

Automate Reporting Pipelines

Cron job runs every Monday
→ Calls Opulent API with weekly report prompt
→ Opulent queries Stripe + HubSpot + GitHub
→ Produces slide deck
→ Posts to leadership Slack channel

Authentication

All API calls require a Bearer token:

curl -X POST https://artful-fly-108.convex.site/api/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Your task here"}'

Get your API key from Settings → API Keys.

Common Questions

Is this the same agent as the web UI? Yes. The same agent, the same tools, the same connectors.

Can I use the API with my own models? Enterprise plans support custom model routing. Contact us for details.

How do I handle long-running tasks? Use webhooks to receive completion notifications rather than polling. For real-time updates, use the streaming endpoint.

Is there a sandbox/test mode? Yes. Use the "test": true flag in requests. Test tasks run against real agent logic but don't consume production connector quotas.

Where is the full API reference? See api.opulentia.ai/docs for the complete OpenAPI specification.