Skip to content
CrewhelmCrewhelmCrewhelm Docs

MCP Work

Start and inspect Runs, conversations, approvals, inbox items, and Workflows.

This reference is generated from Crewhelm’s authenticated MCP catalog and progressive operation schemas. Tool availability does not grant authority; every call is subject to the authenticated owner, approved OAuth scopes, and current control-plane policy.

Read tools

Section titled “Read tools”

Inspect state and obtain exact references without changing it.

crewhelm_inspect_work

Section titled “crewhelm_inspect_work”

Inspect Crewhelm work

Inspect active or retained work, Runs, approvals, and conversations without changing them.

Attributes: read-only, non-destructive, idempotent, closed-world.

How to use this tool:

  1. Send {"request":"operations"} to list its subtools.
  2. Send {"request":"schema","name":"…"} for one subtool’s exact inputs.
  3. Send {"request":"execute","name":"…","input":{…}} to run it.
Subtool Purpose
inspect_run Inspect one exact Run and its bounded retained detail.
list_runs List bounded Runs, optionally filtered by Agent, state, or creation time.
list_approvals List sensitive tool actions waiting for an owner decision.
list_conversations List retained conversations for one exact Agent.
inspect_conversation Inspect one exact retained Agent conversation.
list_workflows List bounded Workflows, optionally filtered by Agent or state.
inspect_workflow Inspect one exact Workflow without fetching prompts or deliverable content by default.
list_inbox List bounded matching inbox items with compact untrusted previews.
inbox_overview Summarize matching inbox items without returning individual previews.

inspect_run

Section titled “inspect_run”

Inspect one exact Run and its bounded retained detail.

Input Required Type Details
includeDeliverable No boolean Include validated JSON deliverable content. Omit for compact inspection. default: false
includeUsage No boolean Include compact admitted and consumed run usage. default: true
runId Yes string pattern: ^run_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
timelineCursor No integer minimum: 0; maximum: 9007199254740991; default: 0
timelineLimit No integer minimum: 1; maximum: 50; default: 20
View exact JSON Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "includeDeliverable": {
      "default": false,
      "description": "Include validated JSON deliverable content. Omit for compact inspection.",
      "type": "boolean"
    },
    "includeUsage": {
      "default": true,
      "description": "Include compact admitted and consumed run usage.",
      "type": "boolean"
    },
    "runId": {
      "type": "string",
      "pattern": "^run_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "timelineCursor": {
      "default": 0,
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "timelineLimit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "runId"
  ],
  "additionalProperties": false
}

list_runs

Section titled “list_runs”

List bounded Runs, optionally filtered by Agent, state, or creation time.

Input Required Type Details
agentId No string Return runs for one exact Agent. pattern: ^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
createdAfter No string Return runs created at or after this time. format: date-time
createdBefore No string Return runs created at or before this time. format: date-time
cursor No string pattern: ^run_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
limit No integer minimum: 1; maximum: 25; default: 10
status No “queued” | “running” | “cancelling” | “completed” | “cancelled” | “failed” | string Return runs in one projected state, or use “active” for queued, running, and cancelling runs.
trigger No “manual” | “schedule” | “event_trigger” | “workflow” Return manual, scheduled, event-triggered, or workflow runs.
View exact JSON Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "agentId": {
      "description": "Return runs for one exact Agent.",
      "type": "string",
      "pattern": "^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "createdAfter": {
      "description": "Return runs created at or after this time.",
      "type": "string",
      "format": "date-time"
    },
    "createdBefore": {
      "description": "Return runs created at or before this time.",
      "type": "string",
      "format": "date-time"
    },
    "cursor": {
      "type": "string",
      "pattern": "^run_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "limit": {
      "default": 10,
      "type": "integer",
      "minimum": 1,
      "maximum": 25
    },
    "status": {
      "description": "Return runs in one projected state, or use \"active\" for queued, running, and cancelling runs.",
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "queued",
            "running",
            "cancelling",
            "completed",
            "cancelled",
            "failed"
          ]
        },
        {
          "type": "string",
          "const": "active"
        }
      ]
    },
    "trigger": {
      "description": "Return manual, scheduled, event-triggered, or workflow runs.",
      "type": "string",
      "enum": [
        "manual",
        "schedule",
        "event_trigger",
        "workflow"
      ]
    }
  },
  "additionalProperties": false
}

list_approvals

Section titled “list_approvals”

List sensitive tool actions waiting for an owner decision.

Input Required Type Details
runId Yes string pattern: ^run_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
View exact JSON Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "runId": {
      "type": "string",
      "pattern": "^run_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    }
  },
  "required": [
    "runId"
  ],
  "additionalProperties": false
}

list_conversations

Section titled “list_conversations”

List retained conversations for one exact Agent.

Input Required Type Details
agentId Yes string pattern: ^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
cursor No string pattern: ^session_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
limit No integer minimum: 1; maximum: 25
View exact JSON Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "agentId": {
      "type": "string",
      "pattern": "^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "cursor": {
      "type": "string",
      "pattern": "^session_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 25
    }
  },
  "required": [
    "agentId"
  ],
  "additionalProperties": false
}

inspect_conversation

Section titled “inspect_conversation”

Inspect one exact retained Agent conversation.

Input Required Type Details
agentId Yes string pattern: ^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
sessionId Yes string pattern: ^session_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
View exact JSON Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "agentId": {
      "type": "string",
      "pattern": "^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "sessionId": {
      "type": "string",
      "pattern": "^session_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    }
  },
  "required": [
    "agentId",
    "sessionId"
  ],
  "additionalProperties": false
}

list_workflows

Section titled “list_workflows”

List bounded Workflows, optionally filtered by Agent or state.

Input Required Type Details
agentId No string Required for start; optional as an exact list filter. pattern: ^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
cursor No string For list, continue after this workflowId. pattern: ^workflow_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
limit No integer For list, bounded page size; defaults to 10. minimum: 1; maximum: 25
status No “queued” | “running” | “waiting” | “cancelling” | “completed” | “failed” | “cancelled” | string For list, return one state or use “active” for unfinished workflows.
View exact JSON Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "agentId": {
      "description": "Required for start; optional as an exact list filter.",
      "type": "string",
      "pattern": "^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "cursor": {
      "description": "For list, continue after this workflowId.",
      "type": "string",
      "pattern": "^workflow_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "limit": {
      "description": "For list, bounded page size; defaults to 10.",
      "type": "integer",
      "minimum": 1,
      "maximum": 25
    },
    "status": {
      "description": "For list, return one state or use \"active\" for unfinished workflows.",
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "queued",
            "running",
            "waiting",
            "cancelling",
            "completed",
            "failed",
            "cancelled"
          ]
        },
        {
          "type": "string",
          "const": "active"
        }
      ]
    }
  },
  "additionalProperties": false
}

inspect_workflow

Section titled “inspect_workflow”

Inspect one exact Workflow without fetching prompts or deliverable content by default.

Input Required Type Details
includePrompts No boolean For inspect only. Defaults false to avoid fetching frozen prompts.
includeDeliverable No boolean For inspect only. Defaults false to avoid fetching report content.
workflowId Yes string pattern: ^workflow_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
View exact JSON Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "includePrompts": {
      "description": "For inspect only. Defaults false to avoid fetching frozen prompts.",
      "type": "boolean"
    },
    "includeDeliverable": {
      "description": "For inspect only. Defaults false to avoid fetching report content.",
      "type": "boolean"
    },
    "workflowId": {
      "type": "string",
      "pattern": "^workflow_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    }
  },
  "required": [
    "workflowId"
  ],
  "additionalProperties": false
}

list_inbox

Section titled “list_inbox”

List bounded matching inbox items with compact untrusted previews.

Input Required Type Details
agentId No string Return items for one exact Agent. pattern: ^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
includeAcknowledged No boolean Include acknowledged items; defaults to false.
kinds No array of “action_required” | “deferred” | “exception” | “outcome” Return only these inbox kinds. minimum items: 1; maximum items: 4
needsAction No boolean Return only items that do or do not require an owner action.
occurredAfter No string Return items occurring after this time. format: date-time
severities No array of “attention_required” | “info” | “warning” Return only these deterministic severity classes. minimum items: 1; maximum items: 3
cursor No string Continue a list request after this opaque inbox item. minimum length: 1; maximum length: 255; pattern: ^inbox_(?:run_[0-9a-f-]{36}|deferred_[0-9a-f-]{36})$
limit No integer Maximum compact list items to return; defaults to 10. minimum: 1; maximum: 25
View exact JSON Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "agentId": {
      "description": "Return items for one exact Agent.",
      "type": "string",
      "pattern": "^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "includeAcknowledged": {
      "description": "Include acknowledged items; defaults to false.",
      "type": "boolean"
    },
    "kinds": {
      "description": "Return only these inbox kinds.",
      "minItems": 1,
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "action_required",
          "deferred",
          "exception",
          "outcome"
        ]
      }
    },
    "needsAction": {
      "description": "Return only items that do or do not require an owner action.",
      "type": "boolean"
    },
    "occurredAfter": {
      "description": "Return items occurring after this time.",
      "type": "string",
      "format": "date-time"
    },
    "severities": {
      "description": "Return only these deterministic severity classes.",
      "minItems": 1,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "attention_required",
          "info",
          "warning"
        ]
      }
    },
    "cursor": {
      "description": "Continue a list request after this opaque inbox item.",
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "pattern": "^inbox_(?:run_[0-9a-f-]{36}|deferred_[0-9a-f-]{36})$"
    },
    "limit": {
      "description": "Maximum compact list items to return; defaults to 10.",
      "type": "integer",
      "minimum": 1,
      "maximum": 25
    }
  },
  "additionalProperties": false
}

inbox_overview

Section titled “inbox_overview”

Summarize matching inbox items without returning individual previews.

Input Required Type Details
agentId No string Return items for one exact Agent. pattern: ^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
includeAcknowledged No boolean Include acknowledged items; defaults to false.
kinds No array of “action_required” | “deferred” | “exception” | “outcome” Return only these inbox kinds. minimum items: 1; maximum items: 4
needsAction No boolean Return only items that do or do not require an owner action.
occurredAfter No string Return items occurring after this time. format: date-time
severities No array of “attention_required” | “info” | “warning” Return only these deterministic severity classes. minimum items: 1; maximum items: 3
View exact JSON Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "agentId": {
      "description": "Return items for one exact Agent.",
      "type": "string",
      "pattern": "^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "includeAcknowledged": {
      "description": "Include acknowledged items; defaults to false.",
      "type": "boolean"
    },
    "kinds": {
      "description": "Return only these inbox kinds.",
      "minItems": 1,
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "action_required",
          "deferred",
          "exception",
          "outcome"
        ]
      }
    },
    "needsAction": {
      "description": "Return only items that do or do not require an owner action.",
      "type": "boolean"
    },
    "occurredAfter": {
      "description": "Return items occurring after this time.",
      "type": "string",
      "format": "date-time"
    },
    "severities": {
      "description": "Return only these deterministic severity classes.",
      "minItems": 1,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "attention_required",
          "info",
          "warning"
        ]
      }
    }
  },
  "additionalProperties": false
}

Write tools

Section titled “Write tools”

Preview or perform bounded changes under the required owner authority.

crewhelm_change_work

Section titled “crewhelm_change_work”

Change Crewhelm work

Start or continue work and resolve its owner decisions.

Attributes: write, destructive, idempotent, closed-world.

How to use this tool:

  1. Send {"request":"operations"} to list its subtools.
  2. Send {"request":"schema","name":"…"} for one subtool’s exact inputs.
  3. Send {"request":"execute","name":"…","input":{…}} to run it.
Subtool Purpose
run Start or continue one owner-private conversation with an exact Agent revision.
cancel_run Cancel one Run before it dispatches an external tool effect.
decide_approval Approve or reject one exact sensitive tool action waiting in a Run.
acknowledge_inbox Acknowledge one exact non-approval inbox item version.
start_workflow Start two to eight ordered Agent Runs under one durable objective.
cancel_workflow Stop future stages of one exact active Workflow revision.
delete_workflow Delete one exact terminal Workflow revision and its isolated conversation.
delete_conversation Delete one idle conversation and redact its retained prompts and inbox projections.

run

Section titled “run”

Start or continue one owner-private conversation with an exact Agent revision.

Input Required Type Details
briefs No array of object | object | object Copy-ready immutable Briefs returned by Crewhelm. maximum items: 8
conversation No object Copy-ready conversation returned by Crewhelm. Omit it to start a new conversation.
outputContract No value Optional bounded Markdown or typed JSON output contract.
message Yes string minimum length: 1; maximum length: 16384
agent Yes object Copy-ready Agent identity and immutable revision returned by Crewhelm.
requestKey No string Optional retry identity. Omit it on the ordinary happy path. minimum length: 1; maximum length: 128; pattern: ^[A-Za-z0-9._~-]+$
View exact JSON Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "briefs": {
      "maxItems": 8,
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^brief_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
              },
              "revision": {
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 100
              }
            },
            "required": [
              "id",
              "revision"
            ],
            "additionalProperties": {}
          },
          {
            "type": "object",
            "properties": {
              "currentRevision": {
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 100
              },
              "id": {
                "type": "string",
                "pattern": "^brief_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
              }
            },
            "required": [
              "currentRevision",
              "id"
            ],
            "additionalProperties": {}
          },
          {
            "type": "object",
            "properties": {
              "brief": {
                "type": "object",
                "properties": {
                  "currentRevision": {
                    "type": "integer",
                    "exclusiveMinimum": 0,
                    "maximum": 100
                  },
                  "id": {
                    "type": "string",
                    "pattern": "^brief_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
                  }
                },
                "required": [
                  "currentRevision",
                  "id"
                ],
                "additionalProperties": {}
              }
            },
            "required": [
              "brief"
            ],
            "additionalProperties": {}
          }
        ],
        "description": "Copy-ready Brief reference, summary, or create result returned by Crewhelm."
      },
      "description": "Copy-ready immutable Briefs returned by Crewhelm."
    },
    "conversation": {
      "description": "Copy-ready conversation returned by Crewhelm. Omit it to start a new conversation.",
      "type": "object",
      "properties": {
        "expectedRevision": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991,
          "description": "Exact conversation revision previously returned by Crewhelm."
        },
        "id": {
          "type": "string",
          "pattern": "^session_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
          "description": "Stable owner-private conversation identity."
        }
      },
      "required": [
        "expectedRevision",
        "id"
      ],
      "additionalProperties": false
    },
    "outputContract": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "markdown"
            }
          },
          "required": [
            "kind"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "json"
            },
            "schema": {
              "type": "object",
              "properties": {
                "jsonSchema": {
                  "type": "object",
                  "propertyNames": {
                    "type": "string"
                  },
                  "additionalProperties": {},
                  "description": "Restricted object-root JSON Schema: scalar, array, and nested object types; required, enum, and basic bounds; additionalProperties must be false. Remote references, recursion, patterns, and composition are unsupported."
                },
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 64,
                  "pattern": "^[A-Za-z][A-Za-z0-9_-]*$"
                },
                "version": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 32,
                  "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
                }
              },
              "required": [
                "jsonSchema",
                "name",
                "version"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "kind",
            "schema"
          ],
          "additionalProperties": false
        }
      ],
      "description": "Optional bounded Markdown or typed JSON output contract."
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 16384
    },
    "agent": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "id",
        "revision"
      ],
      "additionalProperties": {},
      "description": "Copy-ready Agent identity and immutable revision returned by Crewhelm."
    },
    "requestKey": {
      "description": "Optional retry identity. Omit it on the ordinary happy path.",
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9._~-]+$"
    }
  },
  "required": [
    "message",
    "agent"
  ],
  "additionalProperties": false
}

cancel_run

Section titled “cancel_run”

Cancel one Run before it dispatches an external tool effect.

Input Required Type Details
runId Yes string pattern: ^run_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
View exact JSON Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "runId": {
      "type": "string",
      "pattern": "^run_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    }
  },
  "required": [
    "runId"
  ],
  "additionalProperties": false
}

decide_approval

Section titled “decide_approval”

Approve or reject one exact sensitive tool action waiting in a Run.

Input Required Type Details
decision Yes “approve” | “reject” —
executionId Yes string minimum length: 1; maximum length: 255; pattern: ^[A-Za-z0-9._:~-]+$
runId Yes string pattern: ^run_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
View exact JSON Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "decision": {
      "type": "string",
      "enum": [
        "approve",
        "reject"
      ]
    },
    "executionId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "pattern": "^[A-Za-z0-9._:~-]+$"
    },
    "runId": {
      "type": "string",
      "pattern": "^run_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    }
  },
  "required": [
    "decision",
    "executionId",
    "runId"
  ],
  "additionalProperties": false
}

acknowledge_inbox

Section titled “acknowledge_inbox”

Acknowledge one exact non-approval inbox item version.

Input Required Type Details
itemId Yes string minimum length: 1; maximum length: 255; pattern: ^inbox_(?:run_[0-9a-f-]{36}|deferred_[0-9a-f-]{36})$
version Yes string Exact item version returned by Crewhelm to acknowledge. format: date-time
View exact JSON Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "itemId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "pattern": "^inbox_(?:run_[0-9a-f-]{36}|deferred_[0-9a-f-]{36})$"
    },
    "version": {
      "type": "string",
      "format": "date-time",
      "description": "Exact item version returned by Crewhelm to acknowledge."
    }
  },
  "required": [
    "itemId",
    "version"
  ],
  "additionalProperties": false
}

start_workflow

Section titled “start_workflow”

Start two to eight ordered Agent Runs under one durable objective.

Input Required Type Details
briefs No array of object | object | object Copy-ready immutable Briefs returned by Crewhelm. maximum items: 8
objective Yes string minimum length: 1; maximum length: 4096
outputContract No value Optional bounded Markdown or typed JSON output contract.
stages Yes array of object minimum items: 2; maximum items: 8
agent Yes object Copy-ready Agent identity and immutable revision returned by Crewhelm.
requestKey No string Optional retry identity. Omit it on the ordinary happy path. minimum length: 1; maximum length: 128; pattern: ^[A-Za-z0-9._~-]+$
View exact JSON Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "briefs": {
      "maxItems": 8,
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^brief_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
              },
              "revision": {
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 100
              }
            },
            "required": [
              "id",
              "revision"
            ],
            "additionalProperties": {}
          },
          {
            "type": "object",
            "properties": {
              "currentRevision": {
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 100
              },
              "id": {
                "type": "string",
                "pattern": "^brief_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
              }
            },
            "required": [
              "currentRevision",
              "id"
            ],
            "additionalProperties": {}
          },
          {
            "type": "object",
            "properties": {
              "brief": {
                "type": "object",
                "properties": {
                  "currentRevision": {
                    "type": "integer",
                    "exclusiveMinimum": 0,
                    "maximum": 100
                  },
                  "id": {
                    "type": "string",
                    "pattern": "^brief_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
                  }
                },
                "required": [
                  "currentRevision",
                  "id"
                ],
                "additionalProperties": {}
              }
            },
            "required": [
              "brief"
            ],
            "additionalProperties": {}
          }
        ],
        "description": "Copy-ready Brief reference, summary, or create result returned by Crewhelm."
      },
      "description": "Copy-ready immutable Briefs returned by Crewhelm."
    },
    "objective": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    },
    "outputContract": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "markdown"
            }
          },
          "required": [
            "kind"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "json"
            },
            "schema": {
              "type": "object",
              "properties": {
                "jsonSchema": {
                  "type": "object",
                  "propertyNames": {
                    "type": "string"
                  },
                  "additionalProperties": {},
                  "description": "Restricted object-root JSON Schema: scalar, array, and nested object types; required, enum, and basic bounds; additionalProperties must be false. Remote references, recursion, patterns, and composition are unsupported."
                },
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 64,
                  "pattern": "^[A-Za-z][A-Za-z0-9_-]*$"
                },
                "version": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 32,
                  "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
                }
              },
              "required": [
                "jsonSchema",
                "name",
                "version"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "kind",
            "schema"
          ],
          "additionalProperties": false
        }
      ],
      "description": "Optional bounded Markdown or typed JSON output contract."
    },
    "stages": {
      "minItems": 2,
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "delayBeforeSeconds": {
            "type": "integer",
            "minimum": 0,
            "maximum": 604800,
            "description": "Durable delay before this stage is admitted. Sleeping consumes no Run budget."
          },
          "deferral": {
            "type": "object",
            "properties": {
              "maxWaitSeconds": {
                "default": 3600,
                "description": "Maximum elapsed time this stage may defer itself while waiting for external work. The Agent chooses each bounded resume delay.",
                "type": "integer",
                "minimum": 30,
                "maximum": 604800
              }
            },
            "additionalProperties": false,
            "description": "Permit this Workflow stage to checkpoint as waiting and resume as a fresh bounded Run until done or the elapsed-time ceiling is reached."
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "Short progress label for one ordered stage."
          },
          "prompt": {
            "type": "string",
            "minLength": 1,
            "maxLength": 11264,
            "description": "One bounded Run instruction. Crewhelm admits it with the shared objective and exact durable Session produced by the prior stage."
          }
        },
        "required": [
          "name",
          "prompt"
        ],
        "additionalProperties": false
      }
    },
    "agent": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "id",
        "revision"
      ],
      "additionalProperties": {},
      "description": "Copy-ready Agent identity and immutable revision returned by Crewhelm."
    },
    "requestKey": {
      "description": "Optional retry identity. Omit it on the ordinary happy path.",
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9._~-]+$"
    }
  },
  "required": [
    "objective",
    "stages",
    "agent"
  ],
  "additionalProperties": false
}

cancel_workflow

Section titled “cancel_workflow”

Stop future stages of one exact active Workflow revision.

Input Required Type Details
workflow Yes object —
View exact JSON Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "workflow": {
      "type": "object",
      "properties": {
        "workflowId": {
          "type": "string",
          "pattern": "^workflow_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "workflowId",
        "revision"
      ],
      "additionalProperties": {}
    }
  },
  "required": [
    "workflow"
  ],
  "additionalProperties": false
}

delete_workflow

Section titled “delete_workflow”

Delete one exact terminal Workflow revision and its isolated conversation.

Input Required Type Details
workflow Yes object —
requestKey No string Optional retry identity. Omit it on the ordinary happy path. minimum length: 1; maximum length: 128; pattern: ^[A-Za-z0-9._~-]+$
View exact JSON Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "workflow": {
      "type": "object",
      "properties": {
        "workflowId": {
          "type": "string",
          "pattern": "^workflow_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "workflowId",
        "revision"
      ],
      "additionalProperties": {}
    },
    "requestKey": {
      "description": "Optional retry identity. Omit it on the ordinary happy path.",
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9._~-]+$"
    }
  },
  "required": [
    "workflow"
  ],
  "additionalProperties": false
}

delete_conversation

Section titled “delete_conversation”

Delete one idle conversation and redact its retained prompts and inbox projections.

Input Required Type Details
agentId Yes string pattern: ^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
conversation Yes object Copy-ready conversation returned by Crewhelm Run or conversation inspection.
requestKey No string Optional retry identity. Omit it on the ordinary happy path. minimum length: 1; maximum length: 128; pattern: ^[A-Za-z0-9._~-]+$
View exact JSON Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "agentId": {
      "type": "string",
      "pattern": "^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "conversation": {
      "type": "object",
      "properties": {
        "expectedRevision": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991,
          "description": "Exact conversation revision previously returned by Crewhelm."
        },
        "id": {
          "type": "string",
          "pattern": "^session_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
          "description": "Stable owner-private conversation identity."
        }
      },
      "required": [
        "expectedRevision",
        "id"
      ],
      "additionalProperties": false,
      "description": "Copy-ready conversation returned by Crewhelm Run or conversation inspection."
    },
    "requestKey": {
      "description": "Optional retry identity. Omit it on the ordinary happy path.",
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9._~-]+$"
    }
  },
  "required": [
    "agentId",
    "conversation"
  ],
  "additionalProperties": false
}