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 person you act as is fixed by the key; the agent a conversation reaches is chosen when the conversation starts.

Authorization: Bearer ak_<keyId>_<secret>

Send the agent a message

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

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…"
}

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.

List the agents you can message

The valid values for agent_id — the agents your account can hold a conversation with. An account with exactly one agent never needs this: new conversations reach it automatically.

Response

{
  "agents": [
    { "agent_id": "324cd102-…", "name": "Ayven", "workspace_id": "ws_94ba9c…" }
  ]
}

Read a conversation's transcript

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

Query parameters

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": "…" }
  ]
}

Sessions are bound to their owner — a session id created by a different account returns 404, the same as a nonexistent one. Each session remembers which agent it is with.

Settle what the agent is waiting on

The agent gets blocked on you in two ways, and stays blocked until it is settled: an action she has drafted and needs permission for, and a question she is waiting on an answer to. Each has one endpoint to see it and one to settle it. Both settle endpoints take a list, so one call clears a queue; each entry reports its own outcome, so one bad id does not sink the rest.

Actions awaiting your permission. Each carries the operation_id a decision names.

[
  { "operation_id": "op_1c4e…", "decision": "approve" },
  { "operation_id": "op_77af…", "decision": "reject", "reason": "wrong audience" }
]

decision is approve, approve_same_type (this one and every pending action of the same kind), or reject. A rejection re-plans the mission around your refusal, so a reason redirects the work where a bare no only stops it.

Open questions you can answer — ones put to you, and any on a mission you own, whoever she asked. Each carries the request_id an answer names.

[
  { "request_id": "req_9b21…", "text": "Five thousand pounds, all in." }
]

The agent judges whether each reply answers what she asked. An answer can come back accepted: false with a reason naming what is still missing, and the question stays open — say the missing part rather than repeating yourself.

Create an agent

For an account that does not have one yet — nothing can be messaged until it does. Takes agent_name, and optionally a workspace_id to add the agent to a workspace you own or administer. Free accounts include one agent.

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.