Agents / REST API

Run skill

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.

POST /api/skills/runBackend AI, consent required

Parameters

workspaceIdOptional · 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).
payloadOptional · object: Arbitrary input passed to the skill.
agentRoleOptional · string: Optional: pin which agent role context to use.scout · researcher · icp · strategist · writer · campaign_builder · closer · coach
allowHostedAiOptional · boolean: Must be true when this operation uses Pipeline hosted inference.

Request example

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}'

Full input schema

Input schema

{
  "type": "object",
  "properties": {
    "workspaceId": {
      "type": "string",
      "minLength": 1,
      "description": "Optional workspace ID or slug. Required when this credential can access multiple workspaces and no workspace was configured on the client."
    },
    "skillName": {
      "type": "string",
      "description": "The skill name from frontmatter (e.g. dream-one-hundred, cold-email-write)."
    },
    "payload": {
      "type": "object",
      "additionalProperties": true,
      "description": "Arbitrary input passed to the skill."
    },
    "agentRole": {
      "type": "string",
      "enum": [
        "scout",
        "researcher",
        "icp",
        "strategist",
        "writer",
        "campaign_builder",
        "closer",
        "coach"
      ],
      "description": "Optional: pin which agent role context to use."
    },
    "allowHostedAi": {
      "type": "boolean",
      "description": "Must be true when this operation uses Pipeline hosted inference."
    }
  },
  "required": [
    "skillName"
  ]
}

See this operation inCLI MCP TypeScript SDK