API Reference

Runs

A run is one execution of a workflow over one or more input items. Trigger a run, poll until it's finished, or listen to status change with webhooks.

POST/workflows/:id/runs

Create a run

Starts a new run of the workflow. Returns immediately, the run executes asynchronously, so poll or use webhooks to follow progress.
Path parameters
idrequired
integer
The workflow id to run.
Body
inputs
object
Per-input-node values keyed by node id.

If your workflow has only one image input node, you can simplify it by using default node name: imageInput

Example

{
 "imageInput": {
    "files": [
      { "url": "https://example.com/acb.jpg", "name": "abc.jpg" }
    ]
  }
}
For multiple input nodes workflow
Example

{
 "n-imageInput-1778112046042": {
    "files": [
      { "url": "https://example.com/acb.jpg", "name": "abc.jpg" }
    ]
  }
}
zipUrl
string
Public accessible URL of the zip archive to run.
zipLayout
"preserve" | "flatten"
"preserve" keeps directory structure in the output zip file. "flatten" flattens the directory structure in the output zip file.
default: preserve
webhookUrl
string
HTTPS callback fired once the run reaches a terminal status. See Webhooks for details
Request with mutliple image urls
curl -X POST "https://api.photopipe.com/workflows/123/runs" \
  -H "Authorization: Bearer pp_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "imageInput": {
        "files": [
          { "url": "https://example.com/photos/abc.jpg", "name": "abc.jpg" },
          { "url": "https://example.com/def.jpg", "name": "def.jpg" }
        ]
      }
    },
    "webhookUrl": "https://your-app.example.com/hooks/photopipe-run"
  }'
Request with zip file
curl -X POST "https://api.photopipe.com/workflows/123/runs" \
  -H "Authorization: Bearer pp_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90" \
  -H "Content-Type: application/json" \
  -d '{
    "zipUrl": "https://example.com/photos.zip",
    "zipLayout": "preserve",
    "webhookUrl": "https://your-app.example.com/hooks/photopipe-run"
  }'
Response 200
{
  "id": 9871,
  "name": "Background removal 2026-04-29 14:05",
  "status": "queued",
  "totalItems": 2,
  "completedItems": 0,
  "failedItems": 0,
  "workflowId": 123,
  "workspaceId": 42,
  "trigger": "api",
  "createdAt": "2026-04-29T14:05:00.000Z",
  "updatedAt": "2026-04-29T14:05:00.000Z"
}
GET/workflows/runs/:runId

Get a run

Returns the run with a paginated list of its items. Status transitions: queued -> running -> completed | failed | partial | cancelled.
Path parameters
runIdrequired
integer
The run id returned by Create a run.
Query parameters
page
integer
Item page.
default: 1
pageSize
integer
Items per page.
default: 25
q
string
Filter items by their input file name (case-insensitive substring).
Request
curl "https://api.photopipe.com/workflows/runs/9871" \
  -H "Authorization: Bearer pp_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90"
Response 200
{
  "id": 9871,
  "name": "Background removal 2026-04-29 14:05",
  "status": "completed",
  "totalItems": 2,
  "completedItems": 2,
  "failedItems": 0,
  "workflowId": 123,
  "trigger": "api",
  "outputArchiveUrl": "https://cdn.photopipe.com/expire-30/runs/9871/background-removal-2026-04-29.zip",
  "items": [
    {
      "id": 55001,
      "status": "completed",
      "uploadInputs": {
        "imageInput-1": {
          "key": "uploads/u-7/2026-04-29/abc.jpg",
          "fileName": "abc.jpg",
          "url": "https://cdn.photopipe.com/uploads/u-7/2026-04-29/abc.jpg"
        }
      },
      "outputs": [
        {
          "url": "https://cdn.photopipe.com/expire-30/runs/9871/55001/cutout-abc.png",
          "key": "expire-30/runs/9871/55001/cutout-abc.png",
          "processedNodeChain": ["Image Input", "Remove background"]
        }
      ],
      "startedAt": "2026-04-29T14:05:01.000Z",
      "finishedAt": "2026-04-29T14:05:21.000Z"
    }
  ],
  "itemsTotal": 2,
  "page": 1,
  "pageSize": 25
}
POST/workflows/runs/:runId/cancel

Cancel a run

Marks the run cancelled. In-flight tasks finish then have their results discarded; queued tasks are dropped immediately.
Path parameters
runIdrequired
integer
The run id.
Request
curl -X POST "https://api.photopipe.com/workflows/runs/9871/cancel" \
  -H "Authorization: Bearer pp_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90"
Response 200
{ "ok": true }
GET/workflows/runs

List workspace runs

Workspace-wide reverse-chronological listing across every workflow. Useful for dashboards.
Query parameters
page
integer
1-indexed page number.
default: 1
pageSize
integer
Items per page.
default: 25
Request
curl "https://api.photopipe.com/workflows/runs?page=1&pageSize=25" \
  -H "Authorization: Bearer pp_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90"
Response 200
{
  "items": [
    {
      "id": 9871,
      "name": "Background removal 2026-04-29 14:05",
      "status": "completed",
      "totalItems": 2,
      "completedItems": 2,
      "failedItems": 0,
      "workflowId": 123,
      "trigger": "api",
      "outputArchiveUrl": "https://cdn.photopipe.com/expire-30/runs/9871/background-removal-2026-04-29.zip",
      "createdAt": "2026-04-29T14:05:00.000Z",
      "finishedAt": "2026-04-29T14:05:42.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 25
}
GET/workflows/runs/:runId/items/:itemId

Get a run item

Per-item detail with each node's execution state. Useful when you want to walk the graph and pull intermediate artifacts, not just the terminal outputs.
Path parameters
runIdrequired
integer
The run id.
itemIdrequired
integer
The item id from a Get a run response.
Request
curl "https://api.photopipe.com/workflows/runs/9871/items/55001" \
  -H "Authorization: Bearer pp_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90"
Response 200
{
  "run": { /* same shape as Get a run, no items */ },
  "item": {
    "id": 55001,
    "status": "completed",
    "uploadInputs": { /* ... */ },
    "outputs": [ /* ... */ ],
    "nodeStates": [
      {
        "nodeId": "removeBackground-1",
        "status": "completed",
        "fileKeys": ["expire-30/runs/9871/55001/cutout-abc.png"],
        "fileUrls": ["https://cdn.photopipe.com/..."],
        "startedAt": "2026-04-29T14:05:02.000Z",
        "finishedAt": "2026-04-29T14:05:20.000Z"
      }
    ]
  }
}