API ReferenceAop

Execute Agent Operating Procedure Asynchronously

Beta
Start execution of an Agent Operating Procedure (AOP) asset asynchronously. Returns immediately with a thread_id for tracking execution progress without waiting for completion. Send an `Idempotency-Key` header to make the launch safe to retry: if the response is lost, repeating the identical request with the same key returns the original `thread_id` (with `deduplicated: true`) instead of starting a second run. Keys are private to your account; reusing a key with different parameters is rejected with 422, and a retry that races the first attempt gets 409.

Authentication

X-API-KEYstring
API Key authentication via header

Headers

Idempotency-Keystring or nullOptional1-256 characters

Optional caller-chosen key that makes this launch safe to retry. Repeating the identical request with the same key replays the original response instead of starting another run.

Request

This endpoint expects an object.
asset_idstringRequired
ID of the existing AOP asset to execute
dry_runbooleanOptionalDefaults to false

Execute the AOP in dry-run mode: the agent runs with its real prompt, config, and read-only tools, but side-effectful tool calls (emails, external writes) are validated and captured instead of executed. The session remains visible and is marked with athena_metadata.is_dry_run for UI badging.

run_budgetobject or nullOptional

Optional spend cap for this execution: max_model_calls (top-level and sub-agent model calls) and/or max_cost_usd (provider cost at Athena’s model pricing). When a limit is reached the run stops before the next model call, ends with athena_termination_reason=run_budget, and the AOP execution settles as not succeeded. Absent = no cap beyond the agent’s step limit.

user_inputsmap from strings to strings or nullOptional

Optional user inputs to append to the AOP’s prompt as key-value pairs

Response

AOP execution started successfully
aop_asset_idstring
ID of the AOP asset that was executed
aop_configmap from strings to any
Full configuration of the AOP asset
aop_titlestring
Title of the AOP asset
base_promptstring
Base prompt of the AOP before user inputs were added
final_promptstring
Final prompt used for execution including user inputs
messagestring
Status message about the async execution
statusstring

Status of the execution (always ‘started’ for async)

sync_serverstring
Sync server URL used for execution
thread_idstring
Unique thread ID for tracking the execution
trigger_typestring
Type of trigger that initiated the execution
deduplicatedbooleanOptionalDefaults to false

True when this response replays an earlier launch with the same Idempotency-Key; no new run was started.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
500
Internal Server Error