API reference

The API channel is one more messaging platform alongside Slack and Microsoft Teams: you authenticate with an API key, send the agent a message, and get her reply. The message runs through the same pipeline as a Slack message — the only difference is that the reply comes back on this HTTP surface.

Base URL and authentication

https://platform-gateway-3124114101.europe-west1.run.app/api/v1/api-channel

Every request passes your key as a bearer token. The agent you reach and the person you act as are fixed by the key.

Authorization: Bearer ak_<keyId>_<secret>

Send the agent a message

POST/api/v1/api-channel/messages

Runs a normal agent turn — the same thing as messaging her in a channel. The reply is returned in the response when the turn finishes within the request's wait ceiling.

Request body

Field	Required	Meaning
`text`	required	What you want to say to the agent.
`session_id`	optional	Conversation to continue — pass the `session_id` from a previous response and the agent sees the conversation's history, like a Slack thread. Omit to start a new conversation.

Example

curl -X POST https://platform-gateway-3124114101.europe-west1.run.app/api/v1/api-channel/messages \
  -H "Authorization: Bearer ak_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "What is the status of the Q3 board update?"
  }'

Response

{
  "session_id": "3f9c2a1b8d",
  "status": "completed",
  "reply": "The Q3 board update is with finance for sign-off…"
}

Status	Meaning
`completed`	The reply is in this response, in `reply`.
`processing`	The agent is still working; poll the session messages for the reply.
`queued`	The agent is busy with something else and will pick this up next; the reply will appear on the session messages.
`duplicate`	This exact message was just received and is already being handled.

Long-running turns

Turns can run long. If the agent is still working when the request's wait ceiling hits, the response comes back with status: "processing" and no reply — nothing is lost. The run continues, the reply lands on the session transcript, and you retrieve it with the endpoint below.

Read a conversation's transcript

GET/api/v1/api-channel/sessions/{session_id}/messages

The transcript is the durable record of every turn — this is how a long-running reply is retrieved.

Query parameters

Parameter	Required	Meaning
`after`	optional	A turn's `ts`; returns only newer turns, so a poller reads forward without re-downloading the whole conversation.
`limit`	optional	Maximum number of turns to return. Default `50`.

Response

{
  "session_id": "3f9c2a1b8d",
  "status": "idle",
  "messages": [
    { "role": "user",  "text": "What is the status of the Q3 board update?", "ts": "…" },
    { "role": "agent", "text": "The Q3 board update is with finance for sign-off…", "ts": "…" }
  ]
}

Status	Meaning
`idle`	The latest turn is finished; the transcript holds the reply.
`processing`	The agent is still working on the latest message.
`queued`	The latest message waits for the agent to free up.

Sessions are bound to the key's owner and the key's agent — a session id created under a different key returns 404, the same as a nonexistent one.

Rate limits and errors

Each key has its own per-minute rate limit, set when the key is created and shown on its row in the app.

Code	Meaning
`401`	Missing, malformed, unknown, revoked, expired, or inactive API key.
`404`	The session doesn't exist, or belongs to a different key owner or agent.
`422`	The message text is empty.
`429`	The key's per-minute rate limit was exceeded.
`502`	The agent could not process the message.