Skip to main content
POST
Execute Orchestration
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

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

Request

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

Response

string
Unique orchestration identifier in MAIP format (maip-orch:ULID).
string
The agent executing the orchestration.
string
The workflow definition identifier, if provided.
string
Execution status. Always running on creation.
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>