agenttools
Inboxes

Ingest an event

No auth required

Ingests an event into the inbox. Anyone with the inbox ID can ingest — no authentication required, even for org-owned inboxes; the ID itself is the capability. Accepts any content type; the raw body is stored as-is and also parsed into `parsed_body` when the content type includes `application/json`. The event's TTL resolves from `?ttl=`, then the `X-Inbox-TTL` header, then the inbox's `default_ttl_seconds`, clamped to 60–2592000 seconds (30 days).

POST/api/inboxes/{id}/events

Parameters

Path
idstringrequired
The inbox ID (`inbox_…`).
Query
ttlinteger
Per-event TTL override, in seconds (60–2592000). Takes precedence over the X-Inbox-TTL header.
sourcestring
Optional source label for the event, truncated to 200 characters.

Responses

201The ingested event.
idstring
Unique identifier for the inbox event, prefixed with `inbevt_`.Example: "inbevt_xxxxxxxxxxxxxxxxxxxxxxxx"
object"inbox_event"
inbox_idstring
ID of the containing inbox (inbox_…).
organization_idstring | null
Owning organization ID, or null if the resource is public (created without an API key).
content_typestring | null
Content-Type of the ingested request, if provided.
bodystring | null
Raw event body.
parsed_bodyobject
Parsed body when the content type included application/json, otherwise null.
size_bytesinteger | null
sourcestring | null
Optional source label from ?source= or the X-Inbox-Source header, truncated to 200 characters.
expires_atinteger | null
When the event expires — expired events are never returned by reads and are eventually purged. Unix timestamp in seconds.
received_atinteger | null
When the event was ingested. Unix timestamp in seconds.
400The request was malformed or failed validation.
errorobject
type"invalid_request_error" | "authentication_error" | "authorization_error" | "not_found_error" | "rate_limit_error" | "api_error"
codestring
Machine-readable error code.
messagestring
Human-readable error message.
paramstring | null
The offending parameter, when applicable.
404The resource does not exist or is not visible to the caller.
errorobject
type"invalid_request_error" | "authentication_error" | "authorization_error" | "not_found_error" | "rate_limit_error" | "api_error"
codestring
Machine-readable error code.
messagestring
Human-readable error message.
paramstring | null
The offending parameter, when applicable.
413The request body exceeded the size limit.
errorobject
type"invalid_request_error" | "authentication_error" | "authorization_error" | "not_found_error" | "rate_limit_error" | "api_error"
codestring
Machine-readable error code.
messagestring
Human-readable error message.
paramstring | null
The offending parameter, when applicable.
429The caller has hit a rate or capacity limit.
errorobject
type"invalid_request_error" | "authentication_error" | "authorization_error" | "not_found_error" | "rate_limit_error" | "api_error"
codestring
Machine-readable error code.
messagestring
Human-readable error message.
paramstring | null
The offending parameter, when applicable.

Example request

curl
curl -X POST https://agtls.dev/api/inboxes/{id}/events