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

apiDeterministic

Claim agent chat turn

POST /api/agents/conversations

Claim an external Agent Teams chat turn for ten minutes. Returns the addressed role, user input, saved history, selected skill, constraints and claimToken. Use your current coding-agent model, not Pipeline hosted inference. The UI shows this turn as running. Claims are principal/workspace scoped and cannot claim hosted turns.

Parameters

workspaceId

string

No description.

actionrequired

string

No description.

turnIdrequired

string

No description.

Example

REST requestbash

curl -X POST "https://app.pipeline.help/api/agents/conversations" \
  -H "Authorization: Bearer $PIPELINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"external_claim","turnId":"00000000-0000-4000-8000-000000000000"}'

Response

Success response schemajson schema

{
  "type": "object",
  "properties": {
    "turnId": {
      "type": "string"
    },
    "conversationId": {
      "type": "string"
    },
    "claimToken": {
      "type": "string"
    },
    "leaseExpiresAt": {
      "type": "string"
    },
    "executionMode": {
      "type": "string",
      "enum": [
        "external_agent"
      ]
    },
    "role": {
      "type": "string"
    },
    "roleDescription": {
      "type": "string"
    },
    "instructions": {
      "type": "string"
    },
    "surfaceContext": {
      "type": [
        "object",
        "null"
      ]
    },
    "input": {
      "type": "object"
    },
    "history": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "selectedSkill": {
      "type": [
        "object",
        "null"
      ]
    },
    "delegatedResults": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "required": [
    "turnId",
    "conversationId",
    "claimToken",
    "leaseExpiresAt",
    "executionMode",
    "role",
    "roleDescription",
    "instructions",
    "surfaceContext",
    "input",
    "history",
    "selectedSkill",
    "delegatedResults"
  ]
}

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.