Building a webhook integration? Read the webhook guide for signatures, retries, event schemas, and troubleshooting.

apiDeterministic

Claim agent work order

POST /api/agents/work-orders/external/claim

Lease one claimable Agent Teams work order for execution inside an external coding agent. Returns a versioned execution bundle containing the same Pipeline-owned first-party skill loadout, authority order, task context, allowed tools, and output schema used by hosted Agent Teams. The external agent uses its own subscription for inference. Claiming marks the work order running and never authorizes launch or sending.

Parameters

workspaceId

string

Optional with an API key, inferred from the key.

workOrderIdrequired

string

The claimable work order id from list-agent-work-orders.

clientNamerequired

string

Coding agent client name, for example codex, claude-code, or hermes.

clientRunIdrequired

string

Caller-stable run identifier used for traceability.

leaseSeconds

number

Optional lease duration from 60 to 3600 seconds.

nativeCapabilities

string[]

Optional native research capabilities available in the claiming client.

freshnessWindowHours

integer

Optional maximum evidence age in hours. Zero requires current evidence.

requiresScale

boolean

Whether the claimed work is expected to continue from pilot into scale.

Example

REST requestbash

curl -X POST "https://app.pipeline.help/api/agents/work-orders/external/claim" \
  -H "Authorization: Bearer $PIPELINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workOrderId":"00000000-0000-4000-8000-000000000000","clientName":"example","clientRunId":"00000000-0000-4000-8000-000000000000"}'

Response

Success response schemajson schema

{
  "type": "object",
  "properties": {
    "claim": {
      "type": "object",
      "properties": {
        "workOrderId": {
          "type": "string"
        },
        "claimToken": {
          "type": "string"
        },
        "clientName": {
          "type": "string"
        },
        "clientRunId": {
          "type": "string"
        },
        "leaseExpiresAt": {
          "type": "string"
        },
        "bundle": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "version": {
              "type": "number"
            },
            "workspaceId": {
              "type": "string"
            },
            "workOrderId": {
              "type": "string"
            },
            "agentRole": {
              "type": "string"
            },
            "taskType": {
              "type": "string"
            },
            "executionMode": {
              "type": "string",
              "enum": [
                "external_agent"
              ]
            },
            "objective": {
              "type": "string"
            },
            "authority": {
              "type": "object"
            },
            "skills": {
              "type": "object"
            },
            "context": {
              "type": "object"
            },
            "allowedTools": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "outputSchema": {
              "type": "object"
            },
            "provenance": {
              "type": "object"
            },
            "expiresAt": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "version",
            "workspaceId",
            "agentRole",
            "taskType",
            "executionMode",
            "objective",
            "authority",
            "skills",
            "context",
            "allowedTools",
            "outputSchema",
            "provenance",
            "expiresAt"
          ]
        }
      },
      "required": [
        "workOrderId",
        "claimToken",
        "clientName",
        "clientRunId",
        "leaseExpiresAt",
        "bundle"
      ]
    }
  },
  "required": [
    "claim"
  ]
}

HTTP errors

401: Missing or invalid API key.
403: Authenticated but not permitted for the workspace or resource.
404: The requested resource was not found.