Main REST API

The main REST API is the same /api surface used by the Pipelines web app. It is the recommended API surface for new automation because it can read and create library configs, inspect datasets and models, launch workflow runs, and run experiments with temporary config swaps.

Use the main REST API directly when you want raw HTTP access. Use the Python SDK or CLI when you want guided helpers, retries, polling, artifact bundles, and copy-paste workflows.

Recommended Paths

• Python SDK: best for scripts, CI, notebooks, and automation that needs to build payloads programmatically. See Python SDK.
• CLI: best for demos, local smoke tests, and terminal-first workflows. See CLI.
• Raw REST: best when integrating from another language or a backend service that already has HTTP client infrastructure.

API Key Authentication

Pass an organization API key as a bearer token:

curl -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://platform.pipelines.tech/api/prompts

You can also pass the key with X-API-Key:

curl -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://platform.pipelines.tech/api/prompts

API keys are scoped to the organization where they were created. They resolve to the creating user for RBAC checks, so the key can only do what that user and organization can access.

Common REST Endpoints

Library reads:

curl -H "Authorization: Bearer $PIPELINES_API_KEY" \
  "https://platform.pipelines.tech/api/prompts?page_size=10"

curl -H "Authorization: Bearer $PIPELINES_API_KEY" \
  "https://platform.pipelines.tech/api/evaluations?page_size=10"

Workflow discovery:

curl -H "Authorization: Bearer $PIPELINES_API_KEY" \
  "https://platform.pipelines.tech/api/projects/$PROJECT_ID/workflows/$WORKFLOW_ID/creation-mode"

curl -H "Authorization: Bearer $PIPELINES_API_KEY" \
  "https://platform.pipelines.tech/api/projects/$PROJECT_ID/workflows/$WORKFLOW_ID/configurable-fields"

Experiment launch:

curl -X POST \
  -H "Authorization: Bearer $PIPELINES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-experiment-$(date +%s)" \
  "https://platform.pipelines.tech/api/projects/$PROJECT_ID/workflows/$WORKFLOW_ID/experiments" \
  --data @experiment.json

Config Swaps

configOverrides let a run use a different prompt, model, or evaluation without mutating the saved workflow.

{
  "count": 1,
  "variants": [
    {
      "name": "baseline-copy",
      "configOverrides": {}
    },
    {
      "name": "prompt-and-eval-swap",
      "configOverrides": {
        "prompts": [
          {
            "nodeId": "node-id-from-configurable-fields",
            "fieldId": "field-id-from-configurable-fields",
            "promptId": 12,
            "version": 1
          }
        ],
        "models": [
          {
            "nodeId": "node-id-from-configurable-fields",
            "modelSlug": "gemini-3.5-flash"
          }
        ],
        "evaluations": [
          {
            "nodeId": "review-node-id",
            "fieldId": "quality-field-id",
            "evaluationId": 9,
            "version": 1
          }
        ]
      }
    }
  ]
}

For experiments, each variant creates an isolated copied workflow, applies that variant's config, and creates tasks inside the copied workflow. The source workflow is not mutated.

External API v1 Is Deprecated

External API v1 at /api/v1 is deprecated and retained for compatibility only. It is no longer the recommended integration surface.

Use the main REST API, Python SDK, or CLI for new integrations because they support the product library, config swaps, artifacts, experiment workflow copies, cancellation, polling, and richer troubleshooting.

External API v1 remains mounted for now so existing callers do not break in this PR. Responses from the v1 app include Deprecation: true and a successor link to this page.

Error Guide

• 401 Unauthorized: the API key is missing, malformed, revoked, expired, or not valid for production Pipelines. Check PIPELINES_API_KEY.
• 403 Forbidden: the key is valid, but the creating user or org does not have access to that project, model, or evaluation. Use prompt-only swaps if model/evaluation access is restricted.
• 409 Conflict: the same Idempotency-Key was reused with a different request body. Use a new key or retry with the exact same payload.
• 422 Validation Error: the JSON shape does not match the API schema. Check required fields, nodeId, fieldId, and nested configOverrides.
• 429 Too Many Requests: the key hit a rate limit. Wait for Retry-After, then retry.
• Stuck processing: the API accepted the job, but the run is still queued or model/tool execution is slow. Poll status and allow more time.