Suprsonic is a unified API for AI agents. Instead of integrating dozens of providers for search, scraping, enrichment, image generation, transcription, messaging, and more, you add one API key and get all of them.
No provider authentication required. Suprsonic manages all provider subscriptions internally. You never need OAuth flows, per-provider API keys, or token management for any capability. Just your Suprsonic key.
Every capability uses the same authentication, the same response format, and the same credit system. If a provider fails, Suprsonic automatically falls back to the next one. You don't manage retries, credentials, or individual provider accounts.
Available as a REST API, Python SDK, TypeScript SDK, and MCP server. Use whichever fits your stack.
Step 1: Get your API key
Create a key in the API Keys tab. It starts with omk_ and works across every capability.
Step 2: Make your first call
pip install suprsonic
from suprsonic import Suprsonic
client = Suprsonic("omk_your_key")
result = client.search("latest AI funding rounds")
print(result.data)npm install suprsonic
import { Suprsonic } from "suprsonic";
const client = new Suprsonic("omk_your_key");
const result = await client.search("latest AI funding rounds");
console.log(result.data);{
"suprsonic": {
"command": "npx",
"args": ["-y", "suprsonic-mcp"],
"env": { "SUPRSONIC_API_KEY": "omk_your_key" }
}
}curl -X POST https://suprsonic.ai/v1/search \
-H "Authorization: Bearer omk_your_key" \
-H "Content-Type: application/json" \
-d '{"query": "latest AI funding rounds", "mode": "ai"}'All four methods hit the same API, use the same key, and deduct from the same credit balance.
All unified agent APIs use Bearer token authentication. Include your API key in the Authorization header of every request.
Authorization: Bearer omk_your_key_hereAPI keys are created in the API Keys section. Each key works across all capabilities and is tied to your account and credit balance. Keys can be revoked at any time.
Rate limits
Default: 60 requests per minute per key. Rate limit headers are included in every response:
X-RateLimit-Remaining: 58
X-RateLimit-Limit: 60
X-RateLimit-Reset: 1713400060
X-Credits-Used: 2Each capability costs a fixed number of credits per successful call. Failed requests are free. Capabilities with modes let you choose the cost/quality tradeoff.
/v1/builds
1 creditStart a Founden build from a plain-language prompt
/v1/builds/{execution_id}
0 creditsGet build status and the live preview URL
/v1/builds/{execution_id}/message
0 creditsSend a follow-up instruction to a running build
/v1/builds/{execution_id}/stop
0 creditsStop a running build
The Agent API (/v1/agent) costs the same as whichever capability it routes to. Credits are returned in the credits_used field and the X-Credits-Used response header.
All errors follow RFC 7807 (Problem Details for HTTP APIs) with additional fields for agent consumption.
{
"success": false,
"error": {
"type": "https://api.o-mega.ai/errors/rate-limited",
"title": "Rate limit exceeded",
"status": 429,
"detail": "You have exceeded 60 requests per minute",
"is_retriable": true,
"retry_after_seconds": 42,
"alternative_action": "Reduce request frequency or contact support",
"error_category": "transient"
},
"credits_used": 0
}Error categories
Temporary issue. Safe to retry after retry_after_seconds.
Request is invalid. Do not retry with the same parameters.
API key is missing, invalid, or revoked.
Insufficient credits. Upgrade plan or enable overage.
The target content could not be accessed (blocked, CAPTCHA, etc).
HTTP status codes
Success. The request completed and data is in the response.
Bad request. Missing or invalid parameters.
Unauthorized. API key is missing or invalid.
Insufficient credits. Upgrade or enable overage.
Unprocessable. The request was valid but the operation failed (e.g. scrape blocked).
Rate limited. Retry after the specified interval.
Provider error. All upstream providers failed.
Every response uses the same format, regardless of which capability or provider handled the request. This makes it easy for agents to parse responses uniformly.
{
"success": boolean,
"data": { ... } | null,
"error": { ... } | null,
"metadata": {
"provider_used": "string | null",
"providers_tried": ["string"],
"mode_used": "string | null",
"response_time_ms": number,
"request_id": "string"
},
"credits_used": number
}Metadata fields
provider_used
string
Which provider's data was used in the final response. 'merged' if data came from multiple providers.
providers_tried
string[]
All providers that were attempted in the waterfall, in order.
mode_used
string
The mode that was applied (e.g. 'ai', 'standard').
response_time_ms
number
Total wall-clock time for the request in milliseconds.
request_id
string
Unique request identifier for debugging and support.
Every package uses the same API key and hits the same backend. Pick whichever fits your stack.
MCP Server
$ npx suprsonic-mcpWorks with Claude Desktop, Cursor, VS Code, ChatGPT. Your agent gets every capability as MCP tools.
Python SDK
$ pip install suprsonicFor LangChain, CrewAI, OpenAI Agents SDK, Claude API, or any Python agent.
TypeScript SDK
$ npm install suprsonicFor Vercel AI SDK, LangChain.js, Node.js agents, or any TypeScript project.
REST API
Works with any language or framework. Use curl or any HTTP client with a Bearer token.
Machine-readable formats
For auto-generating clients or configuring agent frameworks:
OpenAPI spec
/v1/openapi.jsonFiltered OpenAPI 3.1 spec with only Suprsonic capabilities.
Tool definitions
/v1/tools?format=openaiPre-built tool schemas for OpenAI, Claude, and MCP. Formats: openai, claude, mcp, raw.
llms.txt
/llms.txtAI-readable documentation index for agent discovery.
Suprsonic provides machine-readable tool definitions that any AI agent framework can consume directly. One tool definition gives your agent access to all capabilities. No manual configuration needed.
Tool definition endpoint
Fetch a ready-to-use tool definition, auto-generated from the API schema. No auth required. Choose the format that matches your agent framework.
OpenAI-compatible function calling schema
Anthropic-compatible tool use schema
Model Context Protocol schema (for MCP clients)
Full JSON with per-capability parameter schemas, types, defaults, and descriptions
How it works
Your agent or AI coder fetches the tool definition once, registers it, and routes tool calls to POST /v1/agent. The tool definition contains all parameter names, types, required/optional markers, defaults, and descriptions. No hardcoding needed.
# 1. Fetch the tool definition (pick your format)
GET https://suprsonic.ai/v1/tools?format=openai
# 2. Register it as a tool in your agent framework
# The response is a complete tool schema. Pass it directly.
# 3. When the agent calls the tool, forward to /v1/agent
POST https://suprsonic.ai/v1/agent
Authorization: Bearer omk_your_key_here
Content-Type: application/json
{"capability": "search", "params": {"query": "..."}}The tool definition updates automatically when capabilities are added or parameters change. Fetch it at startup or cache it.
Other discovery endpoints
OpenAPI spec
/v1/openapi.jsonFiltered OpenAPI 3.1 spec for auto-generating typed clients in any language.
llms.txt
/llms.txtAI-readable documentation index for coding agents and RAG pipelines.
One endpoint for every capability.
Instead of registering dozens of separate tools, your agent registers one: POST /v1/agent. Specify the capability and parameters, and the system routes internally. Same response format regardless of which capability you call.
POST /v1/agent
{
"capability": "emails",
"params": {
"first_name": "Yuma",
"last_name": "Heymans",
"domain": "o-mega.ai"
}
}Available capabilities
/v1/builds
Describe the business or app you want. Founden builds the full product in the cloud and returns an execution_id plus a stream URL for live progress.
/v1/builds/{execution_id}
Poll a build by execution_id. Returns the current status and, once ready, the live preview URL.
/v1/builds/{execution_id}/message
Keep iterating in plain language. 'Add online booking.' 'Change the colors.' The change ships to your live site. Free within a build.
/v1/builds/{execution_id}/stop
Gracefully stop an in-progress build. Any work already committed is saved.
Python SDK
from suprsonic import Suprsonic
client = Suprsonic("omk_your_key")
# Convenience methods
result = client.search("latest AI news")
result = client.scrape("https://example.com")
result = client.verify_email("john@example.com")
result = client.emails.find(first_name="John", last_name="Doe", domain="example.com")
# Or use .run() for any capability
result = client.run("screenshot", url="https://example.com")TypeScript SDK
import { Suprsonic } from "suprsonic";
const client = new Suprsonic("omk_your_key");
const result = await client.search("latest AI news");
const result = await client.scrape("https://example.com");
const result = await client.verifyEmail("john@example.com");
// Or use .run() for any capability
const result = await client.run("screenshot", { url: "https://example.com" });Describe the business or app you want. Founden builds the full product in the cloud and returns an execution_id plus a stream URL for live progress.
Start a Founden build from a plain-language prompt
Parameters
prompt
Requiredstring
What to build or change, in plain language.
company_id
string
Target an existing company you own. Omit to use (or create) your default company.
Example response
{
"success": true,
"data": {
"execution_id": "1e04e65f-6ded-4731-bc14-a1b307403bf3",
"company_id": "6a1bc9a7bea382d028741c45",
"status": "running",
"stream_url": "/cloud-build/1e04e65f-6ded-4731-bc14-a1b307403bf3/stream"
},
"metadata": {
"request_id": "req_xyz789"
},
"credits_used": 0
}Poll a build by execution_id. Returns the current status and, once ready, the live preview URL.
Get build status and the live preview URL
Parameters
execution_id
Requiredstring
The execution_id returned by build_company.
Example response
{
"success": true,
"data": {
"execution_id": "1e04e65f...",
"status": "completed",
"preview_url": "https://your-company.vercel.app"
},
"credits_used": 0
}Keep iterating in plain language. 'Add online booking.' 'Change the colors.' The change ships to your live site. Free within a build.
Send a follow-up instruction to a running build
Parameters
execution_id
Requiredstring
The execution_id returned by build_company.
prompt
Requiredstring
Follow-up instruction for the running build agent.
Example response
{
"success": true,
"data": {
"status": "accepted",
"execution_id": "1e04e65f..."
},
"credits_used": 0
}Gracefully stop an in-progress build. Any work already committed is saved.
Stop a running build
Parameters
execution_id
Requiredstring
The execution_id returned by build_company.
Example response
{
"success": true,
"data": {
"message": "Build stopped."
},
"credits_used": 0
}