Developers

FinkMesh API v1

The platform API, beta outbound webhooks, and API-token MCP server are token-authenticated, workspace-scoped, and guarded by readiness checks, rate limits, audit logs, and required idempotency for public writes.

Authentication

Use Authorization: Bearer fmsh_live_... from Settings > API.

Version

Responses include apiVersion: 2026-07-01 and FinkMesh-API-Version.

Pagination

List endpoints accept limit and cursor and return pagination.nextCursor.

Quickstart

Create a scoped API token in Settings, export it locally, then call the API over HTTPS.

  1. Call /api/v1/me to confirm token context.
  2. List workflows and pick a workflow id.
  3. Check readiness before running or publishing.
  4. Trigger a run with a unique Idempotency-Key.
  5. Poll /api/v1/runs/{runId} for the result.
export FINKMESH_TOKEN="fmsh_live_..."

curl https://www.finkmesh.com/api/v1/me \
  -H "Authorization: Bearer $FINKMESH_TOKEN"

curl https://www.finkmesh.com/api/v1/workflows?limit=10 \
  -H "Authorization: Bearer $FINKMESH_TOKEN"

curl -X POST https://www.finkmesh.com/api/v1/workflows/wf_123/run \
  -H "Authorization: Bearer $FINKMESH_TOKEN" \
  -H "Idempotency-Key: run-$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"triggerData":{"source":"quickstart"}}'

Response Shape

{
  "data": {},
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}
{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Token lacks required scope: workflows:read.",
    "requestId": "req_...",
    "apiVersion": "2026-07-01",
    "details": {
      "requiredScope": "workflows:read"
    }
  }
}

Public Write Contract

Every POST, PATCH, and DELETE under /api/v1 requires Idempotency-Key. This includes draft readiness checks because the request body can be replayed safely and consistently by API clients.

Header
Idempotency-Key
Characters
A-Z, a-z, 0-9, underscore, period, colon, and hyphen
Max length
160 characters
TTL
7 days
Scope
API token + method + path + key
Replay
Same key and same body returns the saved response.
Conflict
Same key with a different body returns IDEMPOTENCY_KEY_CONFLICT.
Storage
Responses under 500 are cached; 5xx responses are not cached.

Endpoints

GET/api/v1/me

Inspect the token, user, workspace, and organization context.

GET/api/v1/org

Inspect the active organization, workspace, and subscription context.

GET/api/v1/usage

Read monthly run usage and plan entitlements.

GET/api/v1/limits

Read limits, feature entitlements, and current usage counters.

GET/api/v1/workspaces

List workspaces visible to the token organization.

GET/api/v1/workflows

List workflow summaries for the token workspace.

GET/api/v1/workflows/{workflowId}

Fetch a curated workflow summary without raw graph secrets.

GET/api/v1/workflows/{workflowId}/readiness

Evaluate persisted workflow readiness for publish/run actions.

POST/api/v1/workflows/{workflowId}/readiness

Evaluate readiness against a supplied draft graph. Requires Idempotency-Key.

POST/api/v1/workflows/{workflowId}/run

Queue a public API-triggered workflow run. Requires Idempotency-Key.

POST/api/v1/workflows/{workflowId}/publish

Publish a workflow after plan and readiness gates pass. Requires Idempotency-Key.

POST/api/v1/workflows/{workflowId}/pause

Pause a published workflow without editing its graph. Requires Idempotency-Key.

POST/api/v1/workflows/{workflowId}/resume

Resume a paused or auto-paused workflow after publish gates pass. Requires Idempotency-Key.

GET/api/v1/runs

List workflow run summaries with status, trigger, timing, and failure metadata.

GET/api/v1/runs/{runId}

Fetch run detail with redacted errors and step metadata.

GET/api/v1/templates

Search verified public templates and private workspace templates.

GET/api/v1/connections

List connection metadata and health without credential secrets.

GET/api/v1/webhook-endpoints

List outbound webhook endpoints.

POST/api/v1/webhook-endpoints

Create an HTTPS outbound webhook endpoint. Requires Idempotency-Key.

POST/api/v1/webhook-endpoints/{endpointId}/test

Queue a test delivery for an endpoint. Requires Idempotency-Key.

GET/api/v1/webhook-endpoints/{endpointId}/deliveries

List delivery attempts for an outbound endpoint.

POST/api/v1/webhook-deliveries/{deliveryId}/retry

Retry a failed or dead delivery. Requires Idempotency-Key.

GET/api/v1/support/tickets

List support tickets for the token workspace.

POST/api/v1/support/tickets

Create a support ticket and optional screenshot attachments.

POST/api/v1/support/tickets/{ticketId}/messages

Add a user reply to an existing support ticket.