API v1

Workflow API

Workflow endpoints expose metadata, readiness, and controlled lifecycle actions without returning raw graph secrets. Use readiness before publish or run so API clients get the same guardrails as the builder.

Step 1

List workflows visible to the token workspace.

Step 2

Check readiness before publish, run, webhook, or schedule actions.

Step 3

Use idempotent lifecycle writes for run, publish, pause, and resume.

Endpoints

GET/api/v1/workflows?limit=10

List workflow summaries with active state, node count, timestamps, and links.

Required scope: workflows:read

curl https://www.finkmesh.com/api/v1/workflows?limit=10 \
  -H "Authorization: Bearer $FINKMESH_TOKEN"
{
  "data": [
    {
      "id": "wf_123",
      "name": "Lead routing",
      "active": true,
      "nodeCount": 4
    }
  ],
  "pagination": { "limit": 10, "hasMore": false, "nextCursor": null },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}
GET/api/v1/workflows/{workflowId}

Fetch one curated workflow summary. Secrets and raw node payloads are not returned.

Required scope: workflows:read

curl https://www.finkmesh.com/api/v1/workflows/{workflowId} \
  -H "Authorization: Bearer $FINKMESH_TOKEN"
{
  "data": {
    "id": "wf_123",
    "name": "Lead routing",
    "active": true,
    "errorGuardrail": {
      "threshold": 5,
      "consecutiveErrorCount": 0
    }
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}
POST/api/v1/workflows/{workflowId}/readinessIdempotency-Key

Evaluate persisted or supplied draft workflow readiness for publish, run, webhook, or schedule actions.

Required scope: workflows:read

curl -X POST https://www.finkmesh.com/api/v1/workflows/{workflowId}/readiness \
  -H "Authorization: Bearer $FINKMESH_TOKEN" \
  -H "Idempotency-Key: readiness-$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"action":"api_run"}'
{
  "data": {
    "ok": true,
    "action": "api_run",
    "blockingIssueCount": 0,
    "warningCount": 0,
    "issues": []
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}
GET/api/v1/workflows/{workflowId}/readiness?action=api_run

Evaluate the saved workflow graph without sending a draft graph body.

Required scope: workflows:read

curl https://www.finkmesh.com/api/v1/workflows/{workflowId}/readiness?action=api_run \
  -H "Authorization: Bearer $FINKMESH_TOKEN"
{
  "data": {
    "ok": true,
    "action": "api_run",
    "blockingIssueCount": 0,
    "warningCount": 0
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}
POST/api/v1/workflows/{workflowId}/runIdempotency-Key

Queue an API-triggered workflow run after readiness, plan, quota, and rate-limit checks.

Required scope: workflows:run

curl -X POST https://www.finkmesh.com/api/v1/workflows/{workflowId}/run \
  -H "Authorization: Bearer $FINKMESH_TOKEN" \
  -H "Idempotency-Key: run-$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"triggerData":{"source":"api-smoke"}}'
{
  "data": {
    "runId": "run_123",
    "status": "queued",
    "links": { "run": "/api/v1/runs/run_123" }
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}
POST/api/v1/workflows/{workflowId}/publishIdempotency-Key

Publish a workflow only after readiness and entitlement checks pass.

Required scope: workflows:publish

curl -X POST https://www.finkmesh.com/api/v1/workflows/{workflowId}/publish \
  -H "Authorization: Bearer $FINKMESH_TOKEN" \
  -H "Idempotency-Key: publish-$(uuidgen)"
{
  "data": {
    "workflow": { "id": "wf_123", "active": true },
    "readiness": { "ok": true, "blockingIssueCount": 0 }
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}
POST/api/v1/workflows/{workflowId}/pauseIdempotency-Key

Pause a published workflow without changing its saved graph.

Required scope: workflows:pause

curl -X POST https://www.finkmesh.com/api/v1/workflows/{workflowId}/pause \
  -H "Authorization: Bearer $FINKMESH_TOKEN" \
  -H "Idempotency-Key: pause-$(uuidgen)"
{
  "data": {
    "workflow": { "id": "wf_123", "active": false },
    "readiness": { "ok": true, "blockingIssueCount": 0 }
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}
POST/api/v1/workflows/{workflowId}/resumeIdempotency-Key

Resume a paused or auto-paused workflow after readiness and entitlement checks pass.

Required scope: workflows:resume

curl -X POST https://www.finkmesh.com/api/v1/workflows/{workflowId}/resume \
  -H "Authorization: Bearer $FINKMESH_TOKEN" \
  -H "Idempotency-Key: resume-$(uuidgen)"
{
  "data": {
    "workflow": { "id": "wf_123", "active": true },
    "readiness": { "ok": true, "blockingIssueCount": 0 }
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}

Readiness first

Treat readiness as the preflight contract for publish, run, webhook, and schedule automation.

Lifecycle permissions

Grant workflows:run, workflows:publish, workflows:pause, and workflows:resume separately so tokens can be narrow.

Publish side effects

Publish can synchronize schedule/webhook trigger state after readiness and entitlement gates pass.

Resume side effects

Resume clears auto-pause guardrail state only after the workflow is ready to run again.

Related Docs

Runs APIOpenAPI JSON