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. En Claude Code conecta con: claude mcp add --transport http believe-global https://believe-global.com/mcp. GET /mcp devuelve un descriptor con las tools, los límites y este quickstart.

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.

Idempotencia

Envía el header Idempotency-Key (o idempotency_key en las tools del MCP) en las dos operaciones de envío, para que un reintento tras un corte de red no envíe dos veces. Usa un valor único por operación, por ejemplo un UUID, y reutilízalo solo para reintentar esa misma llamada. Con la misma llave y el mismo cuerpo recibes la respuesta original con Idempotent-Replayed: true, y el reintento no gasta tu cupo de envíos. La misma llave con otro cuerpo devuelve 422, y la misma llave mientras la primera solicitud sigue en curso devuelve 409. Solo se guardan las respuestas exitosas, durante 24 horas, así que una solicitud fallida se puede reintentar con la misma llave.

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ódigoHTTPCuándo
validation_error400Falta un campo o es inválido. Revisa issues.
invalid_request400El cuerpo no es JSON ni datos de formulario válidos.
missing_query400La solicitud no trae query.
invalid_idempotency_key400La Idempotency-Key no tiene entre 1 y 255 caracteres ASCII visibles.
not_found404No existe un endpoint de la API en esa ruta.
method_not_allowed405Método HTTP incorrecto. Revisa el header Allow.
idempotency_in_progress409Una solicitud con la misma Idempotency-Key sigue en curso. Reintenta con la misma llave.
idempotency_key_reused422La Idempotency-Key ya se usó con otro cuerpo de solicitud.
rate_limited429Límite de uso superado. Espera los segundos de Retry-After.
delivery_failed500No se pudo entregar el envío. Reintenta más tarde.
not_configured503El 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.

WebMCP

Un agente en un navegador con soporte de WebMCP puede usar el sitio directamente. Cada página registra la tool de solo lectura ask_brand con document.modelContext.registerTool(). El formulario de la auditoría AOS gratuita de la home es una tool declarativa (run_aos_audit): el agente rellena los campos y la persona lo revisa y lo envía. Las tools de envío no se exponen por WebMCP: para esas usa el MCP.

Recursos legibles por máquinas

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