Create an agent run

{
  "object": "run",
  "id": "id",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "status": "running",
  "thread_id": "thread_id",
  "business_id": "business_id",
  "agent": "agent",
  "requester": {
    "id": "id",
    "name": "name",
    "email": "email"
  },
  "started_at": "2024-01-15T09:30:00Z",
  "ended_at": "2024-01-15T09:30:00Z",
  "output": {
    "artifacts": [
      {
        "title": "title",
        "type": "type"
      }
    ]
  },
  "interrupts": [
    {
      "id": "id",
      "value": {
        "key": "value"
      },
      "agent": "agent"
    }
  ],
  "steps": [
    {
      "id": "id",
      "run_id": "run_id",
      "type": "activity",
      "name": "name",
      "label": "label",
      "status": "running",
      "started_at": "2024-01-15T09:30:00Z",
      "agent": "agent",
      "parent_step_id": "parent_step_id",
      "completed_at": "2024-01-15T09:30:00Z",
      "artifacts": [
        {
          "title": "title",
          "type": "type"
        }
      ]
    }
  ]
}

Creates a new agent run

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

typestringRequired

The agent type to use for this agent run

business_idstringOptionalformat: "uuid"

Business to use as context for the run. Shorthand for context_type=business. Required when thread_id is not provided (unless context_type and context_id are given).

context_typestringOptional

The type of context resource (e.g., “business”)

context_idstringOptionalformat: "uuid"

The ID of the context resource. Must be provided with context_type.

thread_idstringOptionalformat: "uuid"

Optional agent thread ID in which to execute the agent run

Response

agent run created within existing agent thread

objectstring

Object type identifier.

idstringformat: "uuid"

Unique identifier for the agent run.

created_atdatetime

Timestamp when the agent run record was created.

updated_atdatetime

Timestamp when the agent run record was last updated.

statusenum

Current lifecycle status of the agent run.

thread_idstringOptionalformat: "uuid"

Identifier of the agent thread this run belongs to.

business_idstring or nullOptionalformat: "uuid"

Middesk business the run is scoped to. Null when the run was started with an inline business payload whose business did not exist yet.

agentstringOptional

Agent type that produced this run (for example, cip_orchestrator).

requesterobject or nullOptional

Principal that initiated the run. Populated with the authenticated user’s identity when a session caller initiates the run, and with the account when an API key caller initiates the run. null for system-initiated runs.

started_atdatetime or nullOptional

Timestamp when the agent run started.

ended_atdatetime or nullOptional

Timestamp when the agent run finished.

outputobject or nullOptional

Artifact envelope produced by the agent. Non-null only when status is completed; null for running, interrupted, and error runs.

interruptslist of objectsOptional

Pending interrupt requests awaiting input. Empty when the run is not interrupted. To resume a run, POST the interrupt’s id along with the caller-supplied input to POST /v1/runs/{id}/resume.

stepslist of objectsOptional

Top-level execution steps for this run. Opt-in: pass ?include=steps on GET /v1/runs/{id} (or POST /v1/runs/{id}/resume) to populate this field. Omitted by default to avoid the cost of fetching step state from the underlying execution backend.

Errors

400

Create Agent Run Request Bad Request Error

404

Create Agent Run Request Not Found Error

422

Create Agent Run Request Unprocessable Entity Error

$	curl -X POST https://api.middesk.com/v1/runs \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"type": "cip_orchestrator"
>	}'