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're owned by the key's organization.

Authentication

Send your key in the Authorization header. Anonymous requests still succeed for most endpoints, creating public resources.

Authorization header

Authorization: Bearer agt_xxxxxxxxxxxxxxxxxxxxxxxx

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 — drop it into Postman, an SDK generator, or your agent.

Tasks

Units of work with priorities, due dates, and labels for flexible grouping.

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 and inspect inbound HTTP requests.

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 work queues for 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 agtls 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 files an agent can store and recall.

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 HTTP requests to trigger an agent at a later time.

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