For developers

Partner API reference

Everything the partner API answers today, read from the same schemas the routes validate with. List your agents, start runs of their published versions, read results, mint embed sessions, register signed result callbacks - and create, check, and change agents as JSON documents, freeze versions, and put them live - from your own servers, with your own keys.

The reference text - operation summaries, descriptions, and field descriptions - comes from the API description itself and is in English.

Overview

The API is plain JSON over HTTPS. Every address below is relative to the base URL, every request carries your key in the Authorization header, and every answer is JSON - including failures.

Base URL: https://www.amistio.com/api/v1
API version: 1.0.0
Format: JSON over HTTPS

Changes inside v1 are additive only: new fields and new operations may appear, existing ones keep their meaning. Anything that would break a working client arrives as /api/v2 instead.

Authentication

Create API keys under Settings in Amistio. Each key belongs to you and carries only the scopes you chose when you created it.

Key shape

amk_<keyId>_<secret>

Header

Authorization: Bearer amk_<keyId>_<secret>

The key is shown exactly once, when you create it. Amistio keeps only a digest and can never show it again.
Send the key only in the Authorization header over HTTPS. A key anywhere in the query string is refused with 400 before anything else runs.
A key can carry an expiry date and can be revoked at any time. Revocation takes effect on the very next request.
Every use updates the key's last-used time, so Settings shows which keys are really in use.
You can hold at most 20 live keys at a time.
Amistio's own signed-in pages may call the same operations with the browser session, same-origin only. Keys are for your servers - never put one in a browser.

Scopes

A request the key's scopes do not cover fails with 403 before anything else runs. Give a key only the scopes its job needs.

Scopes
Scope	Meaning	Operations
agents:read	Read your agents and their published version pins.	List your agents `listAgents` One agent `getAgent` Read the draft as a document `getAgentDraft`
runs:start	Start runs of your agents' published versions.	Start a run `startRun`
runs:read	Read runs, their results, and their callback deliveries.	List runs of one agent `listRuns` One run `getRun` Callback deliveries for one run `listRunDeliveries`
embed:mint	Mint embed sessions for your allowed embedding origins.	Mint an embed session `createEmbedSession`
callbacks:manage	Register, pause, resume, rotate, and remove result callbacks.	List an agent's result callbacks `listCallbacks` Register a result callback `createCallback` One result callback `getCallback` Pause or resume a result callback `updateCallback` Remove a result callback `deleteCallback` Rotate a callback's secret `rotateCallbackSecret`
agents:write	Create agents from documents, check documents, and replace drafts.	Create an agent from a document `createAgent` Check a document without saving `validateAgent` Replace the draft with a document `replaceAgentDraft`
agents:publish	Freeze versions and put an agent live or take it off.	Freeze a version `freezeAgentVersion` Put the latest version live `activateAgent` Take the agent off `deactivateAgent`

Limits

Protection bounds, not pricing. When a bound is reached the answer is 429 with a Retry-After header that says how many seconds to wait.

Limits
What	Bound
Requests per key	60 per minute
Run starts per owner	10 per minute
Agent document writes per owner	30 per minute
Version freezes per owner	10 per minute
List page size	limit from 1 to 100, default 20
Request body	up to 256 KiB - a larger body answers 413
Callbacks per agent	at most 10
Live keys per owner	at most 20
Embed token first use	the frame must load within 10 minutes of minting
Callback delivery attempts	up to 5 attempts, with growing waits between them

Idempotency

Send an Idempotency-Key header when you start a run, so a retry after a timeout or a lost answer never starts a second run.

The key is yours to choose: 1 to 200 printable ASCII characters, for example your own order id.
A repeat with the same key within 24 hours returns the same run with replayed set to true and status 200. A run that really started answers 201.
The same key with a different input fails with 409, so a mistaken reuse can never silently return someone else's run.

Start one durable run of the agent's published version. Input is validated exactly like the public run page; an input object above the run bound (49152 serialized characters) fails with 400. Send an Idempotency-Key header to make retries safe: a repeat inside 24 hours returns the same run and never starts a second one; a repeat with a different input fails with 409.
POST /agents/{agentId}/runs

Pagination

List operations return one page at a time and hand you a cursor for the next one.

Ask for a page with limit, from 1 to 100. Without it you get 20 items.
When more pages exist the answer carries nextCursor. Pass it back as cursor with the same limit to read the next page.
The last page carries no nextCursor.

Errors

Every failure is the same typed JSON body. The code is one of a closed, stable set; the message is plain, bounded, and never carries a secret.

Error body

{
  "error": {
    "code": "not-found",
    "message": "not found"
  }
}

Two answers carry data beside the error: a stale expectedRevision (409) adds the draft's current revision, and a refused agent document (422) adds the findings list the Studio would show.

Every answer also carries an x-request-id header. Quote it when you report a problem, so the exact request can be found.

HTTP statuses

HTTP statuses
Status	Meaning	Where
200	The OpenAPI document One page of agents The agent An earlier start with the same Idempotency-Key was returned One page of runs The run The agent's callbacks The callback The updated callback The callback with its new secret, shown once The run's deliveries The JSON Schema document An earlier create with the same Idempotency-Key was returned The verdict and every finding (empty when ok) The draft document and its revision The saved draft document and its new revision This exact document was already frozen from this draft	This document List your agents One agent Start a run List runs of one agent One run List an agent's result callbacks One result callback Pause or resume a result callback Rotate a callback's secret Callback deliveries for one run The agent document's JSON Schema Create an agent from a document Check a document without saving Read the draft as a document Replace the draft with a document Freeze a version
201	The run was started (it may still be running) The embed session The callback with its secret, shown once The agent was created; the draft is at revision 0 A new version was frozen The version is live	Start a run Mint an embed session Register a result callback Create an agent from a document Freeze a version Put the latest version live
204	Removed Taken off	Remove a result callback Take the agent off
400	Malformed request (also: an API key placed in the query string) Malformed request, or an address that is not public https (private, loopback, link-local, and metadata ranges are refused)	Every authenticated operation Register a result callback
401	No credential, or an invalid, expired, or revoked API key	Every authenticated operation
403	The key lacks the required scope	Every authenticated operation
404	Unknown or foreign id - always the same body The partner API is off The partner API is off	Every authenticated operation This document The agent document's JSON Schema
409	No published version is live, or the Idempotency-Key was reused with a different input The origin is not on your allowed list, or no published version is live The agent already has 10 callbacks The Idempotency-Key was reused with a different body expectedRevision is stale - the body carries the current revision expectedRevision is stale - the body carries the current revision No frozen version exists, setup is incomplete, or the version cannot start (no trigger, a one-time schedule in the past) Nothing is live (activation-inactive)	Start a run Mint an embed session Register a result callback Create an agent from a document Replace the draft with a document Freeze a version Put the latest version live Take the agent off
413	The request body is larger than 256 KiB The request body is larger than 256 KiB The request body is larger than 256 KiB The request body is larger than 256 KiB	Start a run Create an agent from a document Check a document without saving Replace the draft with a document
422	The document is not a valid agent - the same findings the Studio shows; nothing was saved The document is not a valid agent - the same findings the Studio shows; nothing changed The draft has blocking findings and cannot freeze	Create an agent from a document Replace the draft with a document Freeze a version
429	Protection bound reached; wait `Retry-After` seconds	Every authenticated operation
501	Embedding is not configured on this deployment The version claims a runtime semantics this deployment does not interpret	Mint an embed session Put the latest version live

Error codes

The codes a request can come back with, and the HTTP status each one travels with. Match on the code, not on the message.

Error codes
Code	Status	Meaning
auth-required	401	No credential was sent and no session is signed in.
auth-invalid	401	The API key is malformed, unknown, expired, or revoked.
scope-insufficient	403	The key lacks the scope this operation needs.
payload-invalid	400	The body, a parameter, or a header is malformed - including a key placed in the query string.
payload-too-large	413	The request body is larger than the allowed size.
not-found	404	The id is unknown, belongs to someone else, is malformed, or the partner API is off - always the same answer.
rate-limited	429	A protection bound was reached; wait the seconds named in Retry-After.
version-not-published	409	The agent has no live published version to run or embed.
unsupported-trigger	409	The agent's live version has no trigger that a run or an embedded page could start.
conflict	409	The Idempotency-Key was already used with a different input.
budget-exceeded	409	The agent already has the maximum number of callbacks.
embed-origin-not-allowed	409	The origin is not on your allowed embedding origins list.
stale-revision	409	expectedRevision is not the draft's current revision; the body carries the current one - read the draft again, merge your change, and retry.
invalid-agent	422	The document is not a valid agent. The body carries the same findings the Studio shows, and nothing was saved.
validation-blocked	409	The agent cannot go live yet because its setup is incomplete - finish the setup in the Studio, then try again.
activation-inactive	409	Nothing is live on this agent, so there is nothing to take off.
draft-archived	409	The agent is archived; restore it on My agents before writing to it or freezing a version.
capability-not-implemented	501	Amistio does not offer what the request needs, for example embedding is not configured.
storage-error	500	Amistio could not complete the request; try again later.

Endpoints

One section per operation, grouped by resource. Each sample reads your key from an environment variable and is meant to run on your server, never in a browser.

Documents

GET/openapi.json

This document

The OpenAPI 3.1 description of the partner API, generated from the same schemas the routes validate with.

ScopeNone - public while the API is onoperationIdgetOpenApiDocument

Request body

No request body.

Responses

200The OpenAPI document
404The partner API is off
The shared error body - see Errors.

Request sample

curl https://www.amistio.com/api/v1/openapi.json

GET/schemas/agent.json

The agent document's JSON Schema

The JSON Schema (draft 2020-12) of the agent document, generated from the very schema Amistio parses a Studio save with. Point your editor or CI at it to check a file before sending it. Public when the partner API is on.

ScopeNone - public while the API is onoperationIdgetAgentDocumentSchema

Request body

No request body.

Responses

200The JSON Schema document
404The partner API is off
The shared error body - see Errors.

Request sample

curl https://www.amistio.com/api/v1/schemas/agent.json

Agents

GET/agents

List your agents

Your agents with their published version pins, newest-updated first, paged by cursor.

Scopeagents:readoperationIdlistAgents

Query parameters

Query parameters
Name	Type	Required	Description
cursor	string	optional
limit	string	optional	1-100, default 20

Request body

No request body.

Responses

200One page of agents

listAgents 200
Name	Type	Required	Description
agents	array of object	required
agentId	string	required	The agent's definition id
name	string	required
description	string	optional
publishedVersionId	string \| null	required	The exact published version the agent runs, or null when nothing is live
live	boolean	required	True when a published version is active and runnable through the API
archived	boolean	required
createdAtMillis	integerminimum: 0	required	Unix time in milliseconds
updatedAtMillis	integerminimum: 0	required	Unix time in milliseconds
nextCursor	string	optional	Pass back as `cursor` to read the next page

400Malformed request (also: an API key placed in the query string)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.
429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.

Request sample

curl -H "Authorization: Bearer $AMISTIO_KEY" \
  https://www.amistio.com/api/v1/agents

GET/agents/{agentId}

One agent

One agent with its published pin, start mode, and the input form its published version expects.

Scopeagents:readoperationIdgetAgent

Path parameters

Path parameters
Name	Type	Required	Description
agentId	string	required

Request body

No request body.

Responses

200The agent

One agent in detail

getAgent 200
Name	Type	Required	Description
agentId	string	required	The agent's definition id
name	string	required
description	string	optional
publishedVersionId	string \| null	required	The exact published version the agent runs, or null when nothing is live
live	boolean	required	True when a published version is active and runnable through the API
archived	boolean	required
createdAtMillis	integerminimum: 0	required	Unix time in milliseconds
updatedAtMillis	integerminimum: 0	required	Unix time in milliseconds
startMode	string	optional	How the live version starts; present only when liveAllowed values: `manual`, `schedule`, `provider-event`, `event`, `none`
form	object \| null	required	The inputs to send in `input` when starting a run; null when nothing is live
fields	array of object	required
key	string	required	Input key this field's value lands under
label	string	required
kind	string	required	Field kind, e.g. text, long-text, number, select, photo, document
required	boolean	optional
placeholder	string	optional
help	string	optional
options	array of string	optional	Choices for select fields
min	number	optional
max	number	optional
step	number	optional

400Malformed request (also: an API key placed in the query string)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.
429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.

Request sample

curl -H "Authorization: Bearer $AMISTIO_KEY" \
  https://www.amistio.com/api/v1/agents/<agentId>

POST/agents

Create an agent from a document

Create one agent whose draft is exactly the document you send - the same document the Studio saves, checked the same way (schema, graph validation, size bounds, and no credential-shaped strings). The new agent is an ordinary agent: it appears on My agents with the Edit door, in GET /agents, and nowhere as a special type. Optional setup applies flat setup values before saving. Send an Idempotency-Key header to make retries safe: a repeat inside 24 hours with the same body returns the same agent and never creates a second one; a repeat with a different body fails with 409. Bounded at 30 document writes per minute per owner.

Scopeagents:writeoperationIdcreateAgent

Request headers

Request headers
Name	Type	Required	Description
Idempotency-Key	string	optional	Optional client-chosen key (1-200 printable ASCII characters)

Request body

Create one agent from a document

createAgent Request body
Name	Type	Required	Description
document	AgentDocument	required	The agent document - the same file the JSON Schema at /schemas/agent.json describes
setup	object (any keys)	optional	Optional flat setup values applied to the document before it is saved - a calendar-scheduled document then needs `timezone` (IANA) and `scheduleTime` (HH:MM); unknown keys are refused

Responses

200An earlier create with the same Idempotency-Key was returned

createAgent 200
Name	Type	Required	Description
agent	object	required	One agent in detail
agentId	string	required	The agent's definition id
name	string	required
description	string	optional
publishedVersionId	string \| null	required	The exact published version the agent runs, or null when nothing is live
live	boolean	required	True when a published version is active and runnable through the API
archived	boolean	required
createdAtMillis	integerminimum: 0	required	Unix time in milliseconds
updatedAtMillis	integerminimum: 0	required	Unix time in milliseconds
startMode	string	optional	How the live version starts; present only when liveAllowed values: `manual`, `schedule`, `provider-event`, `event`, `none`
form	object \| null	required	The inputs to send in `input` when starting a run; null when nothing is live
fields	array of object	required
key	string	required	Input key this field's value lands under
label	string	required
kind	string	required	Field kind, e.g. text, long-text, number, select, photo, document
required	boolean	optional
placeholder	string	optional
help	string	optional
options	array of string	optional	Choices for select fields
min	number	optional
max	number	optional
step	number	optional
draft	object	required	The agent's current draft as a document plus its revision
document	object	required
name	stringminLength: 1, maxLength: 128	required
description	stringminLength: 1, maxLength: 2048	optional
runtimeSemanticsVersion	integerminimum: 2, maximum: 1000000	optional
graph	object	required
nodes	array of any \| objectmaxItems: 256	required
edges	array of anymaxItems: 1024	required
revision	integerminimum: 0	required	Send this back as expectedRevision on the next replace or freeze
replayed	boolean	required	True when an Idempotency-Key matched an earlier create and no new agent was made

201The agent was created; the draft is at revision 0

createAgent 201
Name	Type	Required	Description
agent	object	required	One agent in detail
agentId	string	required	The agent's definition id
name	string	required
description	string	optional
publishedVersionId	string \| null	required	The exact published version the agent runs, or null when nothing is live
live	boolean	required	True when a published version is active and runnable through the API
archived	boolean	required
createdAtMillis	integerminimum: 0	required	Unix time in milliseconds
updatedAtMillis	integerminimum: 0	required	Unix time in milliseconds
startMode	string	optional	How the live version starts; present only when liveAllowed values: `manual`, `schedule`, `provider-event`, `event`, `none`
form	object \| null	required	The inputs to send in `input` when starting a run; null when nothing is live
fields	array of object	required
key	string	required	Input key this field's value lands under
label	string	required
kind	string	required	Field kind, e.g. text, long-text, number, select, photo, document
required	boolean	optional
placeholder	string	optional
help	string	optional
options	array of string	optional	Choices for select fields
min	number	optional
max	number	optional
step	number	optional
draft	object	required	The agent's current draft as a document plus its revision
document	object	required
name	stringminLength: 1, maxLength: 128	required
description	stringminLength: 1, maxLength: 2048	optional
runtimeSemanticsVersion	integerminimum: 2, maximum: 1000000	optional
graph	object	required
nodes	array of any \| objectmaxItems: 256	required
edges	array of anymaxItems: 1024	required
revision	integerminimum: 0	required	Send this back as expectedRevision on the next replace or freeze
replayed	boolean	required	True when an Idempotency-Key matched an earlier create and no new agent was made

400Malformed request (also: an API key placed in the query string)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.
409The Idempotency-Key was reused with a different body
The shared error body - see Errors.
413The request body is larger than 256 KiB
The shared error body - see Errors.

422The document is not a valid agent - the same findings the Studio shows; nothing was saved

The typed error plus the complete findings list

createAgent 422
Name	Type	Required	Description
error	object	required
code	string	required	Closed runtime error code, e.g. not-found, auth-invalid, rate-limited
message	string	required	Plain, bounded, secret-free explanation
findings	array of object	required
code	string	required	Closed finding code: one of the Studio's graph findings (e.g. trigger-missing, unknown-node-kind, graph-oversized) or schema-invalid, credential-shaped-value, runtime-semantics-unsupported
blocking	boolean	required	True when this finding alone refuses the write
nodes	array of string	required	Ids of the nodes involved
edges	array of string	required	Ids of the edges involved
path	string	optional	Dotted JSON path into the document, e.g. graph.nodes.2.config.instructions
message	string	optional	Plain words about the rule - never the refused value

429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.

Request sample

hello.agent.json is your agent file - the same document the JSON Schema describes. See the smallest valid one in the quickstart

curl -X POST -H "Authorization: Bearer $AMISTIO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-42" \
  -d "{\"document\":$(cat hello.agent.json)}" \
  https://www.amistio.com/api/v1/agents

POST/agents/validate

Check a document without saving

Run exactly the checks a create or replace runs - schema, graph validation, size bounds, credential-shaped strings - and answer 200 with ok and the complete findings list. Nothing is saved, whatever the answer. Use it in CI before you send a file.

Scopeagents:writeoperationIdvalidateAgent

Request body

Check a document without saving anything

validateAgent Request body
Name	Type	Required	Description
document	any	required	The document to check - any JSON; problems come back as findings, never as a 400

Responses

200The verdict and every finding (empty when ok)

validateAgent 200
Name	Type	Required	Description
ok	boolean	required	True when the document would be accepted as it is
findings	array of object	required	Every finding; empty when ok
code	string	required	Closed finding code: one of the Studio's graph findings (e.g. trigger-missing, unknown-node-kind, graph-oversized) or schema-invalid, credential-shaped-value, runtime-semantics-unsupported
blocking	boolean	required	True when this finding alone refuses the write
nodes	array of string	required	Ids of the nodes involved
edges	array of string	required	Ids of the edges involved
path	string	optional	Dotted JSON path into the document, e.g. graph.nodes.2.config.instructions
message	string	optional	Plain words about the rule - never the refused value

400Malformed request (also: an API key placed in the query string)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.
413The request body is larger than 256 KiB
The shared error body - see Errors.
429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.

Request sample

hello.agent.json is your agent file - the same document the JSON Schema describes. See the smallest valid one in the quickstart

curl -X POST -H "Authorization: Bearer $AMISTIO_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"document\":$(cat hello.agent.json)}" \
  https://www.amistio.com/api/v1/agents/validate

GET/agents/{agentId}/draft

Read the draft as a document

The agent's current draft as the document plus its revision - the same bytes you would write to a file, so a read followed by an unchanged write is accepted. Keep the revision: PUT and freeze require it.

Scopeagents:readoperationIdgetAgentDraft

Path parameters

Path parameters
Name	Type	Required	Description
agentId	string	required

Request body

No request body.

Responses

200The draft document and its revision

The agent's current draft as a document plus its revision

getAgentDraft 200
Name	Type	Required	Description
document	AgentDocument	required	The agent document - the same file the JSON Schema at /schemas/agent.json describes
revision	integerminimum: 0	required	Send this back as expectedRevision on the next replace or freeze

400Malformed request (also: an API key placed in the query string)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.
429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.

Request sample

curl -H "Authorization: Bearer $AMISTIO_KEY" \
  https://www.amistio.com/api/v1/agents/<agentId>/draft

PUT/agents/{agentId}/draft

Replace the draft with a document

Replace the whole draft with the document, behind the revision you read. A stale expectedRevision answers 409 with the current revision and changes nothing - never a silent overwrite. The document is checked exactly like a Studio save; blocking findings answer 422 and nothing changes. The new revision records that it was written through the API (the Studio shows "Edited through the API"). Bounded at 30 document writes per minute per owner.

Scopeagents:writeoperationIdreplaceAgentDraft

Path parameters

Path parameters
Name	Type	Required	Description
agentId	string	required

Request body

Replace the draft with a document, behind the revision you read

replaceAgentDraft Request body
Name	Type	Required	Description
document	AgentDocument	required	The agent document - the same file the JSON Schema at /schemas/agent.json describes
expectedRevision	integerminimum: 0	required	The draft revision you read; a stale value answers 409 with the current one

Responses

200The saved draft document and its new revision

The agent's current draft as a document plus its revision

replaceAgentDraft 200
Name	Type	Required	Description
document	AgentDocument	required	The agent document - the same file the JSON Schema at /schemas/agent.json describes
revision	integerminimum: 0	required	Send this back as expectedRevision on the next replace or freeze

400Malformed request (also: an API key placed in the query string)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.

409expectedRevision is stale - the body carries the current revision

The typed error plus the current draft revision

replaceAgentDraft 409
Name	Type	Required	Description
error	object	required
code	string	required	Closed runtime error code, e.g. not-found, auth-invalid, rate-limited
message	string	required	Plain, bounded, secret-free explanation
revision	integerminimum: 0	required	The draft's CURRENT revision - read, merge, and retry with it

413The request body is larger than 256 KiB
The shared error body - see Errors.

422The document is not a valid agent - the same findings the Studio shows; nothing changed

The typed error plus the complete findings list

replaceAgentDraft 422
Name	Type	Required	Description
error	object	required
code	string	required	Closed runtime error code, e.g. not-found, auth-invalid, rate-limited
message	string	required	Plain, bounded, secret-free explanation
findings	array of object	required
code	string	required	Closed finding code: one of the Studio's graph findings (e.g. trigger-missing, unknown-node-kind, graph-oversized) or schema-invalid, credential-shaped-value, runtime-semantics-unsupported
blocking	boolean	required	True when this finding alone refuses the write
nodes	array of string	required	Ids of the nodes involved
edges	array of string	required	Ids of the edges involved
path	string	optional	Dotted JSON path into the document, e.g. graph.nodes.2.config.instructions
message	string	optional	Plain words about the rule - never the refused value

429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.

Request sample

hello.agent.json is your agent file - the same document the JSON Schema describes. See the smallest valid one in the quickstart

curl -X PUT -H "Authorization: Bearer $AMISTIO_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"document\":$(cat hello.agent.json),\"expectedRevision\":0}" \
  https://www.amistio.com/api/v1/agents/<agentId>/draft

POST/agents/{agentId}/versions

Freeze a version

Freeze the draft at expectedRevision into an immutable version and return its pin and digest. The same draft frozen twice answers 200 with the existing version (outcome idempotent). A stale revision answers 409 with the current one; a draft with blocking findings answers 422 with them, exactly as the Studio refuses the same save. Bounded at 10 freezes per minute per owner.

Scopeagents:publishoperationIdfreezeAgentVersion

Path parameters

Path parameters
Name	Type	Required	Description
agentId	string	required

Request body

Freeze the draft into an immutable version

freezeAgentVersion Request body
Name	Type	Required	Description
expectedRevision	integerminimum: 0	required	The draft revision you are freezing; required, so a version is never cut from a draft you have not read

Responses

200This exact document was already frozen from this draft

freezeAgentVersion 200
Name	Type	Required	Description
version	object	required	One immutable version of an agent
versionId	string	required	The version pin
state	string	required	Allowed values: `frozen`, `published`, `archived`, `deletion-pending`, `deleted`
draftRevision	integerminimum: 0	required	The draft revision this version was frozen from
frozenAtMillis	integerminimum: 0	required	Unix time in milliseconds
contentAddress	object	required	The digest of the frozen canonical document; identical documents share it
algorithm	string	required	Allowed values: `sha256`
digest	string	required	SHA-256 of the canonical document
outcome	string	required	idempotent when this exact document was already frozen from this draftAllowed values: `frozen`, `idempotent`

201A new version was frozen

freezeAgentVersion 201
Name	Type	Required	Description
version	object	required	One immutable version of an agent
versionId	string	required	The version pin
state	string	required	Allowed values: `frozen`, `published`, `archived`, `deletion-pending`, `deleted`
draftRevision	integerminimum: 0	required	The draft revision this version was frozen from
frozenAtMillis	integerminimum: 0	required	Unix time in milliseconds
contentAddress	object	required	The digest of the frozen canonical document; identical documents share it
algorithm	string	required	Allowed values: `sha256`
digest	string	required	SHA-256 of the canonical document
outcome	string	required	idempotent when this exact document was already frozen from this draftAllowed values: `frozen`, `idempotent`

400Malformed request (also: an API key placed in the query string)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.

409expectedRevision is stale - the body carries the current revision

The typed error plus the current draft revision

freezeAgentVersion 409
Name	Type	Required	Description
error	object	required
code	string	required	Closed runtime error code, e.g. not-found, auth-invalid, rate-limited
message	string	required	Plain, bounded, secret-free explanation
revision	integerminimum: 0	required	The draft's CURRENT revision - read, merge, and retry with it

422The draft has blocking findings and cannot freeze

The typed error plus the complete findings list

freezeAgentVersion 422
Name	Type	Required	Description
error	object	required
code	string	required	Closed runtime error code, e.g. not-found, auth-invalid, rate-limited
message	string	required	Plain, bounded, secret-free explanation
findings	array of object	required
code	string	required	Closed finding code: one of the Studio's graph findings (e.g. trigger-missing, unknown-node-kind, graph-oversized) or schema-invalid, credential-shaped-value, runtime-semantics-unsupported
blocking	boolean	required	True when this finding alone refuses the write
nodes	array of string	required	Ids of the nodes involved
edges	array of string	required	Ids of the edges involved
path	string	optional	Dotted JSON path into the document, e.g. graph.nodes.2.config.instructions
message	string	optional	Plain words about the rule - never the refused value

429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.

Request sample

curl -X POST -H "Authorization: Bearer $AMISTIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0}' \
  https://www.amistio.com/api/v1/agents/<agentId>/versions

POST/agents/{agentId}/activation

Put the latest version live

Publish the latest frozen version and make it the one that runs - the Studio's Go live. Preconditions are the Studio's own: a frozen version must exist (409 version-not-published otherwise) and the agent's setup must be complete (409 validation-blocked, e.g. a Telegram channel without its bound chat). For an event-triggered agent the response carries the raw webhook token exactly once.

Scopeagents:publishoperationIdactivateAgent

Path parameters

Path parameters
Name	Type	Required	Description
agentId	string	required

Request body

No request body.

Responses

201The version is live

activateAgent 201
Name	Type	Required	Description
activation	object	required	The agent's activation: which version is live
versionId	string	required	The exact version that is live
enabled	boolean	required
activatedAtMillis	integerminimum: 0	required	Unix time in milliseconds
webhookToken	string	optional	For an event-triggered agent: the raw webhook token, shown exactly once; Amistio keeps only its digest
triggers	array of object	optional	Provider-event subscriptions this activation established
nodeId	string	required
provider	string	required
triggerKey	string	required
transport	string	required	Allowed values: `webhook`, `polling`
state	string	required	Allowed values: `registered`, `pending-manual`
ingestUrl	string	optional	Shown exactly once when a provider needs you to register the address by hand

400Malformed request (also: an API key placed in the query string)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.
409No frozen version exists, setup is incomplete, or the version cannot start (no trigger, a one-time schedule in the past)
The shared error body - see Errors.
429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.
501The version claims a runtime semantics this deployment does not interpret
The shared error body - see Errors.

Request sample

curl -X POST -H "Authorization: Bearer $AMISTIO_KEY" \
  https://www.amistio.com/api/v1/agents/<agentId>/activation

DELETE/agents/{agentId}/activation

Take the agent off

Stop the live version: runs can no longer start through the API, the run page, schedules, or webhooks. Drafts and versions are untouched; POST again to go live. Nothing live answers the Studio's own 409.

Scopeagents:publishoperationIddeactivateAgent

Path parameters

Path parameters
Name	Type	Required	Description
agentId	string	required

Request body

No request body.

Responses

204Taken off
400Malformed request (also: an API key placed in the query string)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.
409Nothing is live (activation-inactive)
The shared error body - see Errors.
429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.

Request sample

curl -X DELETE -H "Authorization: Bearer $AMISTIO_KEY" \
  https://www.amistio.com/api/v1/agents/<agentId>/activation

Runs

POST/agents/{agentId}/runs

Start a run

Start one durable run of the agent's published version. Input is validated exactly like the public run page; an input object above the run bound (49152 serialized characters) fails with 400. Send an Idempotency-Key header to make retries safe: a repeat inside 24 hours returns the same run and never starts a second one; a repeat with a different input fails with 409.

Scoperuns:startoperationIdstartRun

Path parameters

Path parameters
Name	Type	Required	Description
agentId	string	required

Request headers

Request headers
Name	Type	Required	Description
Idempotency-Key	string	optional	Optional client-chosen key (1-200 printable ASCII characters)

Request body

Start one run of the agent's published version

startRun Request body
Name	Type	Required	Description
input	object (any keys)	optional	The run input, keyed exactly like the agent's form fields; validated like the public run page

Responses

200An earlier start with the same Idempotency-Key was returned

startRun 200
Name	Type	Required	Description
run	object	required	One run: state plus the same bounded, redacted view the Amistio result page shows
runId	string	required
agentId	string	required
versionId	string	optional
state	string	required	Allowed values: `running`, `awaiting-approval`, `succeeded`, `failed`, `cancelled`
startedAtMillis	integerminimum: 0	required	Unix time in milliseconds
finishedAtMillis	integerminimum: 0	optional	Unix time in milliseconds
origin	object	required
kind	string	required	Allowed values: `manual`, `draft-test`, `webhook`, `schedule`, `share-link`, `provider-event`, `room-message`, `conversation`, `api`, `embed`
input	object (any keys)	required
outputs	object (any keys)	required	Redacted outputs; generated media keeps only descriptors
steps	array of object	required
seq	integerminimum: 0	required
kind	string	required
status	string	required	Allowed values: `ok`, `error`
startedAtMillis	integerminimum: 0	required	Unix time in milliseconds
durationMillis	integerminimum: 0	required
preview	string	required	Bounded, redacted preview of the step's output
stepsTruncated	boolean	required
error	object	optional
code	string	required
message	string	required
pendingApproval	object	optional	Present while the run waits for the owner's decision in Amistio
requiredApprovers	integerminimum: -9007199254740991	required
decisions	integerminimum: -9007199254740991	required
approvals	integerminimum: 0	required
usage	object	optional
modelCalls	integerminimum: -9007199254740991	required
toolCalls	integerminimum: -9007199254740991	required
connectorCalls	integerminimum: -9007199254740991	required
retries	integerminimum: -9007199254740991	required
cancellation	object	optional
reason	string	required	Allowed values: `user-requested`, `deadline`
requestedAtMillis	integerminimum: 0	optional	Unix time in milliseconds
replayed	boolean	required	True when an Idempotency-Key matched an earlier start and no new run began

201The run was started (it may still be running)

startRun 201
Name	Type	Required	Description
run	object	required	One run: state plus the same bounded, redacted view the Amistio result page shows
runId	string	required
agentId	string	required
versionId	string	optional
state	string	required	Allowed values: `running`, `awaiting-approval`, `succeeded`, `failed`, `cancelled`
startedAtMillis	integerminimum: 0	required	Unix time in milliseconds
finishedAtMillis	integerminimum: 0	optional	Unix time in milliseconds
origin	object	required
kind	string	required	Allowed values: `manual`, `draft-test`, `webhook`, `schedule`, `share-link`, `provider-event`, `room-message`, `conversation`, `api`, `embed`
input	object (any keys)	required
outputs	object (any keys)	required	Redacted outputs; generated media keeps only descriptors
steps	array of object	required
seq	integerminimum: 0	required
kind	string	required
status	string	required	Allowed values: `ok`, `error`
startedAtMillis	integerminimum: 0	required	Unix time in milliseconds
durationMillis	integerminimum: 0	required
preview	string	required	Bounded, redacted preview of the step's output
stepsTruncated	boolean	required
error	object	optional
code	string	required
message	string	required
pendingApproval	object	optional	Present while the run waits for the owner's decision in Amistio
requiredApprovers	integerminimum: -9007199254740991	required
decisions	integerminimum: -9007199254740991	required
approvals	integerminimum: 0	required
usage	object	optional
modelCalls	integerminimum: -9007199254740991	required
toolCalls	integerminimum: -9007199254740991	required
connectorCalls	integerminimum: -9007199254740991	required
retries	integerminimum: -9007199254740991	required
cancellation	object	optional
reason	string	required	Allowed values: `user-requested`, `deadline`
requestedAtMillis	integerminimum: 0	optional	Unix time in milliseconds
replayed	boolean	required	True when an Idempotency-Key matched an earlier start and no new run began

400Malformed request (also: an API key placed in the query string)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.
409No published version is live, or the Idempotency-Key was reused with a different input
The shared error body - see Errors.
413The request body is larger than 256 KiB
The shared error body - see Errors.
429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.

Request sample

curl -X POST -H "Authorization: Bearer $AMISTIO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-42" \
  -d '{"input":{}}' \
  https://www.amistio.com/api/v1/agents/<agentId>/runs

GET/runs

List runs of one agent

Runs of one agent you own, newest first, paged by cursor. The agent query parameter is required.

Scoperuns:readoperationIdlistRuns

Query parameters

Query parameters
Name	Type	Required	Description
cursor	string	optional
limit	string	optional	1-100, default 20
agent	string	required	The agent whose runs to list (required)

Request body

No request body.

Responses

200One page of runs

listRuns 200
Name	Type	Required	Description
runs	array of object	required
runId	string	required
agentId	string	required
versionId	string	optional
state	string	required	Allowed values: `running`, `awaiting-approval`, `succeeded`, `failed`, `cancelled`
startedAtMillis	integerminimum: 0	required	Unix time in milliseconds
finishedAtMillis	integerminimum: 0	optional	Unix time in milliseconds
origin	object	required
kind	string	required	Allowed values: `manual`, `draft-test`, `webhook`, `schedule`, `share-link`, `provider-event`, `room-message`, `conversation`, `api`, `embed`
input	object (any keys)	required
outputs	object (any keys)	required	Redacted outputs; generated media keeps only descriptors
steps	array of object	required
seq	integerminimum: 0	required
kind	string	required
status	string	required	Allowed values: `ok`, `error`
startedAtMillis	integerminimum: 0	required	Unix time in milliseconds
durationMillis	integerminimum: 0	required
preview	string	required	Bounded, redacted preview of the step's output
stepsTruncated	boolean	required
error	object	optional
code	string	required
message	string	required
pendingApproval	object	optional	Present while the run waits for the owner's decision in Amistio
requiredApprovers	integerminimum: -9007199254740991	required
decisions	integerminimum: -9007199254740991	required
approvals	integerminimum: 0	required
usage	object	optional
modelCalls	integerminimum: -9007199254740991	required
toolCalls	integerminimum: -9007199254740991	required
connectorCalls	integerminimum: -9007199254740991	required
retries	integerminimum: -9007199254740991	required
cancellation	object	optional
reason	string	required	Allowed values: `user-requested`, `deadline`
requestedAtMillis	integerminimum: 0	optional	Unix time in milliseconds
nextCursor	string	optional	Pass back as `cursor` with the same `limit` to read the next page

400Malformed request (also: an API key placed in the query string)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.
429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.

Request sample

curl -H "Authorization: Bearer $AMISTIO_KEY" \
  "https://www.amistio.com/api/v1/runs?agent=<agentId>&limit=20"

GET/runs/{runId}

One run

State plus the same bounded, redacted view the Amistio result page shows.

Scoperuns:readoperationIdgetRun

Path parameters

Path parameters
Name	Type	Required	Description
runId	string	required

Request body

No request body.

Responses

200The run

One run: state plus the same bounded, redacted view the Amistio result page shows

getRun 200
Name	Type	Required	Description
runId	string	required
agentId	string	required
versionId	string	optional
state	string	required	Allowed values: `running`, `awaiting-approval`, `succeeded`, `failed`, `cancelled`
startedAtMillis	integerminimum: 0	required	Unix time in milliseconds
finishedAtMillis	integerminimum: 0	optional	Unix time in milliseconds
origin	object	required
kind	string	required	Allowed values: `manual`, `draft-test`, `webhook`, `schedule`, `share-link`, `provider-event`, `room-message`, `conversation`, `api`, `embed`
input	object (any keys)	required
outputs	object (any keys)	required	Redacted outputs; generated media keeps only descriptors
steps	array of object	required
seq	integerminimum: 0	required
kind	string	required
status	string	required	Allowed values: `ok`, `error`
startedAtMillis	integerminimum: 0	required	Unix time in milliseconds
durationMillis	integerminimum: 0	required
preview	string	required	Bounded, redacted preview of the step's output
stepsTruncated	boolean	required
error	object	optional
code	string	required
message	string	required
pendingApproval	object	optional	Present while the run waits for the owner's decision in Amistio
requiredApprovers	integerminimum: -9007199254740991	required
decisions	integerminimum: -9007199254740991	required
approvals	integerminimum: 0	required
usage	object	optional
modelCalls	integerminimum: -9007199254740991	required
toolCalls	integerminimum: -9007199254740991	required
connectorCalls	integerminimum: -9007199254740991	required
retries	integerminimum: -9007199254740991	required
cancellation	object	optional
reason	string	required	Allowed values: `user-requested`, `deadline`
requestedAtMillis	integerminimum: 0	optional	Unix time in milliseconds

400Malformed request (also: an API key placed in the query string)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.
429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.

Request sample

curl -H "Authorization: Bearer $AMISTIO_KEY" \
  https://www.amistio.com/api/v1/runs/<runId>

Embedding

POST/embed-sessions

Mint an embed session

A short-lived signed token that lets exactly one allowed origin show the agent's public run page inside an iframe at the returned embedUrl. The frame must load within 10 minutes; the token is shown once.

Scopeembed:mintoperationIdcreateEmbedSession

Request body

Mint one short-lived embed session

createEmbedSession Request body
Name	Type	Required	Description
agentId	string	required	A live agent you own
origin	string	required	Exact site that will embed the frame, e.g. https://app.example.com; must be on your allowed list
surface	string	optional	The only surface in this sliceAllowed values: `run-page`

Responses

201The embed session

createEmbedSession 201
Name	Type	Required	Description
token	string	required	Shown once; put it in the embed URL
embedUrl	string	required	Load this URL in an iframe on the allowed origin within the first-use window
sessionId	string	required
surface	string	required	Allowed values: `run-page`
agentId	string	required
origin	string	required
createdAtMillis	integerminimum: 0	required	Unix time in milliseconds
expiresAtMillis	integerminimum: 0	required	The frame must load before this instant

400Malformed request (also: an API key placed in the query string)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.
409The origin is not on your allowed list, or no published version is live
The shared error body - see Errors.
429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.
501Embedding is not configured on this deployment
The shared error body - see Errors.

Request sample

curl -X POST -H "Authorization: Bearer $AMISTIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"<agentId>","origin":"https://app.example.com"}' \
  https://www.amistio.com/api/v1/embed-sessions

Callbacks

GET/agents/{agentId}/callbacks

List an agent's result callbacks

The callbacks registered on one agent you own, oldest first. Secrets are never listed. Every callback POST carries X-Amistio-Event-Id, X-Amistio-Timestamp (Unix seconds), and X-Amistio-Signature: sha256=<hex HMAC-SHA256(secret, "<timestamp>.<rawBody>")>. Verify with the raw secret over the raw body in constant time, refuse timestamps more than 300 seconds from your clock, and deduplicate on the event id (retries resend the same id with a fresh timestamp and signature). The registration's secretVersion tells you which secret signed after a rotation.

Scopecallbacks:manageoperationIdlistCallbacks

Path parameters

Path parameters
Name	Type	Required	Description
agentId	string	required

Request body

No request body.

Responses

200The agent's callbacks

listCallbacks 200
Name	Type	Required	Description
callbacks	array of object	required
callbackId	string	required	The registration id (cb-...)
agentId	string	required	The agent this callback belongs to
url	string	required	The https address Amistio POSTs to
description	string	optional
events	array of string	required	Which settle states are sentAllowed values: `succeeded`, `failed`, `cancelled`, `awaiting-approval`
enabled	boolean	required	False while paused: nothing new is sent
secretVersion	integerexclusiveMinimum: 0	required	Increments on every rotation; tells the receiver which secret signed a message
createdAtMillis	integerminimum: 0	required	Unix time in milliseconds
updatedAtMillis	integerminimum: 0	required	Unix time in milliseconds
disabledAtMillis	integerminimum: 0	optional	Present while paused

400Malformed request (also: an API key placed in the query string)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.
429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.

Request sample

curl -H "Authorization: Bearer $AMISTIO_KEY" \
  https://www.amistio.com/api/v1/agents/<agentId>/callbacks

POST/agents/{agentId}/callbacks

Register a result callback

Register one public https address to receive a signed message whenever a run of this agent settles (succeeded, failed, cancelled, or awaiting-approval - or only the states you list). The address is checked against the egress guard now and again before every send. The response is the ONLY time the raw secret is returned. At most 10 callbacks per agent. Every callback POST carries X-Amistio-Event-Id, X-Amistio-Timestamp (Unix seconds), and X-Amistio-Signature: sha256=<hex HMAC-SHA256(secret, "<timestamp>.<rawBody>")>. Verify with the raw secret over the raw body in constant time, refuse timestamps more than 300 seconds from your clock, and deduplicate on the event id (retries resend the same id with a fresh timestamp and signature). The registration's secretVersion tells you which secret signed after a rotation.

Scopecallbacks:manageoperationIdcreateCallback

Path parameters

Path parameters
Name	Type	Required	Description
agentId	string	required

Request body

createCallback Request body
Name	Type	Required	Description
url	stringminLength: 1, maxLength: 2048	required	Public https address, no embedded credentials or fragment; private and internal addresses are refused
events	array of stringminItems: 1, maxItems: 4	optional	Settle states to send; absent means all of themAllowed values: `succeeded`, `failed`, `cancelled`, `awaiting-approval`
description	stringmaxLength: 200	optional	A short note for yourself

Responses

201The callback with its secret, shown once

createCallback 201
Name	Type	Required	Description
callback	object	required	One result-callback registration; never carries the secret or its digest
callbackId	string	required	The registration id (cb-...)
agentId	string	required	The agent this callback belongs to
url	string	required	The https address Amistio POSTs to
description	string	optional
events	array of string	required	Which settle states are sentAllowed values: `succeeded`, `failed`, `cancelled`, `awaiting-approval`
enabled	boolean	required	False while paused: nothing new is sent
secretVersion	integerexclusiveMinimum: 0	required	Increments on every rotation; tells the receiver which secret signed a message
createdAtMillis	integerminimum: 0	required	Unix time in milliseconds
updatedAtMillis	integerminimum: 0	required	Unix time in milliseconds
disabledAtMillis	integerminimum: 0	optional	Present while paused
secret	string	required	The raw signing secret (amcb_...). Shown exactly once here and on rotate; Amistio keeps only its digest

400Malformed request, or an address that is not public https (private, loopback, link-local, and metadata ranges are refused)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.
409The agent already has 10 callbacks
The shared error body - see Errors.
429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.

Request sample

curl -X POST -H "Authorization: Bearer $AMISTIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://app.example.com/amistio/callback"}' \
  https://www.amistio.com/api/v1/agents/<agentId>/callbacks

GET/agents/{agentId}/callbacks/{callbackId}

One result callback

One callback registration on an agent you own, without its secret.

Scopecallbacks:manageoperationIdgetCallback

Path parameters

Path parameters
Name	Type	Required	Description
agentId	string	required
callbackId	string	required

Request body

No request body.

Responses

200The callback

getCallback 200
Name	Type	Required	Description
callback	object	required	One result-callback registration; never carries the secret or its digest
callbackId	string	required	The registration id (cb-...)
agentId	string	required	The agent this callback belongs to
url	string	required	The https address Amistio POSTs to
description	string	optional
events	array of string	required	Which settle states are sentAllowed values: `succeeded`, `failed`, `cancelled`, `awaiting-approval`
enabled	boolean	required	False while paused: nothing new is sent
secretVersion	integerexclusiveMinimum: 0	required	Increments on every rotation; tells the receiver which secret signed a message
createdAtMillis	integerminimum: 0	required	Unix time in milliseconds
updatedAtMillis	integerminimum: 0	required	Unix time in milliseconds
disabledAtMillis	integerminimum: 0	optional	Present while paused

400Malformed request (also: an API key placed in the query string)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.
429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.

Request sample

curl -H "Authorization: Bearer $AMISTIO_KEY" \
  https://www.amistio.com/api/v1/agents/<agentId>/callbacks/<callbackId>

PATCH/agents/{agentId}/callbacks/{callbackId}

Pause or resume a result callback

Set enabled to false to pause: nothing new is sent and a message already queued for it is skipped. Set it to true to resume. The secret and the events do not change.

Scopecallbacks:manageoperationIdupdateCallback

Path parameters

Path parameters
Name	Type	Required	Description
agentId	string	required
callbackId	string	required

Request body

Pause or resume one callback

updateCallback Request body
Name	Type	Required	Description
enabled	boolean	required	False pauses the callback; true resumes it

Responses

200The updated callback

updateCallback 200
Name	Type	Required	Description
callback	object	required	One result-callback registration; never carries the secret or its digest
callbackId	string	required	The registration id (cb-...)
agentId	string	required	The agent this callback belongs to
url	string	required	The https address Amistio POSTs to
description	string	optional
events	array of string	required	Which settle states are sentAllowed values: `succeeded`, `failed`, `cancelled`, `awaiting-approval`
enabled	boolean	required	False while paused: nothing new is sent
secretVersion	integerexclusiveMinimum: 0	required	Increments on every rotation; tells the receiver which secret signed a message
createdAtMillis	integerminimum: 0	required	Unix time in milliseconds
updatedAtMillis	integerminimum: 0	required	Unix time in milliseconds
disabledAtMillis	integerminimum: 0	optional	Present while paused

400Malformed request (also: an API key placed in the query string)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.
429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.

Request sample

curl -X PATCH -H "Authorization: Bearer $AMISTIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}' \
  https://www.amistio.com/api/v1/agents/<agentId>/callbacks/<callbackId>

DELETE/agents/{agentId}/callbacks/{callbackId}

Remove a result callback

Permanently remove the registration and its secret. Deliveries already recorded stay on their runs as evidence.

Scopecallbacks:manageoperationIddeleteCallback

Path parameters

Path parameters
Name	Type	Required	Description
agentId	string	required
callbackId	string	required

Request body

No request body.

Responses

204Removed
400Malformed request (also: an API key placed in the query string)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.
429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.

Request sample

curl -X DELETE -H "Authorization: Bearer $AMISTIO_KEY" \
  https://www.amistio.com/api/v1/agents/<agentId>/callbacks/<callbackId>

POST/agents/{agentId}/callbacks/{callbackId}/rotate-secret

Rotate a callback's secret

Mint a fresh secret and raise secretVersion. Messages sent after this call are signed with the new secret only - there is no overlap window - so update the receiver right after. The response is the only time the new secret is returned. Every callback POST carries X-Amistio-Event-Id, X-Amistio-Timestamp (Unix seconds), and X-Amistio-Signature: sha256=<hex HMAC-SHA256(secret, "<timestamp>.<rawBody>")>. Verify with the raw secret over the raw body in constant time, refuse timestamps more than 300 seconds from your clock, and deduplicate on the event id (retries resend the same id with a fresh timestamp and signature). The registration's secretVersion tells you which secret signed after a rotation.

Scopecallbacks:manageoperationIdrotateCallbackSecret

Path parameters

Path parameters
Name	Type	Required	Description
agentId	string	required
callbackId	string	required

Request body

No request body.

Responses

200The callback with its new secret, shown once

rotateCallbackSecret 200
Name	Type	Required	Description
callback	object	required	One result-callback registration; never carries the secret or its digest
callbackId	string	required	The registration id (cb-...)
agentId	string	required	The agent this callback belongs to
url	string	required	The https address Amistio POSTs to
description	string	optional
events	array of string	required	Which settle states are sentAllowed values: `succeeded`, `failed`, `cancelled`, `awaiting-approval`
enabled	boolean	required	False while paused: nothing new is sent
secretVersion	integerexclusiveMinimum: 0	required	Increments on every rotation; tells the receiver which secret signed a message
createdAtMillis	integerminimum: 0	required	Unix time in milliseconds
updatedAtMillis	integerminimum: 0	required	Unix time in milliseconds
disabledAtMillis	integerminimum: 0	optional	Present while paused
secret	string	required	The raw signing secret (amcb_...). Shown exactly once here and on rotate; Amistio keeps only its digest

400Malformed request (also: an API key placed in the query string)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.
429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.

Request sample

curl -X POST -H "Authorization: Bearer $AMISTIO_KEY" \
  https://www.amistio.com/api/v1/agents/<agentId>/callbacks/<callbackId>/rotate-secret

Deliveries

GET/runs/{runId}/deliveries

Callback deliveries for one run

Every callback delivery recorded for one run you own, oldest first: outcome (pending, delivered, failed, skipped), the closed reason, and each attempt's time, HTTP status or failure class, and bounded response excerpt. Never a secret, and never the registered address beyond its host.

Scoperuns:readoperationIdlistRunDeliveries

Path parameters

Path parameters
Name	Type	Required	Description
runId	string	required

Request body

No request body.

Responses

200The run's deliveries

listRunDeliveries 200
Name	Type	Required	Description
deliveries	array of object	required
deliveryId	string	required
callbackId	string	required	The registration this delivery was for
targetHost	string	optional	Host of the registered address (never its path or query); absent when the callback was removed
runId	string	required
agentId	string	required
versionId	string	optional
event	string	required	run.<state>, the same value as the body's `type`
eventId	string	required	Stable across retries; the receiver deduplicates on it
settledAtMillis	integerminimum: 0	required	Unix time in milliseconds
createdAtMillis	integerminimum: 0	required	Unix time in milliseconds
outcome	string	required	Allowed values: `pending`, `delivered`, `failed`, `skipped`
reason	string	optional	Closed reason for a failed or skipped outcomeAllowed values: `queue-unavailable`, `enqueue-failed`, `registration-missing`, `registration-disabled`, `run-missing`, `secret-unavailable`, `egress-denied`, `rejected`, `attempts-exhausted`
attempts	array of object	required
attempt	integerexclusiveMinimum: 0	required
atMillis	integerminimum: 0	required	Unix time in milliseconds
status	integerminimum: -9007199254740991	optional	HTTP status the receiver answered, when it answered
errorClass	string	optional	Closed failure class; never raw error textAllowed values: `timeout`, `network`, `egress-denied`, `rejected`, `server-error`, `rate-limited`
responseExcerpt	string	optional	At most 256 printable, secret-free characters of the response
nextAttemptAtMillis	integerminimum: 0	optional	Unix time in milliseconds
finishedAtMillis	integerminimum: 0	optional	Unix time in milliseconds

400Malformed request (also: an API key placed in the query string)
The shared error body - see Errors.
401No credential, or an invalid, expired, or revoked API key
The shared error body - see Errors.
403The key lacks the required scope
The shared error body - see Errors.
404Unknown or foreign id - always the same body
The shared error body - see Errors.
429Protection bound reached; wait Retry-After seconds
The shared error body - see Errors.

Request sample

curl -H "Authorization: Bearer $AMISTIO_KEY" \
  https://www.amistio.com/api/v1/runs/<runId>/deliveries

Changelog

v1.0.02026-09-20
First public release, with 14 operations.
v1.0.02026-09-21
Agents as code: 8 operations added - the document's JSON Schema, create, check, read and replace the draft, freeze a version, and put an agent live or take it off.

Not offered

Amistio does not offer an SDK, a CLI, an extension marketplace, or self-hosting today. Use the API directly with any HTTP client - every sample above is plain HTTP in its language.