Developers · Believe Global API and MCP

Operate Believe Global from your agent.

Three surfaces over one backend: an MCP server for agents, REST endpoints for applications, and an OpenAPI 3.1 spec to generate clients. No API keys. Every endpoint is public and applies usage limits.

Quickstart

1. Ask a question. It is read-only and has no side effects.

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. List the MCP tools.

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

3. Call a 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. Submit a diagnostic request. This sends a real email to the Believe team and a confirmation to the address you provide, so use your own details.

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."}'

Connect an MCP client

Point any MCP client with Streamable HTTP transport at https://believe-global.com/mcp (protocol 2025-06-18, JSON responses, no authentication). Discovery files: /.well-known/mcp.json and /.well-known/mcp/server-card.json.

ask_brand: Read-only retrieval over the signed brand profile: verifiable claims with linked proofs and boundaries. You synthesize the answer.
request_diagnostic: Applies for a diagnostic on behalf of a person. A human replies within 48 hours.
apply_partner_program: Applies to the MAAS Partner Program on behalf of an agency or consultant. A human replies within 48 hours.

Authentication and limits

No authentication and no API keys. /ask allows 60 requests per minute per client. The REST forms allow 10 submissions per hour per client. The MCP allows 60 requests per minute and 5 submitted actions per hour per client, plus a shared cap of 20 submitted actions per hour. Failed validations do not count. Every response carries RateLimit-Policy, RateLimit and RateLimit-Limit, -Remaining and -Reset headers, so you can self-throttle before you hit the limit. Over the limit you get HTTP 429 with a Retry-After header in seconds. To automate submissions, use the MCP: the REST endpoints are the same forms the website uses.

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

Versioning and deprecation

The REST endpoints live under /api/v1 and every response carries an API-Version header. /api/contact and /api/partners are aliases pinned to v1. /ask follows the NLWeb convention and /mcp follows the MCP protocol version (2025-06-18). Breaking changes ship only in a new major version (/api/v2). A deprecated version keeps working for at least 180 days: its responses carry a Deprecation header (RFC 9745) with the announcement date, a Sunset header (RFC 8594) with the end date, and a Link header with rel="deprecation" pointing to the notice. Nothing is deprecated today.

Errors

REST endpoints return JSON with ok, error, code and hint, and issues when validation fails. The MCP returns JSON-RPC errors (-32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params, -32000 rate limit) and reports tool failures with 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"]
}

Code	HTTP	When
validation_error	400	A field is missing or invalid. See issues.
invalid_request	400	The body is not valid JSON or form data.
missing_query	400	The request has no query.
not_found	404	There is no API endpoint at that path.
method_not_allowed	405	Wrong HTTP method. See the Allow header.
rate_limited	429	Rate limit exceeded. Wait the seconds in Retry-After.
delivery_failed	500	The submission could not be delivered. Retry later.
not_configured	503	The retrieval backend is unavailable.

Sandbox

There is no sandbox. ask_brand and /ask are read-only, so use them to test an integration without side effects. request_diagnostic, apply_partner_program and the two REST forms are real submissions.

Machine-readable resources

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

Questions, or something missing? Write to hola@believe-global.com.