Sofya

Una API que proporciona a los agentes de IA herramientas de búsqueda web, obtención de páginas como markdown, extracción de IA e investigación profunda.

Ver en sofya.coPrueba este MCPPatrocinado

Documentación

Documentación de la API

Todo lo que necesitas para integrar Sofya en tu agente de IA.

llms.txt · SKILL.md

Copiar como Markdown

Copiar como Texto

Inicio rápido

2. Obtén créditos

Las cuentas de GitHub elegibles obtienen 1,000 créditos/mes en el plan gratuito. ¿Necesitas más? Compra créditos a $0.005 cada uno.

3. Busca en la web

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

Autenticación

Todas las solicitudes a la API requieren una clave de API en el encabezado Authorization.

Authorization: Bearer ay_live_your_key_here

MCP Protocolo de Contexto de Modelo

Conecta Sofya directamente a Claude Code, Cursor o cualquier cliente compatible con MCP. Tu agente de IA obtiene herramientas de búsqueda, extracción, recuperación e investigación, sin necesidad de llamadas REST.

Ve a tu panel de control y haz clic en el botón de copiar para tu cliente. El comando viene prellenado con tu clave de API.

Claude Code

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

Cursor · ~/.cursor/mcp.json

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

Codex · ~/.codex/config.toml

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

Windsurf · ~/.codeium/windsurf/mcp_config.json

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

VS Code Copilot ·.vscode/mcp.json

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

Tu clave de API se envía mediante un encabezado HTTP. El modelo de IA nunca la ve.

Herramientas disponibles

Búsqueda web con extracción de contenido de páginas y respuestas opcionales de IA. 1-3 créditos (+5 con respuesta de IA).

fetch

Recupera URLs como markdown limpio. 1 crédito por URL.

extract

Extracción de datos estructurados impulsada por IA. 5 créditos.

research

Investigación profunda con múltiples consultas y síntesis de IA. 25 créditos.

Definiciones de herramientas para Claude y GPT

Copia y pega estos esquemas de herramientas en tus llamadas a la API de Anthropic u OpenAI. Tu modelo obtiene las herramientas de Sofya sin necesidad de escribir definiciones tú mismo.

Anthropic (Claude)

Pasa este array como el parámetro tools en tu solicitud /v1/messages. Cuando Claude devuelva un bloque tool_use, llama al endpoint REST correspondiente de Sofya y devuelve el resultado como un 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 (+5 credits). Returns: query, answer, results [{title, url, content, description, fetched, published_date}], search_depth, topic, elapsed_ms, credits_used, credits_remaining, altered_query.",
    "input_schema": {
      "type": "object",
      "required": ["query"],
      "properties": {
        "query": {"type": "string", "description": "The search query"},
        "search_depth": {"type": "string", "description": "\"snippets\" (1 credit) or \"basic\" (3, default)"},
        "max_results": {"type": "integer", "description": "Number of results, 1-20 (default 10)"},
        "include_answer": {"type": "boolean", "description": "Add AI answer synthesized from results (+5 credits)"},
        "topic": {"type": "string", "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 (max 10)"},
        "exclude_domains": {"type": "array", "items": {"type": "string"}, "description": "Exclude these domains (max 10)"}
      }
    }
  },
  {
    "name": "sofya_fetch",
    "description": "Fetch one or more URLs and return their content as clean markdown. Supports web pages, PDF, DOCX, and other document formats. 1 credit per URL, max 10 URLs. Failed URLs are not charged. Returns: results [{title, url, content, raw_html, published_time, success, error}], 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 extract specific information using AI. Use when you need structured data (pricing, specs, contact info) rather than raw content. 5 credits. If the page has no usable text it returns empty content with usage.low_content=true instead of a fabricated answer. Returns: content, url, credits_used, credits_remaining, usage (input_tokens, output_tokens, content_chars, low_content).",
    "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. 25 credits. Returns: query, report, sources [{title, url, fetched}], 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", "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)"}
      }
    }
  }
]

OpenAI (GPT)

Pasa este array como el parámetro tools en tu solicitud /chat/completions. Cuando el modelo devuelva tool_calls, llama al endpoint REST correspondiente de Sofya y devuelve el resultado como un mensaje role: "tool".

[
  {
    "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 (+5 credits). Returns: query, answer, results [{title, url, content, description, fetched, published_date}], search_depth, topic, elapsed_ms, credits_used, credits_remaining, altered_query.",
      "parameters": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": {"type": "string", "description": "The search query"},
          "search_depth": {"type": "string", "description": "\"snippets\" (1 credit) or \"basic\" (3, default)"},
          "max_results": {"type": "integer", "description": "Number of results, 1-20 (default 10)"},
          "include_answer": {"type": "boolean", "description": "Add AI answer synthesized from results (+5 credits)"},
          "topic": {"type": "string", "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 (max 10)"},
          "exclude_domains": {"type": "array", "items": {"type": "string"}, "description": "Exclude these domains (max 10)"}
        },
        "additionalProperties": false
      }
    }
  },
  {
    "type": "function",
    "function": {
      "name": "sofya_fetch",
      "description": "Fetch one or more URLs and return their content as clean markdown. Supports web pages, PDF, DOCX, and other document formats. 1 credit per URL, max 10 URLs. Failed URLs are not charged. Returns: results [{title, url, content, raw_html, published_time, success, error}], 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 extract specific information using AI. Use when you need structured data (pricing, specs, contact info) rather than raw content. 5 credits. If the page has no usable text it returns empty content with usage.low_content=true instead of a fabricated answer. Returns: content, url, credits_used, credits_remaining, usage (input_tokens, output_tokens, content_chars, low_content).",
      "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. 25 credits. Returns: query, report, sources [{title, url, fetched}], 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", "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)"}
        },
        "additionalProperties": false
      }
    }
  }
]

Ejemplo: conexión

Cuando el modelo llama a una herramienta, asigna el nombre de la herramienta al endpoint de Sofya y reenvía los argumentos:

# 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://sofya.co{TOOL_TO_ENDPOINT[tool_name]}",
        headers={"Authorization": "Bearer ay_live_..."},
        json=args,
        timeout=120,
    )
    return resp.json()

Herramientas principales

POST /v1/search 1-3 créditos (+5 con respuesta)

Busca en la web. Devuelve el contenido de la página, no solo fragmentos. Elige una profundidad de búsqueda para controlar la relación calidad/costo. Añade include_answer a cualquier profundidad para obtener una respuesta sintetizada por IA (+5 créditos). Esta es una alternativa ligera al endpoint de investigación de 25 créditos.

snippets 1 crédito

Solo fragmentos de SERP. Más rápido.

basic 3 créditos (predeterminado)

Recupera páginas y devuelve contenido extraído (~5000 caracteres por resultado).

Cuerpo de la solicitud

{
  "query": "string",              // required
  "search_depth": "basic",        // "snippets" or "basic"
  "max_results": 10,               // 1-20
  "include_answer": false,         // AI answer from results (+5 credits). Combine with any depth for search + synthesis (e.g. basic = 8 credits)
  "include_domains": [],           // e.g. ["reddit.com", "github.com"]
  "exclude_domains": [],           // e.g. ["pinterest.com"]
  "topic": "general",             // "general" or "news"
  "freshness": null               // "day", "week", "month", "year", or "YYYY-MM-DD:YYYY-MM-DD"
}

Respuesta

{
  "query": "latest AI news",
  "answer": "According to...",     // null unless include_answer
  "results": [
    {
      "title": "...",
      "url": "...",
      "content": "Extracted page content...",
      "description": "SERP snippet",
      "fetched": true,             // true if page was fetched, false if snippet only
      "published_date": "2026-03-08",  // YYYY-MM-DD, normalized from page metadata or SERP (or null)
      "sublinks": [],
      "table": {}
    }
  ],
  "search_depth": "basic",
  "topic": "general",
  "elapsed_ms": 4200,
  "credits_used": 3,
  "credits_remaining": 997,
  "altered_query": null            // if the query was auto-corrected
}

topic: "general" (predeterminado) para búsqueda web, o "news" para búsqueda específica de noticias. Usa "news" para eventos actuales, noticias de última hora, política o cualquier consulta sensible al tiempo. Devuelve artículos con fechas de publicación.

freshness: "day", "week", "month", "year" o rango personalizado "YYYY-MM-DD:YYYY-MM-DD"

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

import httpx

resp = httpx.post("https://sofya.co/v1/search",
    headers={"Authorization": "Bearer ay_live_..."},
    json={"query": "latest AI news", "search_depth": "basic"})
print(resp.json())

const resp = await fetch("https://sofya.co/v1/search", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Authorization": "Bearer ay_live_..." },
  body: JSON.stringify({ query: "latest AI news", search_depth: "basic" })
});
console.log(await resp.json());

POST /v1/fetch 1 crédito por URL

Recupera una o más URLs y devuelve su contenido como markdown limpio.

Cuerpo de la solicitud

{
  "urls": ["string", ...],       // required, max 10
  "include_raw_html": false      // optional - include raw HTML source
}

Respuesta

{
  "results": [
    {
      "title": "Example Page",
      "url": "https://example.com",
      "content": "# Markdown content...",
      "raw_html": null,
      "published_time": null,           // YYYY-MM-DD, extracted from page metadata when available (or null)
      "success": true,
      "error": null
    }
  ],
  "credits_used": 1,
  "credits_remaining": 999
}

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

import httpx

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

const resp = await fetch("https://sofya.co/v1/fetch", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Authorization": "Bearer ay_live_..." },
  body: JSON.stringify({ urls: ["https://example.com"] })
});
console.log(await resp.json());

POST /v1/extract 5 créditos

Recupera una página web y extrae información específica usando IA. Cuesta 5 créditos. Si la página no tiene texto utilizable (cuerpo vacío o renderizado con JavaScript), el modelo no se llama y content se devuelve vacío con usage.low_content: true en lugar de una respuesta inventada.

Cuerpo de la solicitud

{
  "url": "string",          // required
  "prompt": "string"        // required, what to extract
}

Respuesta

{
  "content": "Extracted information...",
  "url": "https://example.com",
  "credits_used": 5,
  "credits_remaining": 995,
  "usage": { "input_tokens": 90, "output_tokens": 24, "content_chars": 4820, "low_content": false }
}

usage.content_chars es el número de caracteres de texto de la página que recibió el modelo; usage.low_content es verdadero cuando la página tenía muy poco texto para extraer (el modelo se omitió). Usa estos campos para detectar páginas vacías o no renderizables.

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

import httpx

resp = httpx.post("https://sofya.co/v1/extract",
    headers={"Authorization": "Bearer ay_live_..."},
    json={"url": "https://example.com", "prompt": "Summarize this page"})
print(resp.json())

const resp = await fetch("https://sofya.co/v1/extract", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Authorization": "Bearer ay_live_..." },
  body: JSON.stringify({ url: "https://example.com", prompt: "Summarize this page" })
});
console.log(await resp.json());

POST /v1/research 25 créditos

Investigación profunda sobre cualquier tema. Descompone tu consulta en subconsultas, busca y lee múltiples fuentes en paralelo, y luego sintetiza un informe estructurado con citas. Cuesta 25 créditos.

Cuerpo de la solicitud

{
  "query": "string",              // required
  "topic": "general",             // "general" or "news"
  "freshness": null,              // "day", "week", "month", "year", or "YYYY-MM-DD:YYYY-MM-DD"
  "max_sources": 20               // 5-30
}

Respuesta

{
  "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
    }
  ],
  "sub_queries": [
    "transformer context window scaling techniques",
    "RoPE positional encoding extensions"
  ],
  "credits_used": 25,
  "credits_remaining": 975,
  "usage": { "input_tokens": 12400, "output_tokens": 1850 }
}

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

import httpx

resp = httpx.post("https://sofya.co/v1/research",
    headers={"Authorization": "Bearer ay_live_..."},
    json={"query": "How do modern LLMs handle long context?"},
    timeout=120)
print(resp.json())

const resp = await fetch("https://sofya.co/v1/research", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Authorization": "Bearer ay_live_..." },
  body: JSON.stringify({ query: "How do modern LLMs handle long context?" })
});
console.log(await resp.json());

Cuenta

GET /v1/auth/me

Obtén la información de tu cuenta, incluidos créditos, plan y solicitudes totales.

Respuesta

{
  "credits": 997,
  "plan_credits": 997,
  "purchased_credits": 0,
  "is_free_tier": true,
  "credits_reset_at": "2026-04-04T12:00:00Z",
  "total_requests": 3,
  "api_key": "ay_live_...",
  "last_login_method": "github",
  "email": "user@example.com",
  "github_username": "octocat"
}

GET /v1/auth/transactions

Obtén tus transacciones de crédito recientes (recargas). Devuelve las últimas 50.

Respuesta

[
  {
    "id": "uuid",
    "type": "credit",
    "amount": 5000,
    "endpoint": "top-up",
    "balance_after": 6000,
    "created_at": "2026-02-22T12:00:00Z"
  }
]

GET /v1/auth/usage

Obtén el desglose de tu uso diario, por endpoint.

Parámetros de consulta

days=7           // 1-90, default 7
offset_days=0    // pagination offset in days

Respuesta

[
  {
    "date": "2026-02-22",
    "endpoint": "/v1/search",
    "request_count": 312,
    "total_credits": 312
  }
]

Facturación

POST /v1/billing/checkout

Compra créditos (PAYG). Compra mínima: 2,000 créditos ($10). Redirige a la página de pago.

Cuerpo de la solicitud

{
  "credits": 5000           // required, minimum ~2000
}

Respuesta

{
  "checkout_url": "https://checkout.creem.io/pay/..."
}

Límites de velocidad

Los endpoints de la API REST están limitados a 10 solicitudes por segundo por clave de API. Esto aplica a todos los endpoints /v1/*. MCP (/mcp) está limitado a 30 solicitudes por segundo.

Si superas el límite, la API devuelve 429 Too Many Requests con un encabezado Retry-After que indica cuántos segundos esperar antes de reintentar.

Respuesta 429

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

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

Las solicitudes limitadas no consumen créditos. Implementa retroceso exponencial o respeta el encabezado Retry-After para obtener mejores resultados.

Códigos de error

Código	Estado	Descripción
400	Solicitud incorrecta	Parámetros no válidos (por ejemplo, consulta faltante, formato de freshness incorrecto)
401	No autorizado	Clave de API no válida o faltante
402	Pago requerido	Créditos insuficientes
403	Prohibido	Prohibido
429	Demasiadas solicitudes	Límite de velocidad alcanzado. Consulta el encabezado `Retry-After`.
502	Puerta de enlace incorrecta	Error interno. Reintenta la solicitud.
504	Tiempo de espera de la puerta de enlace	La investigación agotó el tiempo. Prueba con una consulta más simple o menos fuentes.

Estado y monitoreo

La página de estado pública de Sofya se aloja fuera del servidor en status.sofya.co. Sondea la API cada 60 segundos desde un servidor separado para que siga informando con precisión incluso si Sofya está caída. Todos los feeds son públicos, no se necesita clave de API.

Feeds JSON

/api/v2/summary.json — Compatible con Atlassian Statuspage. Reemplazo directo para cualquier herramienta que ya lea status.anthropic.com, estado de GitHub, etc.
/api/v2/status.json — Solo metadatos de la página e indicador general. Sondeo más económico si solo necesitas saber si está activo o caído.
/api/status.json — Feed más rico nativo de Sofya: latencia por componente, tiempo de actividad de 24 h / 90 días, último error.

Ejemplo

$ curl https://status.sofya.co/api/v2/status.json
{
  "page": { "id": "sofya", "name": "Sofya Status", ... },
  "status": {
    "indicator": "none",
    "description": "All Systems Operational"
  }
}

El campo indicator sigue la convención de Statuspage: none (operativo), minor (degradado) o major (caído). Trata cualquier valor que no sea none como motivo para mostrar un aviso a tus usuarios o reducir los reintentos. # Documentación de la API de Sofya

URL base: https://sofya.co\

Inicio rápido

1. Regístrate a través de GitHub

Visita el panel de control e inicia sesión con GitHub para comenzar.

2. Obtén créditos

Las cuentas de GitHub elegibles obtienen 1,000 créditos al mes en el plan gratuito. ¿Necesitas más? Compra créditos a $0.005 cada uno desde el panel de control.

3. Busca en la web

\``bash curl -X POST https://sofya.co/v1/search \\ -H "Authorization: Bearer ay\_live\_..." \\ -H "Content-Type: application/json" \\ -d '{"query": "latest AI news"}' \``\

Autenticación

Todas las solicitudes a la API requieren una clave de API en el encabezado Authorization\.

\`` Authorization: Bearer ay\_live\_your\_key\_here \``\

MCP (Protocolo de Contexto de Modelo)

Conecta Sofya directamente a Claude Code, Cursor o cualquier cliente compatible con MCP. Tu agente de IA obtiene herramientas de búsqueda, recuperación, extracción e investigación, sin necesidad de llamadas REST. Ve a tu panel de control y haz clic en el botón de copiar para tu cliente. El comando viene prellenado con tu clave de API.

Claude Code

\``bash claude mcp add --transport http sofya https://mcp.sofya.co/mcp \\ --header "Authorization: Bearer ay\_live\_..." \``\

Cursor (`~/.cursor/mcp.json\`)

\``json { "mcpServers": { "sofya": { "url": "https://mcp.sofya.co/mcp", "headers": { "Authorization": "Bearer ay\_live\_..." } } } } \``\

Codex (`~/.codex/config.toml\`)

\``toml \[mcp\_servers.sofya\] url = "https://mcp.sofya.co/mcp" http\_headers = { "Authorization" = "Bearer ay\_live\_..." } \``\

Windsurf (`~/.codeium/windsurf/mcp\_config.json\`)

\``json { "mcpServers": { "sofya": { "serverUrl": "https://mcp.sofya.co/mcp", "headers": { "Authorization": "Bearer ay\_live\_..." } } } } \``\

VS Code Copilot (`.vscode/mcp.json\`)

\``json { "servers": { "sofya": { "type": "http", "url": "https://mcp.sofya.co/mcp", "headers": { "Authorization": "Bearer ay\_live\_..." } } } } \``\

Tu clave de API se envía a través del encabezado HTTP. El modelo de IA nunca la ve.

**Herramientas disponibles:**

search\ · Búsqueda web con extracción de contenido de páginas. 1-3 créditos, +5 con include\_answer: true\ para una respuesta sintetizada por IA. Esta es una alternativa ligera al endpoint de investigación completo.
fetch\ · Recupera URLs como markdown limpio. 1 crédito por URL.
extract\ · Extracción de datos estructurados impulsada por IA. 5 créditos.
research\ · Investigación profunda de múltiples consultas con síntesis de IA. 25 créditos.

Herramientas principales

POST /v1/search · 1-3 créditos (+5 con respuesta de IA)

Busca en la web. Devuelve el contenido de las páginas, no solo fragmentos. Elige una profundidad de búsqueda para controlar el equilibrio entre calidad y costo.

Profundidad	Créditos	Descripción
snippets	1	Solo fragmentos de SERP. Más rápido.
basic	3	Recupera páginas, devuelve contenido extraído (~5000 caracteres por resultado). Predeterminado.

**Consejo:** Agrega include\_answer: true\ a cualquier profundidad para obtener una respuesta sintetizada por IA (+5 créditos). Por ejemplo, basic + answer = 8 créditos. Esta es una alternativa ligera al endpoint de investigación de 25 créditos cuando necesitas una síntesis rápida sin descomposición de múltiples consultas.

**Solicitud:** \``json { "query": "string", "search\_depth": "basic", "max\_results": 10, "include\_answer": false, "include\_domains": \[\], "exclude\_domains": \[\], "topic": "general", "freshness": null } \``\

**Respuesta:** \``json { "query": "latest AI news", "answer": null, "results": \[ { "title": "...", "url": "...", "content": "Extracted page content...", "description": "SERP snippet", "fetched": true, "published\_date": "2026-03-08", "sublinks": \[\], "table": {} } \], "search\_depth": "basic", "topic": "general", "elapsed\_ms": 4200, "credits\_used": 3, "credits\_remaining": 997, "altered\_query": null } \``\

**curl:** \``bash curl -X POST https://sofya.co/v1/search \\ -H "Content-Type: application/json" \\ -H "Authorization: Bearer ay\_live\_..." \\ -d '{"query": "latest AI news", "search\_depth": "basic"}' \``\

**Python:** \``python import httpx resp = httpx.post("https://sofya.co/v1/search", headers={"Authorization": "Bearer ay\_live\_..."}, json={"query": "latest AI news", "search\_depth": "basic"}) print(resp.json()) \``\

**JavaScript:** \``javascript const resp = await fetch("https://sofya.co/v1/search", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": "Bearer ay\_live\_..." }, body: JSON.stringify({ query: "latest AI news", search\_depth: "basic" }) }); console.log(await resp.json()); \``\

POST /v1/fetch · 1 crédito por URL

Recupera una o más URLs y devuelve su contenido como markdown limpio. Máximo 10 URLs por solicitud. Las URLs fallidas no se cobran.

**Solicitud:** \``json { "urls": \["string",...\], "include\_raw\_html": false } \``\

**Respuesta:** \``json { "results": \[ { "title": "Example Page", "url": "https://example.com", "content": "# Markdown content...", "raw\_html": null, "published\_time": null, // YYYY-MM-DD, extracted from page metadata when available (or null) "success": true, "error": null } \], "credits\_used": 1, "credits\_remaining": 999 } \``\

**curl:** \``bash curl -X POST https://sofya.co/v1/fetch \\ -H "Content-Type: application/json" \\ -H "Authorization: Bearer ay\_live\_..." \\ -d '{"urls": \["https://example.com"\]}' \``\

**Python:** \``python import httpx resp = httpx.post("https://sofya.co/v1/fetch", headers={"Authorization": "Bearer ay\_live\_..."}, json={"urls": \["https://example.com"\]}) print(resp.json()) \``\

**JavaScript:** \``javascript const resp = await fetch("https://sofya.co/v1/fetch", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": "Bearer ay\_live\_..." }, body: JSON.stringify({ urls: \["https://example.com"\] }) }); console.log(await resp.json()); \``\

POST /v1/extract · 5 créditos

Recupera una página web y extrae información específica usando IA. Cuesta 5 créditos.

**Solicitud:** \``json { "url": "string", "prompt": "string" } \``\

**Respuesta:** \``json { "content": "Extracted information...", "url": "https://example.com", "credits\_used": 5, "credits\_remaining": 995, "usage": { "input\_tokens": 90, "output\_tokens": 24 } } \``\

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

**Python:** \``python import httpx resp = httpx.post("https://sofya.co/v1/extract", headers={"Authorization": "Bearer ay\_live\_..."}, json={"url": "https://example.com", "prompt": "Summarize this page"}) print(resp.json()) \``\

**JavaScript:** \``javascript const resp = await fetch("https://sofya.co/v1/extract", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": "Bearer ay\_live\_..." }, body: JSON.stringify({ url: "https://example.com", prompt: "Summarize this page" }) }); console.log(await resp.json()); \``\

POST /v1/research · 25 créditos

**Solicitud:** \``json { "query": "string", "topic": "general", "freshness": null, "max\_sources": 20 } \``\

**Respuesta:** \``json { "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 } \], "sub\_queries": \[ "transformer context window scaling techniques", "RoPE positional encoding extensions" \], "credits\_used": 25, "credits\_remaining": 975, "usage": { "input\_tokens": 12400, "output\_tokens": 1850 } } \``\

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

**Python:** \``python import httpx resp = httpx.post("https://sofya.co/v1/research", headers={"Authorization": "Bearer ay\_live\_..."}, json={"query": "How do modern LLMs handle long context?"}, timeout=120) print(resp.json()) \``\

**JavaScript:** \``javascript const resp = await fetch("https://sofya.co/v1/research", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": "Bearer ay\_live\_..." }, body: JSON.stringify({ query: "How do modern LLMs handle long context?" }) }); console.log(await resp.json()); \``\

Cuenta

GET /v1/auth/me

Obtén la información de tu cuenta, incluidos créditos, nivel y solicitudes totales.

**Respuesta:** \``json { "credits": 997, "plan\_credits": 997, "purchased\_credits": 0, "is\_free\_tier": true, "credits\_reset\_at": "2026-04-04T12:00:00Z", "total\_requests": 3, "api\_key": "ay\_live\_...", "last\_login\_method": "github", "email": "user@example.com", "github\_username": "octocat" } \``\

GET /v1/auth/transactions

Obtén tus transacciones de créditos recientes (recargas). Devuelve las últimas 50.

**Respuesta:** \``json \[ { "id": "uuid", "type": "credit", "amount": 5000, "endpoint": "top-up", "balance\_after": 6000, "created\_at": "2026-02-22T12:00:00Z" } \] \``\

GET /v1/auth/usage

Obtén el desglose de tu uso diario, por endpoint.

**Parámetros de consulta:** days\ (1-90, predeterminado 7), offset\_days\ (desplazamiento de paginación en días, predeterminado 0)

**Respuesta:** \``json \[ { "date": "2026-02-22", "endpoint": "/v1/search", "request\_count": 312, "total\_credits": 312 } \] \``\

Facturación

POST /v1/billing/checkout

Compra créditos (PAYG). Compra mínima: 2,000 créditos ($10).

**Solicitud:** \``json { "credits": 5000 } \``\

**Respuesta:** \``json { "checkout\_url": "https://checkout.creem.io/pay/..." } \``\

Límites de velocidad

Los endpoints de la API REST están limitados a **10 solicitudes por segundo por clave de API**. Esto se aplica a todos los endpoints /v1/\*\. MCP (/mcp\) está limitado a **30 solicitudes por segundo**. Si superas el límite, la API devuelve 429 Too Many Requests\ con un encabezado Retry-After\ que indica cuántos segundos esperar antes de reintentar.

**Respuesta 429:** \`` HTTP/1.1 429 Too Many Requests Retry-After: 0.85 { "detail": "Rate limit exceeded. 10 requests per second." } \``\

Las solicitudes limitadas no consumen créditos. Implementa retroceso exponencial o respeta el encabezado Retry-After\ para obtener los mejores resultados.

Códigos de error

Código	Estado	Descripción
400	Solicitud incorrecta	Parámetros no válidos (por ejemplo, consulta faltante, formato de frescura incorrecto)
401	No autorizado	Clave de API no válida o faltante
402	Pago requerido	Créditos insuficientes
403	Prohibido	Prohibido
429	Demasiadas solicitudes	Límite de velocidad alcanzado. Consulta el encabezado `Retry-After\`.
502	Puerta de enlace incorrecta	Error interno. Reintenta la solicitud.
504	Tiempo de espera de la puerta de enlace	La investigación agotó el tiempo. Prueba con una consulta más simple o menos fuentes.

Sofya

Documentación

Documentación de la API

Inicio rápido

2. Obtén créditos

3. Busca en la web

Autenticación

MCP Protocolo de Contexto de Modelo

Claude Code

Cursor · ~/.cursor/mcp.json

Codex · ~/.codex/config.toml

Windsurf · ~/.codeium/windsurf/mcp_config.json

VS Code Copilot ·.vscode/mcp.json

Herramientas disponibles

Definiciones de herramientas para Claude y GPT

Anthropic (Claude)

OpenAI (GPT)

Ejemplo: conexión

Herramientas principales

Cuerpo de la solicitud

Respuesta

Cuerpo de la solicitud

Respuesta

Cuerpo de la solicitud

Respuesta

Cuerpo de la solicitud

Respuesta

Cuenta

Respuesta

Respuesta

Parámetros de consulta

Respuesta

Facturación

Cuerpo de la solicitud

Respuesta

Límites de velocidad

Respuesta 429

Códigos de error

Estado y monitoreo

Feeds JSON

Ejemplo

Inicio rápido

1. Regístrate a través de GitHub

2. Obtén créditos

3. Busca en la web

Autenticación

MCP (Protocolo de Contexto de Modelo)

Claude Code

Cursor (~/.cursor/mcp.json\)

Codex (~/.codex/config.toml\)

Windsurf (~/.codeium/windsurf/mcp\_config.json\)

VS Code Copilot (.vscode/mcp.json\)

Herramientas principales

POST /v1/search · 1-3 créditos (+5 con respuesta de IA)

POST /v1/fetch · 1 crédito por URL

POST /v1/extract · 5 créditos

POST /v1/research · 25 créditos

Cuenta

GET /v1/auth/me

GET /v1/auth/transactions

GET /v1/auth/usage

Facturación

POST /v1/billing/checkout

Límites de velocidad

Códigos de error

Cursor (`~/.cursor/mcp.json\`)

Codex (`~/.codex/config.toml\`)

Windsurf (`~/.codeium/windsurf/mcp\_config.json\`)

VS Code Copilot (`.vscode/mcp.json\`)