Skip to main content
POST
/
v1
/
orchestrations
/
execute
Execute Orchestration
curl --request POST \
  --url https://api.truthlocks.com/v1/orchestrations/execute \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "workflow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agents": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "parameters": {}
}
'
{
  "orchestration_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workflow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agents": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "parameters": {},
  "status": "pending",
  "steps": [
    {
      "step_id": "<string>",
      "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "action": "<string>",
      "status": "<string>",
      "result": {},
      "started_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z"
    }
  ],
  "results": {},
  "receipts": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "created_at": "2023-11-07T05:31:56Z"
}
Initiates an AI orchestration execution. The orchestration engine tracks every step, LLM inference call, tool invocation, and decision point — producing a complete, transparency-log-anchored audit trail. Orchestrations are the primary unit of AI agent work in MAIP. They capture the full lifecycle of an agent’s reasoning and actions, enabling compliance teams to audit what the agent did, why it did it, and what data it consumed.

​
Authentication

​
X-API-Key
string
required
API key with orchestrations:write scope. Alternatively, pass a Bearer JWT token in the Authorization header.
​
X-Tenant-ID
string
required
Tenant identifier for multi-tenant isolation.

​
Request

​
agent_id
string
required
MAIP agent identifier executing the orchestration.
​
workflow_id
string
Optional workflow definition identifier. If provided, the orchestration follows the workflow’s DAG of steps.
​
input
object
required
Input data for the orchestration. Schema depends on the workflow definition or agent’s expected input format.
​
model
string
Default LLM model identifier to use for inference steps (e.g. claude-sonnet-4-20250514, gpt-4o). Individual steps may override this.
​
max_steps
integer
Maximum number of steps the orchestration may execute before automatic termination. Defaults to 10.
​
timeout_seconds
integer
Maximum wall-clock duration in seconds before the orchestration is timed out. Defaults to 300 (5 minutes).

​
Response

​
id
string
Unique orchestration identifier in MAIP format (maip-orch:ULID).
​
agent_id
string
The agent executing the orchestration.
​
workflow_id
string
The workflow definition identifier, if provided.
​
status
string
Execution status. Always running on creation.
​
started_at
string
ISO 8601 timestamp when execution began.

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Body

application/json
​
workflow_id
string<uuid>
required

Workflow to execute

​
agents
string<uuid>[]
required

Agents participating in the orchestration

​
parameters
object

Execution parameters

Response

Orchestration started

​
orchestration_id
string<uuid>
​
workflow_id
string<uuid>
​
agents
string<uuid>[]
​
parameters
object
​
status
enum<string>
Available options:
pending,
running,
completed,
failed,
cancelled
​
steps
object[]
​
results
object
​
receipts
string<uuid>[]
​
created_at
string<date-time>