Developer API - JustFlows

Overview

API v1 gives external services a stable way to operate published workflows and human approvals without using a user session. Workspace boundaries, token abilities, plan limits, and workflow-run limits continue to apply.

Base URL

https://jfl101.qdev.tech/api/v1

Authentication

Workspace Bearer token

Format

JSON requests and responses

Specification

Open API v1 YAML

Authentication

Workspace owners and admins create service tokens from API access in the application. Send the token as a Bearer credential with every request.

Authorization: Bearer wst_v1_<token-id>.<secret>

The full token is shown only once. Store it in a secret manager and never place it in source control, browser code, query strings, or logs. Rotation revokes the previous value immediately.

Site availability control. The site administrator can disable the Workspace API globally. While disabled, existing tokens are retained but cannot authenticate, and service endpoints return HTTP 503 with the error code api_disabled.

Abilities

Grant each application only the operations it needs.

Ability	Allows
`workflows:read`	View published workflows
`runs:create`	Start workflow runs
`runs:read`	View workflow runs
`runs:cancel`	Cancel workflow runs
`approvals:read`	View pending approvals
`approvals:write`	Resolve approvals

Quick start

1. List published workflows

curl "https://jfl101.qdev.tech/api/v1/workflows" \
  -H "Authorization: Bearer $WORKSPACE_API_TOKEN" \
  -H "Accept: application/json"

2. Start a workflow run

curl -X POST "https://jfl101.qdev.tech/api/v1/workflows/wf_01ABC.../runs" \
  -H "Authorization: Bearer $WORKSPACE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "order_id": 1842,
      "customer_email": "customer@example.com"
    }
  }'

A successful start returns HTTP 202. The run may already be finished when synchronous execution is configured, so always inspect its returned status.

Create, cancel, and approval-decision responses contain identifiers and state only. Grant the corresponding read ability and use the GET endpoint when the integration needs workflow output or approval context.

Workflows

Only published workflows are visible and runnable through the API. Draft or paused workflow state is never selected as a fallback.

Method	Path	Ability
`GET`	`/workflows`	`workflows:read`
`GET`	`/workflows/{workflow_id}`	`workflows:read`
`POST`	`/workflows/{workflow_id}/runs`	`runs:create`

Workflow detail responses include the published version and the trigger input schema or example when one is configured.

Runs and idempotency

Run endpoints

Method	Path	Ability
`GET`	`/runs`	`runs:read`
`GET`	`/runs/{run_id}`	`runs:read`
`POST`	`/runs/{run_id}/cancel`	`runs:cancel`

Idempotent starts

Idempotency-Key is optional. When it is omitted, the API starts the run normally using an internal one-time key. This is convenient for simple calls, but repeating the request may start another run.

For integrations that retry requests automatically, generate a unique value in the calling application and reuse it only for the same logical attempt:

Idempotency-Key: order-1842-attempt-1

Retrying the same workflow and payload with that key returns the original run and includes Idempotent-Replayed: true.

The API stores a hash of the key for 24 hours. Reusing it for different data returns HTTP 409. Keys are isolated per token, and a UUID or durable business identifier plus an attempt number works well.

Approvals

Approval lists return pending requests by default. A service token can approve, reject, or request changes within its own workspace when granted the appropriate ability.

Method	Path	Ability
`GET`	`/approvals`	`approvals:read`
`GET`	`/approvals/{approval_id}`	`approvals:read`
`POST`	`/approvals/{approval_id}/decision`	`approvals:write`

curl -X POST "https://jfl101.qdev.tech/api/v1/approvals/apr_01ABC.../decision" \
  -H "Authorization: Bearer $WORKSPACE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "changes_requested",
    "feedback": "Use the approved customer-facing wording."
  }'

decision accepts approved, rejected, or changes_requested. Feedback is required for a change request, and the workflow node must allow that decision.

Pagination

List endpoints use cursor pagination. Set per_page from 1 to 100 and pass meta.next_cursor back as the cursor query parameter.

{
  "data": [],
  "meta": {
    "next_cursor": "eyJpZCI6...",
    "previous_cursor": null,
    "has_more": true
  },
  "request_id": "b89bb14e-..."
}

Errors, request IDs, and limits

Error envelope

Errors use a stable machine-readable code. Every response includes X-Request-Id; clients may supply a safe X-Request-Id value to correlate logs.

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API token does not have the required ability.",
    "details": {
      "required": ["runs:create"]
    }
  },
  "request_id": "b89bb14e-..."
}

Limits and safe output

General requests

60 per minute per token

Run starts

10 per minute per token

JSON request body

Maximum 256 KB

Plan enforcement

Normal workspace and run limits apply

HTTP 429 responses include Retry-After. HTTP 503 with api_disabled means the site administrator has disabled the Workspace API; wait for it to be enabled instead of rotating credentials. Run and approval payloads are redacted before they are returned; authorization headers, credentials, and internal exception metadata are never included in API responses.