HTTP: run

Default control-plane operations. Complete OpenAPI schema · Authentication and tenancy.

POST /api/run

Run Agent

Operation ID: run_agent_api_run_post.

Parameter	Location	Required	Schema
Cayu-Mutation-ID	header	False	{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._~-]*$"},{"type":"null"}],"description":"Client-generated mutation identity used to correlate an ambiguous SSE reconnect with its durable server acceptance event. Send the same value on the initial mutation and every Last-Event-ID replay request; it is a replay correlation key, not permission to repeat the POST.","title":"Cayu-Mutation-Id"}

Request body

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/RunBody"
      }
    }
  }
}

Model declarations: RunBody.

Responses

{
  "200": {
    "description": "Server-Sent Events stream. Each runtime event is emitted as an SSE frame whose `data:` value is a JSON SseEventEnvelope. A classified terminal runtime or observer condition is emitted as `event: error` with a SseErrorEnvelope payload.",
    "content": {
      "text/event-stream": {
        "schema": {
          "type": "string",
          "description": "SSE stream. Runtime `data:` frames contain SseEventEnvelope JSON; `event: error` frames contain SseErrorEnvelope JSON."
        }
      }
    }
  },
  "404": {
    "description": "The replay session or mutation target does not exist.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiErrorResponse"
        }
      }
    }
  },
  "409": {
    "description": "The replay event marker is unknown or the mutation conflicts with the current session state.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiErrorResponse"
        }
      }
    }
  },
  "500": {
    "description": "The mutation could not open an accepted durable stream.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiErrorResponse"
        }
      }
    }
  },
  "413": {
    "description": "The control-plane request exceeds its encoded byte limit.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiErrorResponse"
        }
      }
    }
  },
  "400": {
    "description": "The authenticated caller identity cannot be represented as durable invocation provenance.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiErrorResponse"
        }
      }
    }
  },
  "422": {
    "description": "Validation Error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/HTTPValidationError"
        }
      }
    }
  }
}

Model declarations: ApiErrorResponse, HTTPValidationError.