https://app.cloudthinker.io. To add a caller, see A2A API.
Endpoints
X-API-Key skips the token request and gets every scope the caller has. Repeated wrong keys from one IP address are rate limited like token requests.
Send A2A-Version: 1.0 on every call to /api/a2a. 1 and 1.0.0 also mean A2A 1.0; 0.3, or no header, gets A2A 0.3 fields, which differ from this page. Any other value fails with -32009.
Get a token
POST /api/a2a/oauth/token with Content-Type: application/x-www-form-urlencoded and grant_type=client_credentials. Send the client ID and secret with HTTP Basic auth, or as the form fields client_id and client_secret; Basic auth wins when both are sent. Client IDs start with cta_. Leave out scope (space-separated) for every scope the caller has.
200 with Cache-Control: no-store; scope lists the token’s scopes:
SendMessage calls fail with client_inactive.
A caller registered with a public key can send a private_key_jwt assertion, and no secret: client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer and client_assertion=<JWT>. The JWT needs iss and sub set to the client ID, aud set to the token URL, a single-use jti, and exp at most 5 minutes ahead.
Token errors return OAuth 2.0 error and error_description. 400 invalid_request means a wrong body type or assertion type, or both a secret and an assertion; 400 unsupported_grant_type, that grant_type isn’t client_credentials; 400 invalid_scope, a scope the caller doesn’t have. 401 invalid_client means a missing or wrong ID, secret or assertion, a reused assertion, or a revoked caller; with Basic auth it carries WWW-Authenticate: Basic realm="a2a". 429 slow_down means too many token requests (Limits); wait for Retry-After.
Methods
Every call to/api/a2a is a JSON-RPC 2.0 request; its id (string, number or null) comes back unchanged with a result or an error. Each method needs a scope; a new caller has all three, and a token without the scope fails with insufficient_scope.
a2a:ask:SendMessageasks and waits up to 110 seconds for the answer;SendStreamingMessageasks and streams task updates as server-sent events;CancelTaskstops a task that hasn’t finished.a2a:tasks.read:GetTaskreads one of your tasks;ListTaskslists them, filtered bycontextIdorstatus, up to 100 per page;SubscribeToTaskstreams updates for a task that hasn’t finished;GetExtendedAgentCardreturns your caller’s extended Agent Card.a2a:push:CreateTaskPushNotificationConfig,GetTaskPushNotificationConfig,ListTaskPushNotificationConfigsandDeleteTaskPushNotificationConfigadd, read, list and remove a task’s push URLs.
SendMessage
message.metadata and metadata are accepted and ignored for outside callers; configuration.historyLength sets how many messages of history to include. A question with no text, or with a secret such as an access key, fails with blocked_by_guardrail.
result wraps the task in task:
GetTask and other methods
GetTask takes id, the task id (1 to 128 characters), and an optional historyLength. Its result is the task itself, with no task wrapper. CancelTask takes the same params and returns the task; a task in a final state fails with task_not_cancelable.
Once the state is TASK_STATE_COMPLETED, the answer is in one answer artifact, with secrets redacted.
Task fields
contextId is the conversation, for message.contextId on a follow-up. status.timestamp is when the state last changed, and status.message says why the run failed, was rejected or was canceled, as a text part. metadata.workspaceId is the workspace that answered; metadata.failureKind is a short code when the run didn’t finish, else empty.
TASK_STATE_SUBMITTED (queued) and TASK_STATE_WORKING (the agent is working) aren’t final. The final states are TASK_STATE_COMPLETED (read the answer artifact), TASK_STATE_FAILED (the run failed; ask again or check the conversation), TASK_STATE_REJECTED (refused, for example at the workspace credit limit) and TASK_STATE_CANCELED (stopped by CancelTask or by revoking the caller). TASK_STATE_INPUT_REQUIRED is never returned to outside callers: a step that needs approval is declined, and the agent answers without it.
Push notifications
When a task reaches a final state, CloudThinker POSTs{"task": <task>} to each of its push URLs, set on SendMessage or with CreateTaskPushNotificationConfig. The required url must be a public https address with no user name or password, else invalid_params. The optional token is sent back in X-A2A-Notification-Token, to prove the call is from CloudThinker. The optional authentication.scheme and authentication.credentials are sent as Authorization: <scheme> <credentials>. A task holds at most 5 push configs.
Errors
The HTTP status is200, except 401 for invalid_token (with WWW-Authenticate: Bearer realm="a2a") and 429 with Retry-After for busy and rate_limited. error.data is a list holding one ErrorInfo; metadata.reason is the reason and metadata.retryAfter the seconds to wait, as a string:
Envelope errors have no
metadata.reason: -32700 (the body isn’t valid JSON), -32600 (not a JSON-RPC 2.0 request), -32601 (unknown method), -32602 (params don’t match the method; error.data holds a BadRequest naming the field) and -32603 (internal error; retry with the same messageId).
Limits
An access token lasts 1 hour. Each caller runs at most 3 questions at once and makes at most 120 calls a minute to/api/a2a. Token requests are limited to 20 a minute, per IP address and per caller. A caller’s monthly credit limit is none by default.
Related
A2A API
Add an outside caller and send your first message.
Public API
Read and act on workspace data with a scoped token.