Workflows

Workflow routes provide programmatic access to validated scientific pipelines while preserving revision, permission, provenance, and credit controls.

Workflow API routes run the same published pipelines available in the ProteinIQ workspace. Every run is pinned to an immutable revision and groups its scientific jobs, node decisions, results, and retry attempts under one run ID.

Basic concepts

Published workflow

The public API lists workflows you can access that have a valid published revision. Draft changes stay private to the editor and never affect an existing API run.

Workflow run

A run captures the published revision, input data, workflow settings, and estimated credits used to start the pipeline. Child jobs execute asynchronously. Read the run resource to follow node and job status.

Attempt

The first execution is attempt 1. A retry creates another attempt under the same logical run. Compatible completed nodes can reuse verified artifacts, while ProteinIQ charges only for scientific jobs launched by the new attempt.

Curation checkpoint

A workflow can pause for a human selection. The checkpoint resource returns content-addressed candidate IDs, scientific previews, and a candidate-set digest. Record the selection before continuing the run.

Workflow routes

Method	Route	Purpose
`GET`	`/api/v1/workflows`	List accessible published workflows
`GET`	`/api/v1/workflows/{workflowId}`	Read a published graph and settings
`POST`	`/api/v1/workflows/{workflowId}/validate`	Validate a draft graph for an authorized editor
`POST`	`/api/v1/workflows/{workflowId}/runs`	Start a run from the published revision
`GET`	`/api/v1/workflow-runs/{runId}`	Read run, attempt, node, and child-job status
`GET`	`/api/v1/workflow-runs/{runId}/results`	Read result metadata and authorized result links
`GET`	`/api/v1/workflow-runs/{runId}/curation`	Read a paused checkpoint and its candidates
`POST`	`/api/v1/workflow-runs/{runId}/curation`	Record an immutable candidate selection
`POST`	`/api/v1/workflow-runs/{runId}/continue`	Continue a paused run after curation
`POST`	`/api/v1/workflow-runs/{runId}/cancel`	Cancel active work and return credit accounting
`POST`	`/api/v1/workflow-runs/{runId}/retry`	Start a safe retry attempt

Read routes require jobs:read. Mutating routes require jobs:write. Workspace workflow permissions and per-workflow access grants apply in addition to API key scopes.

Workflow resources and runs include project_id. Filter GET /api/v1/workflows with project_id=<id> or use unassigned=true. The two filters cannot be combined.

Validate a draft

Authorized editors can validate a draft without saving, publishing, or running it. Send the canonical definition and optional settings.

JSON

{
  "definition": {
    "nodes": [],
    "edges": [],
    "annotations": [],
    "viewport": { "x": 0, "y": 0, "zoom": 1 }
  },
  "settings": {
    "failureMode": "halt",
    "notifications": {
      "onComplete": true,
      "onFailure": true
    }
  }
}

The response separates graph errors, warnings, execution-readiness issues, and definition-limit violations. valid is true only when the graph is structurally valid, within limits, and runnable with registered workflow tool contracts.

Start and monitor a run

Starting a run requires JSON input keyed by workflow input node ID and an idempotency key. Reuse the same key only when retrying the same HTTP request.

Bash

curl -s -X POST \
  -H "Authorization: Bearer $PROTEINIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: campaign-2026-07-17-001" \
  "https://proteiniq.io/api/v1/workflows/$WORKFLOW_ID/runs" \
  -d '{
    "name": "Campaign 1",
    "project_id": "project_123",
    "input_data": {
      "input_1": {
        "type": "text",
        "text": ">query\nMKT"
      }
    }
  }'

The response uses HTTP 202 while execution continues. Poll /api/v1/workflow-runs/{runId} until the run reaches COMPLETED, COMPLETED_WITH_ERRORS, FAILED, or CANCELLED.

Runs inherit the workflow project by default. Supply project_id to override the destination, or null to leave the new run unassigned. An explicit override requires projects:write.

Curate and continue

Read the curation resource after a run enters PAUSED. Submit the exact candidate_set_digest and the approved candidate IDs.

JSON

{
  "candidate_set_digest": "sha256:...",
  "approved_candidate_ids": ["wca_..."],
  "note": "Retained candidates above the agreed confidence threshold",
  "criteria": {
    "filters": { "confidence": "reviewed" },
    "sort": [{ "field": "metadata.confidence", "direction": "desc" }]
  }
}

Checkpoint policy requires at least one approved candidate. A stale digest, unknown candidate, or conflicting second decision fails without broadening the selection. After the decision is recorded, call the continue route.

Cancel and retry

Cancellation stops work that has not launched and returns charged and refunded credit totals. It does not erase completed results or prior attempt history.

Retry requests require a new idempotency key. Omit node_id with mode: "from_start" to rerun the pipeline, or use mode: "from_failed_node" with the failed node ID. Artifact reuse fails closed when the revision, inputs, node configuration, tool contract, or stored artifact verification no longer matches.