Developers

API v1

FinkMesh API v1 is a token-authenticated, workspace-scoped REST API. Responses use stable envelopes, request IDs, version headers, cursor pagination, rate-limit headers, metadata-only audit logs, and idempotency support for write requests.

Authentication

Send Authorization: Bearer fmsh_live_....

Public Writes

Every public write requires a unique Idempotency-Key.

Versioning

Responses include apiVersion and FinkMesh-API-Version.

Resource Guides

Workflow API

Readiness, run, publish, pause, and resume.

Runs API

Run history, redacted errors, and execution detail.

Connections API

Connection metadata and health without secrets.

Support Ticket API

Ticket creation, messages, and screenshot limits.

Webhook Endpoint API

Outbound webhook endpoints, deliveries, tests, and retries.

Account

GET /api/v1/meGET /api/v1/orgGET /api/v1/usageGET /api/v1/limits

Workspaces

GET /api/v1/workspacesGET /api/v1/workspaces/{workspaceId}

Workflows

GET /api/v1/workflowsGET /api/v1/workflows/{workflowId}GET /api/v1/workflows/{workflowId}/readinessPOST /api/v1/workflows/{workflowId}/readinessPOST /api/v1/workflows/{workflowId}/runPOST /api/v1/workflows/{workflowId}/publishPOST /api/v1/workflows/{workflowId}/pausePOST /api/v1/workflows/{workflowId}/resume

Runs

GET /api/v1/runsGET /api/v1/runs/{runId}

Connections

GET /api/v1/connectionsGET /api/v1/connections/{connectionId}

Webhooks

GET /api/v1/webhook-endpointsPOST /api/v1/webhook-endpointsGET /api/v1/webhook-endpoints/{endpointId}PATCH /api/v1/webhook-endpoints/{endpointId}DELETE /api/v1/webhook-endpoints/{endpointId}POST /api/v1/webhook-endpoints/{endpointId}/testPOST /api/v1/webhook-endpoints/{endpointId}/rotate-secretGET /api/v1/webhook-endpoints/{endpointId}/deliveriesGET /api/v1/webhook-deliveries/{deliveryId}POST /api/v1/webhook-deliveries/{deliveryId}/retry

Support

GET /api/v1/support/ticketsPOST /api/v1/support/ticketsGET /api/v1/support/tickets/{ticketId}POST /api/v1/support/tickets/{ticketId}/messages

MCP

GET /api/mcpPOST /api/mcp

Endpoint Examples

Inspect Token Context

GET/api/v1/me

Required scope: workspace:read

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

{
  "data": {
    "token": { "id": "tok_...", "scopes": ["workspace:read"] },
    "workspace": { "id": "wsp_...", "name": "Launch Smoke" }
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}

List Workflows

GET/api/v1/workflows?limit=10

Required scope: workflows:read

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

{
  "data": [
    { "id": "wf_...", "name": "Launch Smoke", "active": true }
  ],
  "pagination": { "limit": 10, "hasMore": false, "nextCursor": null },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}

Check Readiness

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

Required scope: workflows:read

curl -X POST https://www.finkmesh.com/api/v1/workflows/wf_123/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
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}

Trigger A Run

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

Required scope: workflows:run

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":"api"}}'

{
  "data": {
    "runId": "run_...",
    "status": "queued",
    "links": { "run": "/api/v1/runs/run_..." }
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}

Create Support Ticket

POST/api/v1/support/tickets

Required scope: support:write

curl -X POST https://www.finkmesh.com/api/v1/support/tickets \
  -H "Authorization: Bearer $FINKMESH_TOKEN" \
  -H "Idempotency-Key: ticket-$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"title":"API question","description":"Need help with readiness."}'

{
  "data": {
    "id": "tkt_...",
    "status": "open",
    "title": "API question"
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}