> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute Orchestration

> Start an AI orchestration execution with full provenance tracking and step-level auditing.

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

<ParamField header="X-API-Key" type="string" required>
  API key with `orchestrations:write` scope. Alternatively, pass a Bearer JWT
  token in the `Authorization` header.
</ParamField>

<ParamField header="X-Tenant-ID" type="string" required>
  Tenant identifier for multi-tenant isolation.
</ParamField>

### Request

<ParamField body="agent_id" type="string" required>
  MAIP agent identifier executing the orchestration.
</ParamField>

<ParamField body="workflow_id" type="string">
  Optional workflow definition identifier. If provided, the orchestration
  follows the workflow's DAG of steps.
</ParamField>

<ParamField body="input" type="object" required>
  Input data for the orchestration. Schema depends on the workflow definition or
  agent's expected input format.
</ParamField>

<ParamField body="model" type="string">
  Default LLM model identifier to use for inference steps (e.g.
  `claude-sonnet-4-20250514`, `gpt-4o`). Individual steps may override this.
</ParamField>

<ParamField body="max_steps" type="integer">
  Maximum number of steps the orchestration may execute before automatic
  termination. Defaults to `10`.
</ParamField>

<ParamField body="timeout_seconds" type="integer">
  Maximum wall-clock duration in seconds before the orchestration is timed out.
  Defaults to `300` (5 minutes).
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique orchestration identifier in MAIP format (`maip-orch:ULID`).
</ResponseField>

<ResponseField name="agent_id" type="string">
  The agent executing the orchestration.
</ResponseField>

<ResponseField name="workflow_id" type="string">
  The workflow definition identifier, if provided.
</ResponseField>

<ResponseField name="status" type="string">
  Execution status. Always `running` on creation.
</ResponseField>

<ResponseField name="started_at" type="string">
  ISO 8601 timestamp when execution began.
</ResponseField>


## OpenAPI

````yaml mint-openapi.yaml POST /v1/orchestrate/execute
openapi: 3.0.3
info:
  title: Truthlocks API
  description: >
    Truthlocks is a universal verification infrastructure for documents,
    credentials, and digital assets.

    This specification defines the canonical API for interacting with Truthlocks
    services.


    ## Base URLs

    - **Production**: `https://api.truthlocks.com`

    - **Sandbox**: `https://sandbox-api.truthlocks.com`


    ## Authentication

    - **API Keys**: Use `X-API-Key` header for machine-to-machine operations

    - **Bearer Tokens**: Use `Authorization: Bearer <jwt>` for user-initiated
    operations


    ## Tenant Identity

    In production, tenant identity is derived from the authenticated context
    (API key or JWT).

    The `X-Tenant-ID` header is ignored in production to prevent spoofing.
  version: 1.0.0
  contact:
    name: Truthlocks Support
    url: https://truthlocks.com/support
    email: support@truthlocks.com
servers:
  - url: https://api.truthlocks.com
    description: Production API
  - url: https://sandbox-api.truthlocks.com
    description: Sandbox Environment
security:
  - APIKey: []
tags:
  - name: Authentication
    description: API key and token management
  - name: Issuers
    description: Issuer registration and trust management
  - name: Keys
    description: Cryptographic key management for issuers
  - name: Attestations
    description: Attestation lifecycle (mint, revoke, supersede)
  - name: Verification
    description: Attestation verification and proof bundles
  - name: Governance
    description: Issuer governance workflows (admin only)
  - name: Identity
    description: Organization, user, and role management
  - name: Audit
    description: Audit event queries
  - name: Platform
    description: Platform administration (super admin only)
  - name: Platform Review
    description: Staff review workflows for issuer applications
  - name: Tenant Console
    description: Tenant profile and lifecycle endpoints
  - name: Health
    description: Service health and readiness endpoints
  - name: Risk
    description: Risk signal ingestion and fraud detection
  - name: Risk Enforcement
    description: Risk enforcement actions — block, challenge, quarantine, and configuration
  - name: Billing
    description: Billing, subscription, and addon management
  - name: Machine Identity
    description: >-
      Machine Agent Identity Protocol (MAIP) — agent registration, sessions,
      trust, witness, compliance, orchestration, and observability
externalDocs:
  description: Transparency read-only API (separate service spec)
  url: >-
    https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
  /v1/orchestrate/execute:
    post:
      tags:
        - Machine Identity
      summary: Execute Orchestration
      description: |
        Starts an orchestration that coordinates multiple agents to execute a
        workflow. Each step produces a receipt for full auditability.
      operationId: maip.orchestrations.execute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - workflow_id
                - agents
              properties:
                workflow_id:
                  type: string
                  format: uuid
                  description: Workflow to execute
                agents:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: Agents participating in the orchestration
                parameters:
                  type: object
                  additionalProperties: true
                  description: Execution parameters
      responses:
        '201':
          description: Orchestration started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaipOrchestration'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - APIKey: []
components:
  schemas:
    MaipOrchestration:
      type: object
      properties:
        orchestration_id:
          type: string
          format: uuid
        workflow_id:
          type: string
          format: uuid
        agents:
          type: array
          items:
            type: string
            format: uuid
        parameters:
          type: object
          additionalProperties: true
        status:
          type: string
          enum:
            - pending
            - running
            - completed
            - failed
            - cancelled
        steps:
          type: array
          items:
            type: object
            properties:
              step_id:
                type: string
              agent_id:
                type: string
                format: uuid
              action:
                type: string
              status:
                type: string
              result:
                type: object
                additionalProperties: true
              started_at:
                type: string
                format: date-time
              completed_at:
                type: string
                format: date-time
        results:
          type: object
          additionalProperties: true
        receipts:
          type: array
          items:
            type: string
            format: uuid
        created_at:
          type: string
          format: date-time
    ErrorEnvelope:
      type: object
      required:
        - code
        - message
        - http_status
      properties:
        code:
          type: string
          description: Machine-readable error code
          enum:
            - AUTH_REQUIRED
            - AUTH_INVALID
            - PERMISSION_DENIED
            - TENANT_IDENTITY_UNVERIFIED
            - NOT_FOUND
            - VALIDATION_ERROR
            - CONFLICT
            - PAYLOAD_TOO_LARGE
            - RATE_LIMIT_EXCEEDED
            - QUOTA_EXCEEDED
            - SERVICE_UNAVAILABLE
            - INTERNAL_ERROR
        message:
          type: string
          description: Human-readable error message
        http_status:
          type: integer
          description: HTTP status code
        retry_after_ms:
          type: integer
          description: Milliseconds to wait before retrying (for rate limits)
        details:
          type: object
          description: Additional error context
      example:
        code: AUTH_REQUIRED
        message: Authentication required
        http_status: 401
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for machine-to-machine authentication

````