AOP API

Use the developer AOP API to run saved Agent Operating Procedures from an external system. Interactive playground: API reference · Spec: openapi.json

Authentication

Authorization: Bearer $OMNI_API_KEY
Content-Type: application/json

Endpoint	Required scope
`POST /api/v1/aop/{aopId}/execute`	`aops:write`
`POST /api/v1/aop/retry`	`aops:write`
`POST /api/v1/aop/create`	`aops:write`
`PUT /api/v1/aop/{aopId}/config`	`aops:write`
`GET /api/v1/aop/{aopId}/config`	`aops:read`
`GET /api/v1/threads/{thread_id}/status`	`aops:read`

API keys created from organization settings receive all developer scopes by default. Existing keys created before this API shipped need aops:read / aops:write added in organization settings.

OAuth clients must include the scope on the client. Session-authenticated calls must include organizationId in the query (GET) or JSON body (writes). Do not send organizationId for API-key requests. aopId in the path (and aop_id in JSON responses) is the OmniCommerce AOP id from /app/{organizationId}/aops.

Execute an AOP

POST /api/v1/aop/{aopId}/execute

Start the run

The AOP id is in the path. Optional user_inputs go in the JSON body. The response returns immediately with a thread_id.

curl -X POST "https://omnicommerce.sg/api/v1/aop/aop_1/execute" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_inputs": {
      "company": "Acme Corp",
      "quarter": "Q1 2024"
    }
  }'

Poll until terminal

curl "https://omnicommerce.sg/api/v1/threads/THREAD_ID/status" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Status values: running, completed, failed. Terminal responses include conversation messages by default. Pass include_messages=true to force messages while the run is still in progress.

Request body

Field	Required	Description
`user_inputs`	No	Key/value inputs appended as a `--- User Inputs ---` block and bound to `[[ placeholder ]]` variables.
`dry_run`	No	When `true`, run as a Test run: read-only tools execute, side-effectful tools are captured.
`organizationId`	Session	Required for session auth.

Response

{
  "status": "started",
  "thread_id": "agent-aop-run_1",
  "trigger_type": "api",
  "aop_id": "aop_1",
  "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\nquarter: Q1 2024\n",
  "aop_config": { "agentId": "research" },
  "sync_server": "https://omnicommerce.sg",
  "message": "Task execution started successfully. Use the thread_id to track progress."
}

trigger_type is always api for this endpoint. sync_server is the OmniCommerce origin and can be ignored.

Poll status

GET /api/v1/threads/{thread_id}/status

curl "https://omnicommerce.sg/api/v1/threads/agent-aop-run_1/status?include_messages=true" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Query	Description
`include_messages`	`true` to include messages while the run is still in progress. Terminal runs include them by default.
`organizationId`	Session auth only.

conversation_asset includes linked_aops, last_message, and metadata.run_status (including awaiting_approval).

Retry a failed run

POST /api/v1/aop/retry

curl -X POST "https://omnicommerce.sg/api/v1/aop/retry" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "thread_id": "agent-aop-run_1" }'

Only failed AOP runs can be retried. Optional user_inputs replace the original values; omit them to reuse the failed run’s inputs. Response:

{
  "status": "started",
  "new_thread_id": "agent-aop-run_2",
  "message": "Retry execution started successfully."
}

Create an AOP

POST /api/v1/aop/create

curl -X POST "https://omnicommerce.sg/api/v1/aop/create" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Market Research Report",
    "prompt": "Generate a comprehensive market research report for [[ company ]]",
    "agentId": "research"
  }'

Use [[ placeholder ]] in the prompt for execution-time inputs. Omni validates a name of at least 2 characters and a prompt of at least 10 characters.

Field	Description
`title`	AOP name. Defaults to `Untitled AOP`.
`prompt`	Instructions. `[[ company ]]` becomes a `user_inputs.company` field.
`agentId`	Assigned agent template id. Defaults to OmniBot.
`structured_output`	JSON Schema for structured results.
`agent_config`	Optional `chatModel` / `planModeEnabled`. Does not grant extra tools.
`parent_folder_id`	Optional workstream id.
`user_notification_configs`	Per-user outcome notification map.
`organizationId`	Session auth only.

Response includes aop_id, title, status: "created", and parent_folder_id.

Read and overwrite config

GET /api/v1/aop/{aopId}/config
PUT /api/v1/aop/{aopId}/config

GET returns prompt, agentId, structured_inputs (computed from placeholders), structured_output, and notification settings. PUT updates provided fields only. Omitted fields keep their current values. Send user_notification_configs: null to clear notification overrides.

curl "https://omnicommerce.sg/api/v1/aop/aop_1/config" \
  -H "Authorization: Bearer $OMNI_API_KEY"

curl -X PUT "https://omnicommerce.sg/api/v1/aop/aop_1/config" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Generate a weekly pricing brief for [[ marketplace ]]",
    "agentId": "pricing"
  }'

Errors

Status	Meaning
`400`	Invalid JSON, missing `thread_id`, failed-run retry on a non-failed thread, or AOP draft validation.
`401`	Missing or invalid bearer token.
`402`	Organization is out of AI credits.
`403`	Token is missing `aops:read` or `aops:write`.
`404`	AOP or thread was not found in the authenticated organization.
`429`	Rate limit. Retry later.

Field notes

Field	Meaning
`aop_id`	Organization AOP id
`organizationId`	Session auth organization id
`user_inputs`	AOP variable values
`parent_folder_id`	Assigned workstream id
`dry_run`	Test run (`simulation: { "mode": "read_only" }`)

Get started

Guides

Webhooks

MCP

Authentication

Execute an AOP

Request body

Response

Poll status

Retry a failed run

Create an AOP

Read and overwrite config

Errors

Field notes

​Authentication

​Execute an AOP

​Request body

​Response

​Poll status

​Retry a failed run

​Create an AOP

​Read and overwrite config

​Errors

​Field notes

Authentication

Execute an AOP

Request body

Response

Poll status

Retry a failed run

Create an AOP

Read and overwrite config

Errors

Field notes