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, and register signed result callbacks - 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 the Builder. 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`
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`

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

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	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
201	The run was started (it may still be running) The embed session The callback with its secret, shown once	Start a run Mint an embed session Register a result callback
204	Removed	Remove a result callback
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	Every authenticated operation This document
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	Start a run Mint an embed session Register a result callback
413	The request body is larger than 256 KiB	Start a run
429	Protection bound reached; wait `Retry-After` seconds	Every authenticated operation
501	Embedding is not configured on this deployment	Mint an embed session

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.
capability-not-implemented	501	This deployment 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.

Document

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

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>

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.

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.