SOPs

Standard operating procedures — each with a version history, phases (columns), and steps (cards).

GET/api/v1/sops

Paginated list of SOPs with their active version summary.

Query parameters

Name	Type	Required	Description
limit	integer	optional	Number of results (default 100, max 500).
cursor	ISO 8601	optional	Pagination cursor from nextCursor.
nodeId	uuid	optional	Filter to SOPs owned by this org node.

Example response

Json

{
  "data": [
    {
      "id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "sopNumber": "SOP-001",
      "orgNodeId": "550e8400-e29b-41d4-a716-446655440000",
      "category": "Onboarding",
      "reviewPeriodMonths": 12,
      "createdAt": "2025-03-05T09:00:00.000Z",
      "activeVersionId": "c56a4180-65aa-42ec-a945-5fd21dec0538",
      "activeVersionTitle": "New Employee Onboarding v2",
      "activeVersionStatus": "active",
      "activeVersionMajor": 2,
      "activeVersionMinor": 0,
      "activeVersionEffectiveDate": "2025-04-01"
    }
  ],
  "nextCursor": null
}

GET/api/v1/sops/:id

Full SOP with active version, phases, and steps.

Path parameters

Name	Type	Required	Description
id	uuid	required	SOP ID.

Example response

Json

{
  "data": {
    "id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
    "sopNumber": "SOP-001",
    "orgNodeId": "550e8400-e29b-41d4-a716-446655440000",
    "category": "Onboarding",
    "reviewPeriodMonths": 12,
    "createdAt": "2025-03-05T09:00:00.000Z",
    "activeVersion": {
      "id": "c56a4180-65aa-42ec-a945-5fd21dec0538",
      "versionMajor": 2,
      "versionMinor": 0,
      "status": "active",
      "title": "New Employee Onboarding v2",
      "purpose": "Ensure every new hire has a consistent first-week experience.",
      "scope": "Applies to all full-time employees.",
      "effectiveDate": "2025-04-01",
      "approvedAt": "2025-03-28T14:00:00.000Z",
      "createdAt": "2025-03-20T10:00:00.000Z",
      "phases": [
        {
          "id": "phase-1-id",
          "title": "Day 1",
          "sortOrder": 0,
          "color": "#6366f1",
          "createdAt": "2025-03-20T10:00:00.000Z",
          "steps": [
            {
              "id": "step-1-id",
              "title": "Set up laptop and accounts",
              "description": "IT hands off laptop with standard image. Employee activates SSO.",
              "stepType": "action",
              "assignedRole": "IT",
              "sortOrder": 0,
              "estimatedDuration": "2 hours",
              "createdAt": "2025-03-20T10:00:00.000Z"
            }
          ]
        }
      ]
    }
  }
}

SOP object

Top-level fields

Name	Type	Required	Description
id	uuid	optional	Unique SOP ID.
sopNumber	string	optional	Human-readable identifier, e.g. "SOP-001".
orgNodeId	uuid \| null	optional	The org chart node that owns this SOP.
category	string \| null	optional	Optional category label.
reviewPeriodMonths	integer	optional	How often (months) this SOP should be reviewed.
createdAt	ISO 8601	optional	When the SOP was created.
activeVersion	SopVersion \| null	optional	The currently active version (detail endpoint only).

SopVersion fields

Name	Type	Required	Description
id	uuid	optional	Version ID.
versionMajor	integer	optional	Major version number.
versionMinor	integer	optional	Minor version number.
status	string	optional	draft \| review \| approved \| active \| retired
title	string	optional	Title of this version.
purpose	string \| null	optional	Purpose statement.
scope	string \| null	optional	Scope statement.
effectiveDate	date \| null	optional	When this version became effective.
approvedAt	ISO 8601 \| null	optional	When this version was approved.
phases	Phase[]	optional	Ordered list of phases (only on detail endpoint).

Phase fields

Name	Type	Required	Description
id	uuid	optional	Phase ID.
title	string	optional	Phase title (column label).
sortOrder	integer	optional	Position among phases.
color	string \| null	optional	Hex color for this phase column.
steps	Step[]	optional	Ordered list of steps in this phase.

Step fields

Name	Type	Required	Description
id	uuid	optional	Step ID.
title	string	optional	Step title.
description	string \| null	optional	Markdown description.
stepType	string	optional	action \| decision \| approval \| subprocess \| reference
assignedRole	string \| null	optional	Role responsible for this step.
sortOrder	integer	optional	Position within the phase.
estimatedDuration	string \| null	optional	Human-readable duration estimate.

Code samples

# All SOPs in the org
curl "https://sopflow.io/api/v1/sops" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

# SOPs for a specific org node
curl "https://sopflow.io/api/v1/sops?nodeId=NODE_ID" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

# Full SOP detail (with phases + steps)
curl "https://sopflow.io/api/v1/sops/SOP_ID" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Mutating SOPs

Mutations require the write scope. Creating an SOP also creates an initial draft version; phases and steps live on a version, so add them after creation.

POST/api/v1/sops

Create an SOP shell plus an initial draft version owned by ownerNodeId.

Body fields

Name	Type	Required	Description
sopNumber	string	required	1–50 chars; unique per workspace (e.g. SOP-001).
ownerNodeId	uuid \| null	required	Owning org-chart node. Pass null for a catalog-level SOP with no initial assignment.
title	string	required	Title for the initial draft version.
purpose	string \| null	optional	Why this SOP exists.
scope	string \| null	optional	What it covers / doesn't cover.
category	string	optional	Up to 100 chars.
reviewPeriodMonths	integer	optional	1–120, defaults to 12.

Example response

Json

{
  "data": {
    "id": "...",
    "sopNumber": "SOP-005",
    "createdAt": "..."
  }
}

DELETE/api/v1/sops/:id

Discard an eligible SOP and its content. Published or evidence-bearing SOPs have integrity restrictions; deletion creates a recoverable trash record. Returns 204 on success.

Example response

Json

HTTP/1.1 204 No Content

POST/api/v1/sops/:id/versions/:versionId/transition

Move an SOP version through the state machine: draft → in_review → approved → active → retired (with under_revision available off active). Invalid transitions return 422 invalid_transition.

Body fields

Name	Type	Required	Description
toStatus	string	required	draft \| in_review \| approved \| active \| retired \| under_revision
comment	string	optional	Optional reviewer comment, recorded on approval_records.

Example response

Json

{
  "data": {
    "id": "...",
    "status": "active",
    "effectiveDate": "2026-05-03"
  }
}

Phases

POST/api/v1/sops/:id/phases

Add a phase (kanban column) to the SOP's current draft version.

Body fields

Name	Type	Required	Description
sopVersionId	uuid	required	Version this phase belongs to.
title	string	required	—
color	string \| null	optional	Hex code for the column header.
sortOrder	integer	optional	Position among siblings; defaults to last.

Example response

Json

{
  "data": { "id": "...", "title": "Plan", "sortOrder": 0, "color": "#dbeafe" }
}

PATCH/api/v1/phases/:id

Update a phase's title, color, or sort order.

Example response

Json

{ "data": { "id": "...", "title": "Renamed" } }

DELETE/api/v1/phases/:id

Delete a phase and all of its steps.

Example response

Json

HTTP/1.1 204 No Content

Steps

POST/api/v1/phases/:id/steps

Add a step (card) to a phase.

Body fields

Name	Type	Required	Description
phaseId	uuid	required	Phase this step belongs to.
title	string	required	Step title.
description	string \| null	optional	Markdown allowed.
stepType	string	optional	action \| decision \| approval \| subprocess \| reference
assignedRole	string \| null	optional	Role responsible for this step.
estimatedDuration	string \| null	optional	Human-readable estimate.
sortOrder	integer	optional	Position within the phase.

Example response

Json

{
  "data": { "id": "...", "title": "Run pre-deploy checks", "stepType": "action" }
}

PATCH/api/v1/steps/:id

Update any step field. Only the keys you supply are written.

Example response

Json

{ "data": { "id": "...", "title": "Updated step" } }

DELETE/api/v1/steps/:id

Delete a step.

Example response

Json

HTTP/1.1 204 No Content

SOPs

SOP object

Code samples

Mutating SOPs

Phases

Steps

Read a procedure and its current version