Skip to main content
Paths are relative to https://inkbox.ai/api/v1/identities/my-agent. Authenticate with an API key in X-API-Key. Admin-scoped keys and the identity’s own claimed agent-scoped key can use these endpoints. In the Console, any organization member can view sources (including their URLs) and events, create sources the agent handles, and rename, re-sign, rotate or delete them. Creating, editing, rotating or deleting a script source, switching a source to or from a script handler, and replaying events need an organization owner or admin. Creating, updating, and rotating sources and replaying events need a hosted agent; otherwise they return 409 with code identity_not_hosted. Removing hosting deletes the agent’s sources and their events. Their URLs stop working as soon as removal starts. For concepts and setup guides, see Inbound.

Source

Create a source

POST /inbound
Returns 201 with the source. Invalid signature settings return 422 with the reason. An agent can have up to 50 sources; creating another returns 409 with code inbound_source_limit. See example settings for common senders.

List sources

GET /inbound Returns {"sources": [Source]}, oldest first.

Get a source

GET /inbound/{source_id}

Update a source

PATCH /inbound/{source_id} Send any of name, signature, and handler. Omitted fields keep their values. Send "signature": null to remove verification. A new signature replaces the old one and needs its secret. The URL doesn’t change.

Delete a source

DELETE /inbound/{source_id} Deletes the source and all of its events. Its URL stops working. Returns 204.

Rotate a source URL

POST /inbound/{source_id}/rotate Returns the source with a new url. The old URL stops working immediately.

Check a signature

POST /inbound/signature-check Checks a sample request against signature settings, or against a saved source’s settings and secret. Nothing is stored.
This sample is signed with example-secret, so it returns 200 with:
When the signature doesn’t match, verified is false and reason says why, such as "Signature does not match". A timestamped sample older than max_age_seconds fails with a timestamp reason, so use a recent request.

Event

List events

GET /inbound/{source_id}/events Returns {"events": [Event], "next_cursor": "inbev_..." | null}, newest first.

Get an event

GET /inbound/{source_id}/events/{event_id} Returns the event plus request, the request as received:
body_encoding is utf8 for bodies that are valid UTF-8 and base64 otherwise. Decode body by body_encoding, not by content_type. Credentials and connection headers aren’t stored.

Replay an event

POST /inbound/{source_id}/events/{event_id}/replay Delivers the event to the agent again with a new delivery_id and resets its status to pending. Returns 202 with the event.

Report a failed event

POST /inbound/{source_id}/events/{event_id}/result The agent reports an event it couldn’t handle, so you can find and replay it. Requires the identity’s own agent-scoped key.
Returns 204. If the event was replayed since that delivery, returns 409 with code stale_delivery and changes nothing; treat that as done.

Receive events

Senders post to the source’s url. See responses to the sender and the inbound.received payload.

SDKs