Execute Agent Operating Procedure Asynchronously

Beta

POST

https://api.athenaintel.com/api/v0/aop/execute-async

POST

/api/v0/aop/execute-async

curl -X POST https://api.athenaintel.com/api/v0/aop/execute-async \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "asset_id": "asset_9249292-d118-42d3-95b4-00eccfe0754f",
  "run_budget": {
    "max_cost_usd": 30,
    "max_model_calls": 80
  },
  "user_inputs": {
    "company": "Acme Corp",
    "quarter": "Q1 2024"
  }
}'

{
  "aop_asset_id": "asset_9249292-d118-42d3-95b4-00eccfe0754f",
  "aop_config": {
    "agentId": "research_agent"
  },
  "aop_title": "Market Research Report Generator",
  "base_prompt": "Generate a comprehensive market research report",
  "final_prompt": "Generate a comprehensive market research report\n\n--- User Inputs ---\ncompany: Acme Corp\n",
  "message": "Task execution started successfully. Use the thread_id to track progress.",
  "status": "started",
  "sync_server": "https://iris.prd.athenaintel.com",
  "thread_id": "thread_12345-6789-abcd-efgh",
  "trigger_type": "api"
}

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

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

Authentication

Headers

Request

Response

Errors