API documentation

Connect your agent MCP

Sofya runs a remote MCP server at https://mcp.sofya.co/mcp. Add it to your agent and it gets four tools: search, fetch, extract and research. There are two ways to connect:

Either way, calls are charged to your account's credits, exactly like API calls, and show up in your dashboard usage. Apps you signed in to are listed under Connected apps, where you can disconnect them.

claude mcp add --transport http sofya https://mcp.sofya.co/mcp

claude mcp add --transport http sofya https://mcp.sofya.co/mcp \
  --header "Authorization: Bearer sofya_live_..."

{ "permissions": { "deny": ["WebSearch", "WebFetch"] } }

{
  "mcpServers": {
    "sofya": {
      "url": "https://mcp.sofya.co/mcp",
      "headers": { "Authorization": "Bearer sofya_live_..." }
    }
  }
}

{
  "servers": {
    "sofya": {
      "type": "http",
      "url": "https://mcp.sofya.co/mcp",
      "headers": { "Authorization": "Bearer sofya_live_..." }
    }
  }
}

{
  "mcpServers": {
    "sofya": {
      "serverUrl": "https://mcp.sofya.co/mcp",
      "headers": { "Authorization": "Bearer sofya_live_..." }
    }
  }
}

codex mcp add sofya --url https://mcp.sofya.co/mcp
codex mcp login sofya

[mcp_servers.sofya]
url = "https://mcp.sofya.co/mcp"
http_headers = { "Authorization" = "Bearer sofya_live_..." }

{
  "mcpServers": {
    "sofya": {
      "httpUrl": "https://mcp.sofya.co/mcp",
      "headers": { "Authorization": "Bearer sofya_live_..." }
    }
  }
}

{
  "mcpServers": {
    "sofya": {
      "url": "https://mcp.sofya.co/mcp",
      "headers": { "Authorization": "Bearer sofya_live_..." }
    }
  }
}

{
  "mcpServers": {
    "sofya": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.sofya.co/mcp", "--header", "Authorization: Bearer sofya_live_..."]
    }
  }
}

Tools

MCP tools take the same parameters and return the same JSON as the REST endpoints. The four web tools only read the web; none changes anything. Errors arrive as a tool result with isError: true and a message instead of an HTTP status code, and are not charged.

Authentication

Every API request needs your API key, sent in either the Authorization header or the X-API-Key header. Keys start with sofya_live_; keys made before October 27, 2026 start with ay_live_ and keep working. If GitHub finds one of your sofya_live_ keys in a public repository, we revoke it at once and email you.

Authorization: Bearer sofya_live_your_key_here
# or
X-API-Key: sofya_live_your_key_here

Exceptions: GET /v1/status and GET /v1/updates need no key, and MCP apps can sign in with your account instead (see Connect your agent). If you set an IP allowlist on a key, requests from any other IP get a 401. Keep keys on your server: calling the API from a web page would show your key to every visitor.

An agent with no key can ask for one, and you approve it in the browser. See Agent sign-up. A 401 carries a WWW-Authenticate header pointing to the OAuth metadata.

Search

Search the web. Returns page content, not just snippets. Choose a search depth to control the quality/cost tradeoff. Add include_answer to any depth for an AI-synthesized answer (+2 credits). This is a lightweight alternative to the 50-credit research endpoint.

Parameters

{
  "query": "latest AI news",
  "search_depth": "basic",
  "max_results": 10,
  "include_answer": false,
  "include_domains": [],
  "exclude_domains": [],
  "topic": "general",
  "freshness": null
}

{
  "query": "latest AI news",
  "answer": null,
  "results": [
    {
      "title": "...",
      "url": "...",
      "content": "Extracted page content...",
      "description": "The result's snippet",
      "fetched": true,
      "published_date": "2026-03-08",
      "sublinks": [],
      "table": {}
    }
  ],
  "search_depth": "basic",
  "topic": "general",
  "elapsed_ms": 4200,
  "credits_used": 2,
  "credits_remaining": 1998,
  "altered_query": null,
  "relaxed_query": null
}

Response fields

Examples

curl -X POST https://mcp.sofya.co/v1/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sofya_live_..." \
  -d '{"query": "latest AI news", "search_depth": "basic"}'

import httpx

resp = httpx.post("https://mcp.sofya.co/v1/search",
    headers={"Authorization": "Bearer sofya_live_..."},
    json={"query": "latest AI news", "search_depth": "basic"},
    timeout=90)  # longer than the server's limit, so you get its answer or error
print(resp.json())

// Node 18+: save as example.mjs (top-level await needs a module)
const resp = await fetch("https://mcp.sofya.co/v1/search", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Authorization": "Bearer sofya_live_..." },
  body: JSON.stringify({ query: "latest AI news", search_depth: "basic" })
});
console.log(await resp.json());

Fetch

Fetch up to 10 URLs in parallel and return their content as clean markdown. Works on web pages and documents: PDF, Word (DOCX, DOC), Excel (XLSX, XLS), PowerPoint (PPTX, PPT), OpenDocument, EPUB, RTF, CSV, XML and plain text. Costs 1 credit per URL that succeeds; a URL that fails comes back with success: false and is not charged.

Parameters

{
  "urls": ["https://example.com"],
  "include_raw_html": false
}

{
  "results": [
    {
      "title": "Example Page",
      "url": "https://example.com",
      "content": "# Markdown content...",
      "raw_html": null,
      "published_time": null,
      "success": true,
      "error": null,
      "low_content": false,
      "notice": null
    }
  ],
  "credits_used": 1,
  "credits_remaining": 1999
}

Response fields

Examples

curl -X POST https://mcp.sofya.co/v1/fetch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sofya_live_..." \
  -d '{"urls": ["https://example.com"]}'

import httpx

resp = httpx.post("https://mcp.sofya.co/v1/fetch",
    headers={"Authorization": "Bearer sofya_live_..."},
    json={"urls": ["https://example.com"]},
    timeout=90)
print(resp.json())

// Node 18+: save as example.mjs (top-level await needs a module)
const resp = await fetch("https://mcp.sofya.co/v1/fetch", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Authorization": "Bearer sofya_live_..." },
  body: JSON.stringify({ urls: ["https://example.com"] })
});
console.log(await resp.json());

Extract

Fetch a webpage and answer a question about it using AI. Costs 10 credits. content is a free-text answer (it is not JSON or structured output; ask for a format in your prompt if you need one). Only the first 50,000 characters of the page text are sent to the model.

If the page has under 40 characters of text (empty or JavaScript-rendered body), the model is not called and content is returned empty with usage.low_content: true rather than a fabricated answer. That is still a 200, but only 1 credit is charged, the cost of fetching the page; the rest is refunded. If the page itself can't be fetched (404, blocked, no DNS, timed out, refused URL), you get a 422 and are not charged.

Parameters

{
  "url": "https://example.com",
  "prompt": "List all pricing tiers with their monthly prices"
}

{
  "content": "Three tiers: Free ($0), Pro ($20/month), Team ($50/month).",
  "url": "https://example.com",
  "credits_used": 10,
  "credits_remaining": 1990,
  "usage": { "input_tokens": 1420, "output_tokens": 24, "content_chars": 4820, "low_content": false },
  "notice": null
}

usage.content_chars is the number of characters of page text the model received; usage.low_content is true when the page had under 40 characters of text (the model was skipped, content is empty, and only 1 credit is charged), and notice says why in plain words. Gate on these to detect empty or unrenderable pages.

Examples

curl -X POST https://mcp.sofya.co/v1/extract \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sofya_live_..." \
  -d '{"url": "https://example.com", "prompt": "Summarize this page"}'

import httpx

resp = httpx.post("https://mcp.sofya.co/v1/extract",
    headers={"Authorization": "Bearer sofya_live_..."},
    json={"url": "https://example.com", "prompt": "Summarize this page"},
    timeout=90)  # extract usually takes 10-20 s
print(resp.json())

// Node 18+: save as example.mjs (top-level await needs a module)
const resp = await fetch("https://mcp.sofya.co/v1/extract", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Authorization": "Bearer sofya_live_..." },
  body: JSON.stringify({ url: "https://example.com", prompt: "Summarize this page" })
});
console.log(await resp.json());

Research

Deep research on any topic. Decomposes your query into sub-queries, searches and reads multiple sources in parallel, then synthesizes a structured report with citations. Costs 50 credits. Research has a 55-second time limit (504, not charged); if no sources can be found the request fails and is not charged.

Each Key Findings bullet ends with an evidence tag: [Confirmed] (several sources agree), [Reported] (one source) or [Contested] (sources disagree). Sending the same research request again while the first is still running (same key, same query and options) does not start a second run: it waits for the first and returns its report with credits_used: 0.

Parameters

{
  "query": "How do modern LLMs handle long context?",
  "topic": "general",
  "freshness": null,
  "max_sources": 20
}

{
  "query": "How do modern LLMs handle long context?",
  "report": "## Key Findings\n\n- ...",
  "sources": [
    {
      "title": "Scaling Transformer Context Windows",
      "url": "https://arxiv.org/abs/...",
      "fetched": true,
      "published_date": "2026-09-14"
    }
  ],
  "sub_queries": [
    "transformer context window scaling techniques",
    "RoPE positional encoding extensions"
  ],
  "credits_used": 50,
  "credits_remaining": 1950,
  "usage": { "input_tokens": 12400, "output_tokens": 1850 }
}

Examples

curl -X POST https://mcp.sofya.co/v1/research \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sofya_live_..." \
  -d '{"query": "How do modern LLMs handle long context?"}'

import httpx

resp = httpx.post("https://mcp.sofya.co/v1/research",
    headers={"Authorization": "Bearer sofya_live_..."},
    json={"query": "How do modern LLMs handle long context?"},
    timeout=120)  # research usually takes 15-25 s
print(resp.json())

// Node 18+: save as example.mjs (top-level await needs a module)
const resp = await fetch("https://mcp.sofya.co/v1/research", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Authorization": "Bearer sofya_live_..." },
  body: JSON.stringify({ query: "How do modern LLMs handle long context?" })
});
console.log(await resp.json());

Errors

No error is charged, so after any error it is safe to retry once you've fixed the cause.

Error body

Errors return JSON with a detail field. It is a string, except for parameter errors (422), where it is a list with one entry per problem. Handle both.

{
  "detail": "Invalid API key"
}

{
  "detail": [
    {
      "type": "literal_error",
      "loc": ["body", "search_depth"],
      "msg": "Input should be 'snippets' or 'basic'"
    }
  ]
}

{
  "detail": "Insufficient credits. This costs 2 credit(s). You have 0. Buy credits at https://mcp.sofya.co/dashboard?topup=10, or create a payment link for your user with POST /v1/billing/topup (MCP tool: buy_credits).",
  "error": "insufficient_credits",
  "credits_required": 2,
  "credits_available": 0,
  "top_up_url": "https://mcp.sofya.co/dashboard?topup=10",
  "top_up_endpoint": "POST /v1/billing/topup"
}

Credits & billing

Every call is paid for in credits. One credit is $0.0025.

Buying credits: top up from the dashboard in whole dollars, from $10 (4,000 credits) up to $25,000. Purchased credits are not affected by the free-tier reset. An agent can make a payment link for you with POST /v1/billing/topup; you pay on that page.

Limits per key: in the dashboard, Limit on a key sets the most credits it can spend per calendar month (UTC). Past it, the key gets a 402 with "error": "key_cap_reached" until the 1st. Only you can change it, not an app using the key.

Free tier: accounts created by signing in with a GitHub account that is at least 1 year old get 2,000 credits, reset to 2,000 every 30 days. Unused free credits don't roll over, and they are spent before purchased credits. Linking GitHub to an existing email account does not add the free tier, and email (magic link) sign-ups start at 0 credits on pay-as-you-go.

What is charged: only a 2xx response, at exactly its credits_used. See Billing on errors.

Rate limits

Requests are rate limited to 30 requests per second per API key. REST (/v1/*) and MCP (/mcp) are counted separately, so each gets its own 30 per second.

If you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header giving the whole number of seconds to wait before retrying.

HTTP/1.1 429 Too Many Requests
Retry-After: 1

{
  "detail": "Rate limit exceeded. 30 requests per second."
}

Rate-limited requests do not consume credits. Wait the Retry-After seconds, then retry.

Every response to a request with an API key carries X-RateLimit-Limit (requests per second), X-RateLimit-Remaining (left in the current second) and X-RateLimit-Reset (seconds until the window frees up).

Every response also carries an X-Request-Id. Send your own (up to 64 letters, digits, . _ : -) and it is echoed back; otherwise one is generated. Quote it when you contact support.

Tool definitions for Claude & GPT

Building your own agent loop on the Anthropic or OpenAI API, without MCP? Paste these schemas as your tools, and when the model calls one, POST its arguments to the matching REST endpoint. The sofya_ prefix keeps them from clashing with your other tools: sofya_search is /v1/search, and so on. If your app supports MCP, connect it instead and skip this section; the MCP tools are named search, fetch, extract and research.

The blocks are long on purpose: copy the whole block, it's meant to be pasted, not read.

Anthropic (Claude)

Pass this array as the tools parameter in your /v1/messages request. When Claude returns a tool_use block, call the matching Sofya REST endpoint and return the result as a tool_result.

[
  {
    "name": "sofya_search",
    "description": "Search the web for current information. Returns extracted page content, not just snippets. Set topic='news' for current events. Set include_answer=true for an AI-synthesized answer (+2 credits). Returns: query (the query actually run), answer, results [{title, url, content, description, fetched, published_date, sublinks, table}], search_depth, topic, elapsed_ms, credits_used, credits_remaining, altered_query, relaxed_query (set when the query matched nothing and was retried once with its site: operator, else its quotes, removed - the results answer that looser query).",
    "input_schema": {
      "type": "object",
      "required": ["query"],
      "properties": {
        "query": {"type": "string", "description": "The search query"},
        "search_depth": {"type": "string", "enum": ["snippets", "basic"], "description": "\"snippets\" (1 credit) or \"basic\" (2, default)"},
        "max_results": {"type": "integer", "description": "Maximum number of results, 1-20 (default 10). Out-of-range values are clamped"},
        "include_answer": {"type": "boolean", "description": "Add AI answer synthesized from results (+2 credits)"},
        "topic": {"type": "string", "enum": ["general", "news"], "description": "\"general\" (default) or \"news\""},
        "freshness": {"type": "string", "description": "\"day\", \"week\", \"month\", \"year\", or \"YYYY-MM-DD:YYYY-MM-DD\""},
        "include_domains": {"type": "array", "items": {"type": "string"}, "description": "Only these domains, bare hostnames like github.com (max 10)"},
        "exclude_domains": {"type": "array", "items": {"type": "string"}, "description": "Exclude these domains, bare hostnames like pinterest.com (max 10)"}
      }
    }
  },
  {
    "name": "sofya_fetch",
    "description": "Fetch one or more URLs in parallel and return their content as clean markdown. Supports web pages, PDF, Word, Excel, PowerPoint, OpenDocument, EPUB, RTF, CSV, XML and plain text. 1 credit per URL, max 10 URLs. Failed URLs (success=false) are not charged. Returns: results [{title, url, content, raw_html, published_time, success, error, low_content, notice}], credits_used, credits_remaining.",
    "input_schema": {
      "type": "object",
      "required": ["urls"],
      "properties": {
        "urls": {"type": "array", "items": {"type": "string"}, "description": "URLs to fetch (max 10)"},
        "include_raw_html": {"type": "boolean", "description": "Include raw HTML source in response (default false)"}
      }
    }
  },
  {
    "name": "sofya_extract",
    "description": "Fetch a URL and answer a question about it using AI. Use when you need specific facts from a page (pricing, specs, contact info) rather than its full content. Returns a free-text answer, not structured JSON. 10 credits. If the page has under 40 chars of text it returns empty content with usage.low_content=true instead of a fabricated answer, and only 1 credit is charged. Returns: content, url, credits_used, credits_remaining, usage (input_tokens, output_tokens, content_chars, low_content), notice (null unless there was no answer).",
    "input_schema": {
      "type": "object",
      "required": ["url", "prompt"],
      "properties": {
        "url": {"type": "string", "description": "The URL to extract from"},
        "prompt": {"type": "string", "description": "What to extract, e.g. \"list all pricing tiers with features\""}
      }
    }
  },
  {
    "name": "sofya_research",
    "description": "Deep research on a topic. Decomposes query into sub-queries, searches and reads multiple sources in parallel, synthesizes a structured report with citations. 50 credits. Returns: query, report, sources [{title, url, fetched, published_date}], sub_queries, credits_used, credits_remaining, usage.",
    "input_schema": {
      "type": "object",
      "required": ["query"],
      "properties": {
        "query": {"type": "string", "description": "The research question or topic"},
        "topic": {"type": "string", "enum": ["general", "news"], "description": "\"general\" (default) or \"news\""},
        "freshness": {"type": "string", "description": "\"day\", \"week\", \"month\", \"year\", or \"YYYY-MM-DD:YYYY-MM-DD\""},
        "max_sources": {"type": "integer", "description": "Max sources to use, 5-30 (default 20). Out-of-range values are clamped"}
      }
    }
  }
]

OpenAI (GPT)

Pass this array as the tools parameter in your /chat/completions request. When the model returns tool_calls, call the matching Sofya REST endpoint and return the result as a role: "tool" message.

[
  {
    "type": "function",
    "function": {
      "name": "sofya_search",
      "description": "Search the web for current information. Returns extracted page content, not just snippets. Set topic='news' for current events. Set include_answer=true for an AI-synthesized answer (+2 credits). Returns: query (the query actually run), answer, results [{title, url, content, description, fetched, published_date, sublinks, table}], search_depth, topic, elapsed_ms, credits_used, credits_remaining, altered_query, relaxed_query (set when the query matched nothing and was retried once with its site: operator, else its quotes, removed - the results answer that looser query).",
      "parameters": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": {"type": "string", "description": "The search query"},
          "search_depth": {"type": "string", "enum": ["snippets", "basic"], "description": "\"snippets\" (1 credit) or \"basic\" (2, default)"},
          "max_results": {"type": "integer", "description": "Maximum number of results, 1-20 (default 10). Out-of-range values are clamped"},
          "include_answer": {"type": "boolean", "description": "Add AI answer synthesized from results (+2 credits)"},
          "topic": {"type": "string", "enum": ["general", "news"], "description": "\"general\" (default) or \"news\""},
          "freshness": {"type": "string", "description": "\"day\", \"week\", \"month\", \"year\", or \"YYYY-MM-DD:YYYY-MM-DD\""},
          "include_domains": {"type": "array", "items": {"type": "string"}, "description": "Only these domains, bare hostnames like github.com (max 10)"},
          "exclude_domains": {"type": "array", "items": {"type": "string"}, "description": "Exclude these domains, bare hostnames like pinterest.com (max 10)"}
        },
        "additionalProperties": false
      }
    }
  },
  {
    "type": "function",
    "function": {
      "name": "sofya_fetch",
      "description": "Fetch one or more URLs in parallel and return their content as clean markdown. Supports web pages, PDF, Word, Excel, PowerPoint, OpenDocument, EPUB, RTF, CSV, XML and plain text. 1 credit per URL, max 10 URLs. Failed URLs (success=false) are not charged. Returns: results [{title, url, content, raw_html, published_time, success, error, low_content, notice}], credits_used, credits_remaining.",
      "parameters": {
        "type": "object",
        "required": ["urls"],
        "properties": {
          "urls": {"type": "array", "items": {"type": "string"}, "description": "URLs to fetch (max 10)"},
          "include_raw_html": {"type": "boolean", "description": "Include raw HTML source in response (default false)"}
        },
        "additionalProperties": false
      }
    }
  },
  {
    "type": "function",
    "function": {
      "name": "sofya_extract",
      "description": "Fetch a URL and answer a question about it using AI. Use when you need specific facts from a page (pricing, specs, contact info) rather than its full content. Returns a free-text answer, not structured JSON. 10 credits. If the page has under 40 chars of text it returns empty content with usage.low_content=true instead of a fabricated answer, and only 1 credit is charged. Returns: content, url, credits_used, credits_remaining, usage (input_tokens, output_tokens, content_chars, low_content), notice (null unless there was no answer).",
      "parameters": {
        "type": "object",
        "required": ["url", "prompt"],
        "properties": {
          "url": {"type": "string", "description": "The URL to extract from"},
          "prompt": {"type": "string", "description": "What to extract, e.g. \"list all pricing tiers with features\""}
        },
        "additionalProperties": false
      }
    }
  },
  {
    "type": "function",
    "function": {
      "name": "sofya_research",
      "description": "Deep research on a topic. Decomposes query into sub-queries, searches and reads multiple sources in parallel, synthesizes a structured report with citations. 50 credits. Returns: query, report, sources [{title, url, fetched, published_date}], sub_queries, credits_used, credits_remaining, usage.",
      "parameters": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": {"type": "string", "description": "The research question or topic"},
          "topic": {"type": "string", "enum": ["general", "news"], "description": "\"general\" (default) or \"news\""},
          "freshness": {"type": "string", "description": "\"day\", \"week\", \"month\", \"year\", or \"YYYY-MM-DD:YYYY-MM-DD\""},
          "max_sources": {"type": "integer", "description": "Max sources to use, 5-30 (default 20). Out-of-range values are clamped"}
        },
        "additionalProperties": false
      }
    }
  }
]

Example: wiring it up

When the model calls a tool, map the tool name to the Sofya endpoint and forward the arguments:

# Python - handle tool calls from Claude or GPT
TOOL_TO_ENDPOINT = {
    "sofya_search": "/v1/search",
    "sofya_fetch": "/v1/fetch",
    "sofya_extract": "/v1/extract",
    "sofya_research": "/v1/research",
}

def call_sofya(tool_name: str, args: dict) -> dict:
    import httpx
    resp = httpx.post(
        f"https://mcp.sofya.co{TOOL_TO_ENDPOINT[tool_name]}",
        headers={"Authorization": "Bearer sofya_live_..."},
        json=args,
        timeout=120,
    )
    return resp.json()

Agent sign-up

An agent with no key can get one, with you approving it. The agent asks for a code, you open the link it shows, sign in or create an account, and approve. The agent then receives an ordinary API key, tagged Agent in your dashboard, where you can limit or revoke it. Neither call needs a key. The same flow is described for agents at /auth.md.

curl -X POST https://mcp.sofya.co/v1/agent/signup \
  -H "Content-Type: application/json" \
  -d '{"client_name": "My agent", "login_hint": "you@example.com"}'

{
  "claim_token": "clm_...",
  "user_code": "BCDF-GHJK",
  "verification_uri": "https://mcp.sofya.co/device",
  "verification_uri_complete": "https://mcp.sofya.co/device?code=BCDF-GHJK",
  "expires_in": 900,
  "interval": 5,
  "token_endpoint": "https://mcp.sofya.co/v1/agent/token"
}

Both fields are optional: client_name is shown to you on the approval page, and login_hint is the email the agent expects you to use. The response also has the same values under claim and as device_code, for agents that follow auth.md or OAuth device flow. Then the agent polls every interval seconds:

curl -X POST https://mcp.sofya.co/v1/agent/token \
  -H "Content-Type: application/json" \
  -d '{"claim_token": "clm_..."}'

{
  "error": "authorization_pending",
  "interval": 5
}

{
  "api_key": "sofya_live_...",
  "access_token": "sofya_live_...",
  "token_type": "Bearer",
  "key_id": "uuid",
  "key_name": "My agent",
  "account": "you@example.com",
  "credits": 0,
  "monthly_credit_cap": null,
  "message": "..."
}

Other poll errors: slow_down (poll less often), access_denied (you declined), expired_token (the 15 minutes ran out; start again). The key is returned once. The poll also works as an OAuth token request on /oauth/token with grant_type=urn:workos:agent-auth:grant-type:claim or urn:ietf:params:oauth:grant-type:device_code.

Balance and payment links

With an API key, an agent can check the balance and make a payment link for you. Nothing is charged until you pay on the Stripe page the link opens. The credits are added as soon as the payment goes through. Both calls are free.

curl -X POST https://mcp.sofya.co/v1/billing/topup \
  -H "Authorization: Bearer sofya_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 10}'

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
  "amount_usd": 10,
  "credits": 4000,
  "expires_in": 86400,
  "message": "Open this link to pay. Credits are added to the account as soon as the payment goes through."
}

amount_usd is whole US dollars, $10 to $25,000. The link works for 24 hours. At most 20 links per account per hour (429 after that).

{
  "credits": 3994,
  "plan_credits": 0,
  "purchased_credits": 3994,
  "credits_reset_at": null,
  "key_monthly_cap": 5000,
  "key_credits_used_this_month": 6,
  "credits_per_usd": 400,
  "min_topup_usd": 10,
  "max_topup_usd": 25000,
  "top_up_url": "https://mcp.sofya.co/dashboard?topup=10"
}

key_monthly_cap and key_credits_used_this_month are about the key you called with; the cap is null when there is none.

Me

Get your account info: credit balance, tier and total requests. Free.

{
  "credits": 1994,
  "plan_credits": 1994,
  "purchased_credits": 0,
  "is_free_tier": true,
  "credits_reset_at": "2026-11-04T12:00:00Z",
  "total_requests": 3,
  "api_key": null,
  "last_login_method": "github",
  "email": "user@example.com",
  "email_verified": true,
  "github_username": "octocat",
  "has_billing_portal": false,
  "new_ip_alerts_enabled": true,
  "low_balance_alerts_enabled": true,
  "low_balance_threshold": null,
  "low_balance_threshold_auto": 1000
}

Transactions

Get your last 50 top-ups and account adjustments, newest first. Per-request charges and refunds are not listed here; use usage for those.

[
  {
    "id": "uuid",
    "type": "credit",
    "amount": 4000,
    "endpoint": "top-up",
    "balance_after": 5994,
    "created_at": "2026-10-08T12:00:00Z",
    "has_receipt": true,
    "amount_usd_cents": 1000
  }
]

type is credit or debit. amount_usd_cents is what was actually charged (negative for refunds and disputes) and null for adjustments; don't work out dollars from credits, since older top-ups were sold at a different rate. has_receipt is true for paid top-ups.

Usage

Get your daily usage breakdown. Rows are per day, endpoint and API key, newest day first, so one day can have several rows for the same endpoint if you use more than one key. Each row names its key in api_key_id and api_key_name; both are null for rows not tied to a key (older usage, and searches on search.sofya.co).

Query parameters

curl "https://mcp.sofya.co/v1/auth/usage?days=30" \
  -H "Authorization: Bearer sofya_live_..."

[
  {
    "date": "2026-10-08",
    "endpoint": "/v1/search",
    "request_count": 3,
    "total_credits": 6,
    "api_key_id": "4505fa6c-edff-eff6-7aa9-547504df43ee",
    "api_key_name": "Production"
  }
]

Status & monitoring

Per-endpoint health: GET /v1/status (no API key) reports the health of search, fetch, extract and research as measured by Sofya itself.

{
  "overall": "operational",
  "endpoints": {
    "search": { "status": "operational", "latency_ms": 1905.9, "last_check": "2026-10-09T14:00:27+00:00" },
    "fetch": { "status": "operational", "latency_ms": 4116.3, "last_check": "2026-10-09T13:59:47+00:00" },
    "extract": { "status": "operational", "latency_ms": 14693.6, "last_check": "2026-10-09T13:59:18+00:00" },
    "research": { "status": "operational", "latency_ms": 17904.2, "last_check": "2026-10-09T13:59:18+00:00" },
    "mcp": { "status": "operational", "latency_ms": null, "last_check": "2026-10-09T13:58:41+00:00" }
  },
  "incidents": []
}

Changelog: GET /v1/updates (no API key) returns the list of user-facing changes as JSON.

Website status: status.sofya.co runs on a separate server and checks the website (sofya.co) every 60 seconds, so it keeps reporting even if Sofya itself is down. It does not probe the individual API endpoints; use /v1/status for those. Its feeds are public, no API key needed.

status.sofya.co JSON feeds

• /api/v2/summary.json - Atlassian Statuspage-compatible, for tools that already read Statuspage feeds.
• /api/v2/status.json - Page metadata and overall indicator only. Cheapest poll if you only need up/down.
• /api/status.json - Richer feed: last latency, 24h and 90d uptime, last error.

$ curl https://status.sofya.co/api/v2/status.json
{
  "page": { "id": "sofya", "name": "Sofya Status", "url": "https://status.sofya.co", "time_zone": "Etc/UTC", "updated_at": "2026-10-09T14:00:30+00:00" },
  "status": {
    "indicator": "none",
    "description": "All Systems Operational"
  }
}

The indicator field follows the Statuspage convention: none (operational), minor (degraded), or major (down).