Workflows API

A workflow is a graph of Pincel tools you assemble on the canvas: remove a background, drop the product into a generated scene, relight it, upscale it, export. Once it's saved, this API runs that same graph with whatever inputs you pass in.

• https://pincel.app — base URL. All responses are JSON.
• Runs are asynchronous: start a run, then poll it.
• Credits are charged per step, exactly as in the app. The same content-safety checks apply to every step.
• Outputs are temporary — deleted after 7 days. Add a Save to Library node to keep a result permanently.
• Pass an array to a List input and the workflow runs once per row — a whole product catalog in one call.
• Using an AI assistant? Connect it to the MCP server and every saved workflow shows up as a tool it can call.

Three calls: find your workflow, run it, poll for the result.

curl https://pincel.app/api/v1/workflows \
  -H "X-API-Key: $PINCEL_API_KEY"

curl -X POST https://pincel.app/api/v1/workflows/$WORKFLOW_ID/run \
  -H "X-API-Key: $PINCEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{"upload-1":"https://example.com/product.jpg"}}'

curl https://pincel.app/api/v1/runs/$RUN_ID \
  -H "X-API-Key: $PINCEL_API_KEY"

Send your key in the X-API-Key header. It's a UUID — copy it from your account page.

X-API-Key: 3f7a1c92-8e54-4b0d-9a6f-2c1e5d840b7a

A 401 means the key is unknown or was rotated; a zero balance answers 402 instead — see Credit balance. Credits — not a subscription — are what entitle you here.

A workflow's source nodes are its inputs, and you address them by node id. Ask the API what they are rather than guessing:

{
  "id": "7c4f…",
  "name": "Product shot cleanup",
  "estimated_credits_per_run": 7,
  "inputs": [
    {
      "nodeId": "upload-1",
      "type": "image",
      "cardinality": "single",
      "required": true,
      "hasStoredValue": false
    }
  ],
  "steps": [
    { "nodeId": "remove-bg-1", "tool": "remove-bg", "name": "Remove Background" },
    { "nodeId": "upscale-1", "tool": "upscale", "name": "Upscale" }
  ]
}

Image URLs must be publicly reachable over http(s). Private and loopback addresses are rejected.

Add a List node to the workflow on the canvas, then pass an array to it. The whole pipeline runs once per row, rows are independent — one failure doesn't stop the others — and you poll a single batch id.

{
  "inputs": {
    "list-1": [
      "https://example.com/sku-1.jpg",
      "https://example.com/sku-2.jpg",
      "https://example.com/sku-3.jpg"
    ]
  }
}

• Up to 25 rows per call.
• A text List (one prompt per row) works the same way — useful for generating variants of one asset.
• The whole batch is checked against your balance up front, so it won't die halfway with some rows already charged.

https://pincel.app/api/v1/mcp is this API reshaped for agents: every saved workflow is one MCP tool, with an input schema generated from its graph — one property per input node id, arrays for List inputs. Two extra tools, get_run_status and get_batch_status, cover the asynchronous part. Connect an assistant once and it can discover and run your pipelines without composing REST calls.

claude mcp add --transport http pincel https://pincel.app/api/v1/mcp \
  --header "X-API-Key: $PINCEL_API_KEY"

• Auth — the same API key, sent as X-API-Key or Authorization: Bearer for clients that only support bearer tokens.
• Transport — stateless Streamable HTTP: one JSON-RPC message per POST, no sessions, no SSE stream.
• Waiting — a run tool waits up to ~50 seconds and returns the outputs directly; longer runs come back as status: "running" with a run_id to poll via get_run_status.
• Credits & limits — every tool result includes credits_remaining; the rate limits are the same buckets as REST (list → discovery, run → start, status → polling).

Poll every ~2 seconds. There are no delivery webhooks yet.

Every response tells you where your balance stands, so an unattended integration can warn its owner before runs start failing:

• Header X-Credits-Remaining: 4821 — on every request, including errors.
• Field credits_remaining — in every JSON body.

curl -si https://pincel.app/api/v1/runs/$RUN_ID \
  -H "X-API-Key: $PINCEL_API_KEY" | grep -i x-credits-remaining

When the balance reaches zero, requests answer 402 rather than 401, so you can handle it specifically — a 401 then means only that the key is wrong or was rotated.

{
  "error": "Out of credits. Top up at https://pincel.app/billing to keep running workflows.",
  "code": 402,
  "credits_remaining": 0
}

Credits are the real throughput limit — every run spends them. These limits exist to protect shared model capacity, to stop a retry loop from burning credits by accident, and to block key guessing. The same limits apply to every account.

• 60 starts/minute is ≥1,500 rows/minute when batched, so a real catalog job never touches it.
• Runs in flight is the limit that matters most: one request can start 25 runs, so it's checked before a batch begins.
• A 429 carries Retry-After and X-RateLimit-* headers. Back off rather than retrying immediately — the window is a rolling 60 seconds.

A run that can't be afforded in full is rejected up front with a message naming the shortfall, rather than dying halfway with some steps already charged. Content that fails moderation isn't an HTTP error: the step ends with status blocked and isn't charged.