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

apiHosted AI, explicit consent

Run skill

POST /api/skills/run

Run a Pipeline-owned first-party skill through Pipeline hosted inference. This consumes the workspace BYOK model provider, not the coding agent subscription. For execution inside Claude Code, Codex, Hermes, or another external agent, claim an Agent Teams work order instead. Returns a hosted run summary including the runId for get-agent-run.

Parameters

workspaceId

string

Optional workspace ID or slug. Required when this credential can access multiple workspaces and no workspace was configured on the client.

skillNamerequired

string

The skill name from frontmatter (e.g. dream-one-hundred, cold-email-write).

payload

object

Arbitrary input passed to the skill.

agentRole

string

Optional: pin which agent role context to use.

allowHostedAi

boolean

Must be true when this operation uses Pipeline hosted inference.

Example

REST requestbash

curl -X POST "https://app.pipeline.help/api/skills/run" \
  -H "Authorization: Bearer $PIPELINE_API_KEY" \
  -H "X-Pipeline-Execution-Policy: hosted-enabled" \
  -H "Content-Type: application/json" \
  -d '{"skillName":"example","allowHostedAi":true}'

Response

Success response schemajson schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "terminationReason": {
      "type": "string"
    },
    "toolCalls": {
      "type": "number"
    },
    "tokensUsed": {
      "type": "number"
    },
    "skipped": {
      "type": "boolean"
    },
    "reason": {
      "type": "string"
    },
    "roleDispatched": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "terminationReason",
    "toolCalls",
    "tokensUsed"
  ]
}

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.