Developers · API y MCP de Believe Global

Opera Believe Global desde tu agente.

Tres superficies sobre un mismo backend: un servidor MCP para agentes, endpoints REST para aplicaciones y una especificación OpenAPI 3.1 para generar clientes. Sin API keys. Todos los endpoints son públicos y aplican límites de uso.

Quickstart

1. Haz una pregunta. Es de solo lectura y no tiene efectos.

curl -X POST https://believe-global.com/ask \
  -H 'content-type: application/json' \
  -d '{"query": "Is Believe Global a good fit for a LATAM retail brand?"}'

2. Lista las tools del MCP.

curl -X POST https://believe-global.com/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

3. Llama a una tool.

curl -X POST https://believe-global.com/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ask_brand","arguments":{"query":"Who is Believe not a good fit for?"}}}'

4. Envía una solicitud de diagnóstico. Esto manda un correo real al equipo de Believe y una confirmación a la dirección que indiques, así que usa tus propios datos.

curl -X POST https://believe-global.com/api/v1/contact \
  -H 'content-type: application/json' \
  -d '{"name":"Ana Pérez","email":"ana@example.com","company":"Example Retail","role":"Head of Marketing","country":"CO","context":"Mid-market retail brand with sales data, looking to make marketing operable by agents."}'

Conecta un cliente MCP

Apunta cualquier cliente MCP con transporte Streamable HTTP a https://believe-global.com/mcp (protocolo 2025-06-18, respuestas JSON, sin autenticación). Archivos de descubrimiento: /.well-known/mcp.json y /.well-known/mcp/server-card.json.

ask_brand: Consulta de solo lectura sobre el perfil de marca firmado: claims verificables con sus pruebas y sus límites. Tú sintetizas la respuesta.
request_diagnostic: Solicita un diagnóstico en nombre de una persona. Una persona responde en 48 horas.
apply_partner_program: Aplica al programa de partners MAAS en nombre de una agencia o consultor. Una persona responde en 48 horas.

Autenticación y límites

Sin autenticación y sin API keys. /ask permite 60 solicitudes por minuto por cliente. Los formularios REST permiten 10 envíos por hora por cliente. El MCP permite 60 solicitudes por minuto y 5 envíos por hora por cliente, más un tope compartido de 20 envíos por hora. Las validaciones fallidas no cuentan. Cada respuesta trae los headers RateLimit-Policy, RateLimit y RateLimit-Limit, -Remaining y -Reset, así puedes autorregularte antes de llegar al límite. Al superarlo recibes HTTP 429 con el header Retry-After en segundos. Para automatizar envíos usa el MCP: los endpoints REST son los mismos formularios que usa el sitio.

HTTP/2 200
api-version: 1
ratelimit-policy: "default";q=60;w=60
ratelimit: "default";r=57;t=48
ratelimit-limit: 60
ratelimit-remaining: 57
ratelimit-reset: 48

Versionado y deprecación

Los endpoints REST viven bajo /api/v1 y cada respuesta trae el header API-Version. /api/contact y /api/partners son alias fijos de v1. /ask sigue la convención NLWeb y /mcp la versión del protocolo MCP (2025-06-18). Los cambios que rompen compatibilidad salen solo en una nueva versión mayor (/api/v2). Una versión deprecada sigue funcionando al menos 180 días: sus respuestas traen un header Deprecation (RFC 9745) con la fecha del anuncio, un header Sunset (RFC 8594) con la fecha de cierre y un Link con rel="deprecation" que apunta al aviso. Hoy nada está deprecado.

Errores

Los endpoints REST devuelven JSON con ok, error, code y hint, y issues cuando falla la validación. El MCP devuelve errores JSON-RPC (-32700 error de parseo, -32600 solicitud inválida, -32601 método inexistente, -32602 parámetros inválidos, -32000 límite de uso) y reporta los fallos de una tool con isError.

{
  "ok": false,
  "error": "Revisa estos campos — email: Invalid email address",
  "code": "validation_error",
  "hint": "Fix the fields listed in issues and resend. Schema: https://believe-global.com/openapi.json",
  "issues": ["email: Invalid email address"]
}

Código	HTTP	Cuándo
validation_error	400	Falta un campo o es inválido. Revisa issues.
invalid_request	400	El cuerpo no es JSON ni datos de formulario válidos.
missing_query	400	La solicitud no trae query.
not_found	404	No existe un endpoint de la API en esa ruta.
method_not_allowed	405	Método HTTP incorrecto. Revisa el header Allow.
rate_limited	429	Límite de uso superado. Espera los segundos de Retry-After.
delivery_failed	500	No se pudo entregar el envío. Reintenta más tarde.
not_configured	503	El backend de consulta no está disponible.

Sandbox

No hay sandbox. ask_brand y /ask son de solo lectura: úsalos para probar una integración sin efectos. request_diagnostic, apply_partner_program y los dos formularios REST son envíos reales.

Recursos legibles por máquinas

OpenAPI 3.1/openapi.json
API catalog (RFC 9727)/.well-known/api-catalog
AI catalog (ARD)/.well-known/ai-catalog.json
Agent skills index/.well-known/agent-skills/index.json
API status/api/v1/status
MCP/.well-known/mcp.json
MCP server card/.well-known/mcp/server-card.json
A2A agent card/.well-known/agent-card.json
Brand profile/.well-known/brand.json
llms.txt/llms.txt
AGENTS.md/AGENTS.md

¿Dudas o falta algo? Escribe a hola@believe-global.com.