Skip to content

HTTP API

The A3T API is plain HTTP and JSON. The console at dash.a3t.io uses the same API, so anything the console does, your code can do too.

This page lists the endpoints by purpose. Most work on flows, runs, resources and triggers goes through MCP tools on POST /message; those are on MCP tools.

All examples use $A3T_URL for the API address. Copy it from any agent’s Overview: it is the address under Data plane, without /chat. See the Quick start.

Terminal window
export A3T_URL="https://…" # the API address, from Data plane on an agent's Overview

Every request carries a token in the Authorization header:

Authorization: Bearer <token>

There are two kinds of token.

TokenWhat it isHow you get itWhat it may call
Sign-in token ($A3T_TOKEN)A person’s session. It acts with that person’s role and project accessPOST /auth/login, belowEverything that person may do. Each endpoint below says what it needs
Agent key ($AGENT_KEY, a3tk_…)A key for one agent, for apps. It acts with the roles of the person who made it, never moreThe agent’s Access › Keys in the console, or POST /agents/{id}/keysThat agent’s data plane only: POST /chat, GET /chat/stream/{session} for its own sessions, and its webhook POST /webhook/agent/{id}/…. Anything else answers 403

Public endpoints need no token: /auth/login, /auth/first-password, /auth/forgot, /auth/sso/start, /auth/sso/callback, /auth/me (it checks the token you send itself), /health, /edition, the two /.well-known/oauth-… documents, and /webhook/… (see Webhooks).

A missing or bad token answers 401 with {"error": "…"} and a WWW-Authenticate header that points at /.well-known/oauth-protected-resource. A token that is valid but not allowed answers 403.

Which projects a person sees and changes follows their project membership and role, the same as in the console. See Projects and Security.

Signs a person in with email and password. Public.

FieldWhat it is
emailThe email the account was made with
passwordIts password
Terminal window
curl -s -X POST "$A3T_URL/auth/login" \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com", "password": "…"}'

It answers:

FieldWhat it is
access_tokenThe sign-in token. Send it as Authorization: Bearer …
token_typeAlways Bearer
expires_inSeconds until the token expires. Sign in again after that
refresh_tokenReturned, but there is no endpoint that takes it yet
user{id, org_id, email, name, role}. role is one of superadmin, securityadmin, admin, operator, viewer
AnswerMeans
401 Invalid credentialsWrong email or password
403 with "code": "password_change_required"The account still has a temporary password. Call /auth/first-password

The first sign-in with a temporary password an admin gave. Sets the person’s own password and signs them in. Public.

FieldWhat it is
emailThe account’s email
passwordThe temporary password
new_passwordTheir own password: at least 8 characters, not the temporary one

It answers like /auth/login. 401 means the email or temporary password is wrong; 409 means the account is already set up, so use /auth/login.

Sends a link to set a new password. The link works for 30 minutes. Public.

FieldWhat it is
emailThe email the person signs in with
returnOptional. The console address the link should open

The answer is the same whether or not the email has an account: {"ok": true, "message": "…"}. People who sign in with single sign-on get no link; their organisation sets their password.

GET /auth/sso/start and GET /auth/sso/callback

Section titled “GET /auth/sso/start and GET /auth/sso/callback”

Single sign-on, for a browser. Public. start takes ?org=<organisation handle> or ?email=<work email>, and optionally &return=<console origin>, and redirects to the organisation’s own sign-in page. After sign-in, callback returns the browser to the console with the token in the address’s # fragment. An app does not call these directly. See Get access and sign in.

Who the token belongs to: {id, org_id, email, name, role}. 401 if the token is missing or invalid.

SuperAdmin only. Acts as another user or as a role, for support. Give exactly one of:

FieldWhat it is
user_idThe person to act as
roleA role to act as: securityadmin, admin, operator or viewer

It answers a token like /auth/login, valid for at most one hour, plus act: {sub, email} naming the SuperAdmin. Everything done with it is logged as done by the SuperAdmin on that person’s behalf. To stop, go back to your own token.

This is the data plane: what an app uses to talk to an agent. Make the agent and its key in the console first; the Quick start does it step by step.

Sends one message to an agent and streams the answer back. Agent key or sign-in token.

The agent’s id is the short id in its address and on its Overview, such as agt-87c819a3; its name, such as agent_acme_support_helpdesk, is what lists show.

FieldWhat it isWhat to put
session_idWhich agent and which conversation, as <agent id>:<conversation>The agent’s id, a colon, then your own name for the conversation: one per customer case, chat or user. Messages with the same session_id share a conversation
messageWhat the user saidText
contextOptional. Extra facts for this turnA JSON object
memory_branchOptional. Run this turn on one of the agent’s memory branches instead of its main memoryA branch name from GET /agents/{id}/branches

With an agent key, session_id must start with that key’s agent id, or the answer is 403 with "code": "key_scope". With a sign-in token you may also pass llm_resource, enabled_tools, mcp_servers and ui_context; the console uses these for its own assistant.

Terminal window
curl -N "$A3T_URL/chat" \
-H "Authorization: Bearer $AGENT_KEY" \
-H "Content-Type: application/json" \
-d '{"session_id": "agt-87c819a3:ticket-4182", "message": "Where is my refund?"}'

The answer is a stream of server-sent events, one data: line each, in the AI SDK UI message stream format (header x-vercel-ai-ui-message-stream: v1):

Event typeWhat it carries
start, start-stepThe answer starts
text-start, text-delta, text-endThe answer’s text. Join the delta fields of the text-delta events
tool-input-available, tool-output-availableA tool the agent called, and what it got back
data-…Other progress the agent reports
errorThe run failed; errorText says why
finish-step, finishThe answer is complete

If the run stops before it answers (a model error, a refused step), the stream says so in the text and ends. Other answers: 400 without session_id, 401 without a token, 429 with "code": "org_quota" when the organisation is over its quota.

Attaches to a conversation’s live stream: every token of its runs as they happen. Agent key (its own sessions only) or sign-in token. Each event has an id; to resume after a dropped connection, send Last-Event-ID: <id> or ?after=<id> and the missed events come first. Write the : in the session id as %3A if your client needs it.

The agent’s webhook, if it has one (see the agent’s Access › Endpoints). It takes the same session_id and message, but answers at once with the runs it started instead of streaming. Needs a token: one of the agent’s keys, or a sign-in token. Use POST /chat unless you need a webhook.

The control plane for keys. Sign-in token of someone who may change the agent: write access to its project.

Method and pathWhat it doesBodyAnswer
GET /agents/{id}/keysLists its keys—{agent_id, keys: [{id, name, prefix, created_by, created_at, last_used_at, revoked_at}]}. Only the first characters (prefix) of each key are kept
POST /agents/{id}/keysMakes a key{"name": "shop backend"} (optional)201 with the key’s record and key: the full a3tk_… key. It is shown only this once
DELETE /agents/{id}/keys/{key id}Revokes a key. The next call with it fails—{agent_id, key, revoked: true}; 404 if the agent has no such key
Terminal window
curl -s -X POST "$A3T_URL/agents/agt-87c819a3/keys" \
-H "Authorization: Bearer $A3T_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "shop backend"}'

Making, changing, blocking and sharing agents goes through the A3T agents: built-in agents whose tools are A3T’s own control plane. Each tool runs a platform flow as you, with your project access. Sign-in token.

Method and pathWhat it does
GET /agents/{agent}/toolsLists an agent’s tools: {agent, tools: [{name, flow, description, schema}]}. schema is what the tool’s arguments look like
POST /agents/{agent}/tools/{tool}Runs one tool now, with no model in between. The body is the tool’s arguments. Answers {agent, tool, output}; 403 if you may not, 404 if the agent has no such tool

The A3T agents and what their tools cover:

AgentIts tools
agent_a3t_agentsAgents: tool_a3t_agent_create, _list, _get, _update, _delete, _block, _unblock, _share, _unshare, _lineage, _memory, _memory_put, _memory_forget, _turns, _events and more
agent_a3t_templatesTemplates: tool_a3t_template_list, _get, _create, _update, _delete
agent_a3t_projectsProjects, organisations, profiles and users: tool_a3t_project_list, _create, _update, _delete, _move, tool_a3t_org_…, tool_a3t_user_…
agent_a3t_resourcesResources and settings: tool_a3t_resource_…, tool_a3t_setting_…, tool_a3t_resource_test
agent_a3t_runtimeCanvases, flow releases, sharing between projects: tool_a3t_canvas_…, tool_a3t_release_…, tool_a3t_share
agent_a3t_governanceAudit log, error log, early-access requests
agent_a3t_knowledgeThe knowledge graph: ingest, look up, query, train

List an agent’s tools first to see each one’s arguments:

Terminal window
curl -s "$A3T_URL/agents/agent_a3t_agents/tools" -H "Authorization: Bearer $A3T_TOKEN"

An agent’s memory space, its versions and its memory branches are FlowR endpoints under /agents/{id}. Reading needs read access to the agent’s project; changing needs write access. Changes are also checked against policy; a refusal answers 403 with "code": "policy_denied". See Agents › Versions & deploy.

Method and pathWhat it doesBody
GET /agents/{id}/memoryWhere its memory lives: {agent_id, resource, namespace, own}—
PUT /agents/{id}/memoryGives it its own memory space{"namespace": "…"} (optional; default <project>--<agent>)
GET /agents/{id}/versionsIts versions—
POST /agents/{id}/versionsMakes a version now. A version never changes; a change is the next version{"note": "…", "flows": [{namespace, name, version}]} (both optional)
GET /agents/{id}/versions/{version}One version—
GET /agents/{id}/versions/{version}/manifestWhat that version’s flows reach—
GET /agents/{id}/branchesIts memory branches—
POST /agents/{id}/branchesMakes a branch{"name": "…", "parent": "…"} (parent optional)
DELETE /agents/{id}/branches/{name}Drops a branch—
GET /agents/{id}/branches/{name}/conflictsWhat differs between the branch and main?memories=PROCEDURAL,SEMANTIC narrows it
POST /agents/{id}/branches/{name}/mergeMerges the branch’s procedures back. 409 lists conflicts to resolve{main_offset, resolutions}
POST /agents/{id}/branches/{name}/promoteMakes a new agent from the branch{"new_agent": {"id": "…", "name": "…"}}
POST /agents/{id}/forkCopies the agent into a new one{"new_agent": {"id": "…", "name": "…"}}
GET /agents/{id}/deploymentsWhich version each environment runs—
PUT /agents/{id}/deployments/{environment}Pins an environment to a version. Rolling back is pinning the previous one{"version": "…"}
GET /agents/{id}/runsIts recorded turns. Sort by at—
GET /agents/{id}/usageIts usage, by environment—

Flows and runs have no REST endpoints of their own: use the MCP tools on POST /message. The ones you need most:

ToTool
List flows, read onelist_flows, get_flow
Run a flow and wait for its resultexecute_flow
Check a runget_execution_status, get_run
List runslist_runs, list_executions
Terminal window
curl -s -X POST "$A3T_URL/message" \
-H "Authorization: Bearer $A3T_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": {"name": "execute_flow",
"arguments": {"namespace": "acme-support", "name": "flow_acme_support_refund", "input": {"order_id": "A-1042"}}}}'

See MCP tools for every tool and its arguments.

Sends a CloudEvent into a project: every run waiting for it in a listen step wakes up, and event triggers fire. Sign-in token with run access to the project. Send it as JSON with at least type (and source, subject, data as your listeners need), or send the body as data with ce-type, ce-source, … headers. Answers 202 with {id, woke, started}.

A run that waits for a person shows up here. Sign-in token.

Method and pathWhat it does
GET /inputsThe waiting requests: {inputs, count}
GET /inputs/{request id}One request
POST /inputs/{request id}Answers it; the run carries on. The body is the answer. An approval can only be answered by the person it asks; for anyone else it answers 404

Triggers are made in the console (Triggers) or with the trigger MCP tools (create_trigger, list_triggers, …), which check your project access.

Fires the webhook trigger whose path is /{path}. For example, a trigger with path /acme/refund is called at POST /webhook/acme/refund. The body is any JSON; it becomes the event’s body.

Terminal window
curl -X POST "$A3T_URL/webhook/acme/refund" \
-H "Authorization: Bearer $A3T_TOKEN" \
-H "Content-Type: application/json" \
-d '{"order_id": "A-1042", "customer": "Ana Ruiz", "reason": "Refund not received after 10 days"}'

Who may call it. Webhook paths are public, so outside systems can call them. Send a token when you have one: with a sign-in token the runs act as that person, with their access; without one they act as the trigger. An agent’s own webhook (/webhook/agent/…) always needs a token. Only POST is served.

AnswerMeans
200 {delivered, targets, executions: [{trigger, target, instance_id}], failed, paused, path}It reached its targets. Follow each run with get_execution_status and its instance_id
404No trigger listens on this path, or what it feeds is paused and set to hide
422 {error: "nothing delivered", failed}Every target failed; failed names each with the reason, such as a mapping error
503 {error: "paused", message}Everything it feeds is paused

Runs a trigger mapping on sample events, exactly as a firing would, without running anything. Sign-in token. The console’s Check on samples uses it.

FieldWhat it is
exprThe mapping: a jq expression wrapped as ${ … }
samplesSample bodies, as callers would send them
fieldOptional. Which mapping it is: input, message or conversation
targetOptional. A flow as namespace/name, to check the result against its input schema

Resources are models, databases, MCP servers, secrets and runtimes your flows and agents use. See Resources. Sign-in token. Secret values are never returned; other keys and passwords come back masked.

Method and pathWhat it doesWho
GET /registry/resourcesThe resources you may see: [{name, namespace, type, config, tags}]. ?type=<type> filtersSigned in
POST /registry/resourcesMakes one. Body {name, namespace, type, config, tags}; namespace defaults to default. Answers 201Write access to the project. A cedar policy: SuperAdmin or SecurityAdmin only
GET /registry/resources/{project}/{name}One resourceRead access
PUT /registry/resources/{project}/{name}Replaces its config. The body is the new config objectWrite access
DELETE /registry/resources/{project}/{name}Deletes it. Deleting a runtime answers 409 with its reschedule plan first; repeat with ?confirm=<its name>Write access
GET /registry/resources/{project}/{name}/used-byThe flows and resources that name it: {flows, resources}. Check before changing or deletingSigned in; lists only what you may see
Method and pathWhat it does
GET /storage/{project}/{resource}/list?prefix=…Lists a storage resource’s files under a prefix
GET /storage/{project}/{resource}/preview?path=…The first 64 KB of one file

What runs where. See Runtimes and Canvas. Sign-in token. Changing a runtime needs Admin; pausing in production is checked against policy.

Method and pathWhat it does
GET /ops/overviewEvery runtime, what is deployed on it, its state and recent activity
GET /ops/deployments/{id}/probeA live look at one deployment
POST /ops/deployments/{id}/{action}pause, resume, restart, undeploy or terminate. Body {"reason": "…"} (optional)
POST /ops/runtimes/{name}/{action}pause, resume or hibernate a runtime. terminate needs body {"confirm": "<its name>"}
GET /ops/runtimes/{name}/terminateWhat terminating it would do, without doing it
PUT /ops/runtimes/{name}/paused-responseWhat webhooks get while paused: {"status": 503} or {"status": 404}
GET /canvas/runtimesThe runtimes flows can be placed on
GET /canvas/presetsThe deployment presets to choose from
GET /canvas/flows/{project}/{flow}/placementWhere the flow would be deployed, without deploying
POST /canvas/flows/{project}/{flow}/deployDeploys the flow
POST /canvas/canvases/{project}/{canvas}/deployDeploys an agent’s own canvas
GET /canvas/deploymentsLive deployment status

SuperAdmin or SecurityAdmin unless the row says otherwise. See Security and Decision log.

Method and pathWhat it does
GET /security/auditThe policy decision log. ?limit= (default 100, at most 1000), ?denials_only=true, ?project=<project> (or - for platform-wide decisions). Answers {count, records, scope}; it holds the newest 1000 decisions of the server that answers
GET /security/policiesThe saved Cedar policies, with their source
POST /security/policies/reloadReloads the policies now. A policy that doesn’t load leaves the current set in place
POST /security/policies/testTries a request against the policies without changing anything. Body {principal, action, resource: {type, id, attributes}, attributes?, draft_policies?, include_registry?, draft_namespace?}. Answers the decision and which policies matched
GET /security/idp/statusWhether the identity provider is set up and reachable
GET /security/idp/usersThe accounts: {id, username, email, enabled, …} each
POST /security/idp/usersMakes an account. Body {username, email?, name?, password, temporary, roles}. temporary: true makes them choose their own password at first sign-in
GET /security/idp/users/{id}One account, with its roles
PUT /security/idp/users/{id}Changes it. Any of {name, email, enabled, password, temporary, roles}; roles replaces their roles
DELETE /security/idp/users/{id}Deletes the account
GET /directory/usersPeople who can be added as members: {count, users: [{id, email, name}]}. Project owners and org admins too
Method and pathWhoWhat it answers
GET /healthPublic{"status": "ok", "service": …, "version": …}
GET /editionPublic{edition, enforcing, policy_hook, features}: whether policies are enforced on this server
GET /metricsSigned inPrometheus metrics of this server
GET /admin/stats/metricsSigned inThe same as JSON, with p50, p90 and p99
GET /.well-known/oauth-protected-resourcePublicWhere to get a token, for OAuth-aware clients such as MCP clients

The console keeps a few things per person. Sign-in token; each person sees only their own.

Method and pathWhat it does
GET /chat/sessionsYour conversations, newest first
GET /chat/sessions/{session_id}One transcript, as user and assistant turns
DELETE /chat/sessions/{session_id}Deletes a conversation. Nothing else removes it
GET /chat/sessions/{session_id}/permissionsWhat you allowed or declined in it
POST /chat/sessions/{session_id}/permissions/liftReopens a refusal: {"key": "…"}. The next matching call asks again
GET /ui/pins, POST /ui/pinsYour pinned items. Body {"kind": "chat", "id": "…", "pinned": true}