Workflows

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.

Workflows, runs, and attempts

These resources keep the reusable definition separate from each execution:

• Published workflow: A validated revision available to authorized API clients. Draft edits do not change an existing run.
• Run: One execution with a pinned revision, input data, settings, child jobs, and results.
• Attempt: The initial execution or a later retry within the same run. New jobs use credits; eligible earlier artifacts can be reused.
• Curation checkpoint: A pause where a person reviews candidates and records a selection before execution continues.

Workflow routes

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.

Find a published workflow

List workflows with GET /api/v1/workflows, then inspect the chosen id with GET /api/v1/workflows/{workflowId}. Lists accept limit from 1 to 100, defaulting to 20, and starting_after from the previous next_cursor.

The detail response includes the published definition and settings. Find its input nodes in definition.nodes; their IDs are the keys required in input_data. Match each node's input type and format.

A draft alone is not available for API execution. Prepare and run it from the workflow editor to publish an executable revision. Publication does not make the workflow publicly accessible.

Validate a draft

Authorized editors can send POST /api/v1/workflows/{workflowId}/validate with a definition object and optional settings. This validates without saving, publishing, running, or charging.

The response separates graph errors, warnings, execution-readiness issues, and definition-limit violations. valid is true only when the graph meets all required checks. An empty graph is not a runnable workflow.

Start and monitor a run

Starting a run requires JSON input keyed by workflow input node ID and an idempotency key. Save the exact request and key before submission and reuse both after an uncertain response.

Set WORKFLOW_ID to the chosen workflow and PROTEINIQ_RUN_KEY to a new UUID. The example assumes a sequence input node named input_1 that accepts FASTA; replace that key with the actual node ID. The 500-credit total limit is illustrative.

curl --fail-with-body --silent --show-error -X POST \
  -H "Authorization: Bearer $PROTEINIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $PROTEINIQ_RUN_KEY" \
  "https://proteiniq.io/api/v1/workflows/$WORKFLOW_ID/runs" \
  -d '{
    "name": "Campaign 1",
    "max_credits": 500,
    "input_data": {
      "input_1": {
        "method": "text",
        "textContent": ">example\nACDEFGHIKLMNPQRSTVWY"
      }
    }
  }'

New runs return HTTP 202; an idempotent replay returns HTTP 200 with the existing run. Save the returned id as RUN_ID.

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $PROTEINIQ_API_KEY" \
  "https://proteiniq.io/api/v1/workflow-runs/$RUN_ID"

Poll with backoff. Stop at COMPLETED, COMPLETED_WITH_ERRORS, FAILED, or CANCELLED. Handle PAUSED separately: inspect the paused node and run error, since waiting alone may not resolve it.

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.

Spending limits

Optional max_credits is a nonnegative integer that caps total spending for the run attempt. It does not reserve the estimate or add credits. Each child job is funded when ready; a run can pause if its limit or workspace balance cannot cover further work.

The run response reports estimated_credits and actual_credits. Review workflow credit usage before raising limits or starting another attempt.

Curate and continue

For a manual review pause, read GET /api/v1/workflow-runs/{runId}/curation. Review the actual candidates, then send POST to the same route with the exact returned candidate_set_digest and the IDs you approve.

The identifiers below are placeholders, not runnable candidate selections:

{
  "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 POST /api/v1/workflow-runs/{runId}/continue. This continues the same attempt. A credit-related pause needs its funding constraint resolved; it is not a request to select candidates.

Read results and earlier attempts

GET /api/v1/workflow-runs/{runId}/results returns node and child-job result metadata, including result_available and relative result_url values. Resolve a job result URL against https://proteiniq.io and authenticate it with the same key. Download scientific files through the job Results API.

Run status and result requests accept attempt_id to inspect an earlier attempt. Use an ID from the run response’s attempts list. Without it, responses describe the current attempt.

Cancel and retry

POST /api/v1/workflow-runs/{runId}/cancel requests cancellation. It stops work that has not launched and returns charged and refunded credit totals. It does not erase completed results or prior attempt history.

Send retries to POST /api/v1/workflow-runs/{runId}/retry with JSON and a new idempotency key for the intended retry attempt. Reuse that key only if repeating that same HTTP request. 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.