Skip to content

SOPFlow API Reference

Programmatic access to your org chart, SOPs, and team data.

Base URL

https://sopflow.io/api/v1

All endpoints use HTTPS. Requests over HTTP are rejected.

Versioning

The API is URL-versioned. The current version is v1. When breaking changes are required, a new version path (/api/v2) will be introduced with advance notice. v1 will continue to be supported for at least 12 months after a new version launches.

Authentication

Every request must include an API key in the Authorization header:

Authorization: Bearer sk_live_YOUR_KEY

API keys are created in Settings → API Keys. See the Authentication page for full details and code samples.

HTTP conventions

  • All responses are JSON. The Content-Type is always application/json.
  • Success shape: { data: ... } for single objects; { data: [...], nextCursor: string | null } for lists.
  • Error shape: { error, code, details?, requestId }. See the Errors & Limits page.
  • Methods: GET for reads, POST / PATCH / DELETE for writes (require write scope).
  • OpenAPI spec: machine-readable definition at /api/v1/openapi.json (3.1, requires a valid key).
  • Request IDs: every response carries an X-Request-Id header — quote it when reporting issues.
  • Idempotency: POSTs accept an Idempotency-Key header to make retries replay-safe for 24h.
  • Pagination: List endpoints accept ?limit= (default 100, max 500) and ?cursor= (ISO 8601 timestamp from the previous page's nextCursor).
  • Tenant isolation: All queries are scoped to the organization that owns the API key. You cannot read or mutate data from other workspaces.

Resources

Organization

Org name, slug, plan, and status.

Nodes

Org chart nodes — list, read, create, update, move, delete.

SOPs

SOPs, versions, phases, steps, and state transitions.

Users

Team members — list and update role / status / anchor.

Process Flows

Cross-functional diagrams with nodes and edges.

First integration: read workspace context

Create a read-scoped service key in an eligible workspace and keep it on your server. Read the organization first, confirm it is the intended workspace, then request one page of SOPs. Follow nextCursor when you need the complete collection.

The example below does not create or change content. Handle a rejected request before attempting another resource; do not treat an access error as an empty workspace.

// Server-side JavaScript. Store the real key in your secret manager.
const key = process.env.SOPFLOW_API_KEY;
const expectedWorkspaceId = process.env.SOPFLOW_WORKSPACE_ID;
if (!key || !expectedWorkspaceId) throw new Error("Configure SOPFLOW_API_KEY and SOPFLOW_WORKSPACE_ID");
async function read(path) {
  const response = await fetch("https://sopflow.io/api/v1" + path, {
    headers: { Authorization: "Bearer " + key },
  });
  if (!response.ok) throw new Error("Request failed: " + response.status);
  return response.json();
}
const workspace = await read("/organization");
if (workspace.data.id !== expectedWorkspaceId) throw new Error("Unexpected workspace");
const page = await read("/sops");
const first = page.data[0];
if (first) {
  const procedure = await read("/sops/" + encodeURIComponent(first.id));
  console.log({ hasActiveVersion: !!procedure.data.activeVersion });
}
// Use page.nextCursor with the documented cursor parameter for more pages.