# Blueticked API

> Blueticked is a multi-channel messaging platform (WhatsApp, SMS, email) with contacts, campaigns, automations, AI agents, forms, published sites and commerce, for South African businesses. One REST API, one send endpoint, three channels.

The public API exposes supported messaging and integration operations;
it is not a mirror of every dashboard-only administration screen. The API
is versioned in the path (`/api/v1`) and authenticated with a bearer key.

## Start here

- [Everything in one document](https://app.blueticked.com/llms-full.txt): the complete
  contract — auth, conventions, all endpoints, scopes, error codes,
  webhooks and known pitfalls. Fetch this one if you are writing code.
- [OpenAPI 3.1 specification](https://app.blueticked.com/api/v1/openapi.json): the
  authoritative machine-readable schema for every request and response.
- [Operations playbooks](https://app.blueticked.com/agent-kit/platform-operations.md)
- [Dashboard map for browser agents](https://app.blueticked.com/agents.md)

All public, no credentials needed.

## MCP server

Call this API as tools rather than writing HTTP: `https://app.blueticked.com/api/mcp`
(Streamable HTTP, remote — nothing to install).

```
claude mcp add --transport http --scope user blueticked https://app.blueticked.com/api/mcp
```

The coding agent discovers Blueticked OAuth, opens a browser sign-in, and
asks the workspace administrator to approve its organization, businesses,
access profile, Test/Live mode and expiry. No API key is copied into the
project. Access and refresh tokens are stored by the MCP client.

## In the dashboard (sign-in required)

These are for the human developer, not for an agent to fetch — they
redirect to sign-in:

- [API reference](https://app.blueticked.com/developers/docs/api): per-endpoint
  documentation with request and response examples.
- [Webhooks](https://app.blueticked.com/developers/docs/webhooks): envelope, signature
  verification and the event catalogue.
- [API console](https://app.blueticked.com/developers/console): run a real request
  against a workspace and read the response.
- [API keys](https://app.blueticked.com/developers/keys): create a key, choose scopes,
  set an IP allowlist.
- [Agent access](https://app.blueticked.com/developers/agent-access): create an
  expiring, business-scoped MCP connection with a fixed safety profile.

## Notes for agents

- Use a test key (`blu_test_…`) while building. It sandboxes the entire
  send lifecycle: no provider is called, no message is delivered to a real
  recipient, and nothing is charged.
- Do not hard-code a key into generated source. Read it from the
  environment and tell the developer which variable to set.
- Branch on the `code` field of an error, never on `message`.
- Call `get_workspace_context` first. Treat its businesses, environment
  and scopes as the complete boundary for the current connection.