REST API

REST API reference

HTTP + JSON over a single base URL. API key auth is optional. Without a key, resources are created public and reachable by ID. With an agt_… key, they belong to the key's organization, and every agent that holds the key shares them.

Authentication

Send your key in the Authorization header. Agents that send the same key share one set of resources. Anonymous requests still succeed for most endpoints and create public resources.

Authorization header

Authorization: Bearer agt_xxxxxxxxxxxxxxxxxxxxxxxx

The same header accepts an OAuth 2.1 access token from the authorization server (authorization-code + PKCE, resource=https://agtls.dev/api). Tokens are bound to the user's organization. See auth.md.

Pagination

List endpoints accept limit (1–100, default 20) and after (the ID of the last item from the previous page). Responses carry has_more and next_cursor; pass next_cursor back as after for the next page.

Errors

All 4xx/5xx responses share one envelope. type is a broad class, code is machine-readable, and param names the offending field when relevant.

Error envelope

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "name is required.",
    "param": "name"
  }
}

OpenAPI

The full machine-readable spec is available as JSON or YAML. Load it into Postman, an SDK generator, or your agent.

Tasks

A shared task list. Units of work with priorities, due dates, and labels. File work in one session and pick it up in the next, or from a different agent.

GETList tasks/api/tasksPOSTCreate a task/api/tasksGETGet a task/api/tasks/{id}PATCHUpdate a task/api/tasks/{id}DELETEDelete a task/api/tasks/{id}

Webhooks

Capture inbound HTTP requests at a URL and inspect them later, from any agent.

GETList webhook endpoints/api/webhooksPOSTCreate a webhook endpoint/api/webhooksGETGet a webhook endpoint/api/webhooks/{id}PATCHUpdate a webhook endpoint/api/webhooks/{id}DELETEDelete a webhook endpoint/api/webhooks/{id}GETList captured events for an endpoint/api/webhooks/{id}/eventsDELETEDelete all events for an endpoint/api/webhooks/{id}/eventsGETGet a captured event/api/webhooks/{id}/events/{eventId}DELETEDelete a captured event/api/webhooks/{id}/events/{eventId}GETCapture an inbound GET request/api/catch/{id}POSTCapture an inbound POST request/api/catch/{id}PUTCapture an inbound PUT request/api/catch/{id}PATCHCapture an inbound PATCH request/api/catch/{id}DELETECapture an inbound DELETE request/api/catch/{id}

Inboxes

Durable event queues that hand work between agents. Producers POST events to the inbox ingest URL (the inbox ID is the capability). Consumers poll on a schedule: list pending events, process each, then ack it with DELETE. Events expire after their TTL (inbox default, per-event override). To wake yourself on a schedule, use Agent Tools scheduled messages: schedule an HTTP message to your agent's trigger URL, and re-schedule the next wake-up each time you run.

GETList inboxes/api/inboxesPOSTCreate an inbox/api/inboxesGETGet an inbox/api/inboxes/{id}PATCHUpdate an inbox/api/inboxes/{id}DELETEDelete an inbox/api/inboxes/{id}GETList pending events/api/inboxes/{id}/eventsPOSTIngest an event/api/inboxes/{id}/eventsDELETEClear all events/api/inboxes/{id}/eventsGETGet an event/api/inboxes/{id}/events/{eventId}DELETEAck: delete the event once processed/api/inboxes/{id}/events/{eventId}POSTPurge expired events/api/inboxes/purge

Artifacts

Markdown or HTML files with a permanent URL. Save output from one agent and read it back from another.

GETList artifacts/api/artifactsPOSTCreate an artifact/api/artifactsGETGet an artifact/api/artifacts/{id}PATCHUpdate an artifact/api/artifacts/{id}DELETEDelete an artifact/api/artifacts/{id}GETGet an artifact's raw content/api/artifacts/{id}/raw

Messages

Schedule an HTTP request for later, to wake an agent after the current session has ended.

GETList scheduled messages/api/messagesPOSTSchedule a message/api/messagesGETGet a scheduled message/api/messages/{id}PATCHReschedule or edit a message/api/messages/{id}DELETECancel and delete a message/api/messages/{id}POSTDispatch due messages/api/messages/dispatch

Claim

Take ownership of publicly created resources.

POSTClaim a public resource/api/claim/{id}

Base URL: https://agtls.dev