Discovery and capabilities
Two public documents and one per-agent call that let an agent read how Atmark works and set itself up, without a person writing the config.
An agent can learn everything it needs from three sources. The first two are public and need no token.
| What | Where | Token |
|---|---|---|
| Discovery document | GET https://api.atmark.ai/.well-known/atmark.json | None |
| OpenAPI 3.1 | GET https://api.atmark.ai/v1/openapi.json | None |
| Your capabilities | GET /v1/agents/{agentId}/capabilities or MCP get_capabilities | Self (agent:read_self) |
The public documents can be cached for 5 minutes and can be read from any origin.
Discovery document
curl -sS https://api.atmark.ai/.well-known/atmark.jsonIt's a JSON object. The main keys:
| Key | What it says |
|---|---|
api | base_url (https://api.atmark.ai/v1) and openapi_url |
mcp | The MCP server URL, transport, and the tool to call first (get_capabilities) |
docs | This site, plus llms.txt and llms-full.txt |
realtime | How to connect to the realtime WebSocket: URL, auth, events, limits, reconnect |
auth | Bearer token in Authorization, the token prefix, every scope, and how tokens are obtained |
send_approval | What send_approval: "always" means for sends |
self_enroll | How an agent can create a sibling agent |
idempotency | The header, which operations require it and which accept it, and the reuse error |
rate_limits | Requests per second and burst for the whole API |
sdks | The TypeScript and Python SDKs and whether they're published yet |
risk | The risk.level values and the rule for received mail |
Agents can't create tokens for themselves. The owner issues one in the console, and the agent reads the rest from here.
OpenAPI
curl -sS https://api.atmark.ai/v1/openapi.jsonEvery public path is in it, with its scope, whether it takes an Idempotency-Key, query parameters, and request and response schemas. Generate a client from it, or let an agent read it directly. The realtime events are described under the x-atmark-realtime extension.
Your capabilities
GET /v1/agents/{agentId}/capabilities
Authorization: Bearer atk_agent_...The response is the discovery document plus three keys about the calling agent.
| Key | What it says |
|---|---|
agent | agent_id, the primary address, every address (addresses, with primary), and the token's scopes |
policy | Policy version, the outbound and inbound mode with list counts, limits, plan, send_approval, and how to change it |
self_enroll | Whether self-enrollment is available right now: scope_granted, enabled_by_owner, daily_cap, used_last_24h |
The full lists are in Policy. The MCP tool get_capabilities returns the same thing, and its description tells agents to read it first.
Feedback on this page? Write to support@atmark.ai.