Skip to main content

Protocols

Protocols define repeatable operational workflows in Assimetria OS. Each protocol consists of ordered steps, supports versioning with draft/publish lifecycle, and tracks execution history.

Listing protocols​

curl https://api.orkosi.com/api/protocols \
  -H "Authorization: Bearer TOKEN"

Response:

{
  "data": [
    {
      "id": 1,
      "name": "Deploy to Production",
      "description": "Standard production deployment workflow",
      "status": "published",
      "version": 3,
      "steps_count": 8,
      "created_at": "2026-03-01T10:00:00Z",
      "updated_at": "2026-04-12T14:30:00Z"
    }
  ],
  "meta": { "total": 12, "limit": 50, "offset": 0 }
}

Getting a protocol​

curl https://api.orkosi.com/api/protocols/1 \
  -H "Authorization: Bearer TOKEN"

Creating a protocol​

Requires admin role.

curl -X POST https://api.orkosi.com/api/protocols \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Incident Response",
    "description": "Steps to follow during a production incident"
  }'

Updating a protocol​

curl -X PATCH https://api.orkosi.com/api/protocols/1 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated deployment workflow"}'

Deleting a protocol​

curl -X DELETE https://api.orkosi.com/api/protocols/1 \
  -H "Authorization: Bearer TOKEN"

Versioning​

Protocols support a draft/publish lifecycle. Changes to a published protocol create a new draft version that must be explicitly published.

Publish a version​

curl -X POST https://api.orkosi.com/api/protocols/1/publish \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"changelog": "Added rollback verification step"}'

Create a draft​

curl -X POST https://api.orkosi.com/api/protocols/1/draft \
  -H "Authorization: Bearer TOKEN"

Rollback to a previous version​

curl -X POST https://api.orkosi.com/api/protocols/1/rollback \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_version": 2}'

View version history​

curl https://api.orkosi.com/api/protocols/1/versions \
  -H "Authorization: Bearer TOKEN"

Diff between versions​

curl "https://api.orkosi.com/api/protocols/1/versions/diff?from=1&to=3" \
  -H "Authorization: Bearer TOKEN"

Steps​

Each protocol contains ordered steps that define the workflow.

List steps​

curl https://api.orkosi.com/api/protocols/1/steps \
  -H "Authorization: Bearer TOKEN"

Add a step​

curl -X POST https://api.orkosi.com/api/protocols/1/steps \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Run smoke tests",
    "description": "Execute the post-deploy smoke test suite",
    "order": 5
  }'

Update a step​

curl -X PATCH https://api.orkosi.com/api/protocols/1/steps/3 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Run smoke tests (v2)"}'

Delete a step​

curl -X DELETE https://api.orkosi.com/api/protocols/1/steps/3 \
  -H "Authorization: Bearer TOKEN"

Reorder steps​

curl -X PUT https://api.orkosi.com/api/protocols/1/steps/reorder \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"step_ids": [3, 1, 2, 5, 4]}'

Executions​

Track protocol execution instances with step-level progress.

Start an execution​

curl -X POST https://api.orkosi.com/api/protocols/1/executions \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"triggered_by": "felix"}'

Update execution status​

curl -X PATCH https://api.orkosi.com/api/protocols/1/executions/42 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "completed"}'

Cancel an execution​

curl -X POST https://api.orkosi.com/api/protocols/1/executions/42/cancel \
  -H "Authorization: Bearer TOKEN"

Execution history​

curl https://api.orkosi.com/api/protocols/executions/history \
  -H "Authorization: Bearer TOKEN"

Audit trail​

curl https://api.orkosi.com/api/protocols/1/executions/42/audit-trail \
  -H "Authorization: Bearer TOKEN"

Attach related resources (tasks, products, knowledge base articles) to a protocol.

curl https://api.orkosi.com/api/protocols/1/context \
  -H "Authorization: Bearer TOKEN"
curl -X POST https://api.orkosi.com/api/protocols/1/context \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "task", "target_id": 53440}'
curl -X DELETE https://api.orkosi.com/api/protocols/1/context/7 \
  -H "Authorization: Bearer TOKEN"

Endpoints summary​

MethodPathAuthDescription
GET/protocolsYesList protocols
GET/protocols/:idYesGet protocol details
POST/protocolsAdminCreate a protocol
PATCH/protocols/:idAdminUpdate a protocol
DELETE/protocols/:idAdminDelete a protocol
GET/protocols/:id/versionsYesVersion history
GET/protocols/:id/versions/diffYesDiff between versions
GET/protocols/:id/versions/:vYesGet specific version
POST/protocols/:id/publishAdminPublish current draft
POST/protocols/:id/draftAdminCreate new draft
POST/protocols/:id/rollbackAdminRollback to a version
GET/protocols/:id/stepsYesList steps
POST/protocols/:id/stepsAdminAdd a step
PATCH/protocols/:id/steps/:sidAdminUpdate a step
DELETE/protocols/:id/steps/:sidAdminRemove a step
PUT/protocols/:id/steps/reorderAdminReorder steps
GET/protocols/executions/historyYesExecution history
GET/protocols/:id/executionsYesExecutions for a protocol
POST/protocols/:id/executionsYesStart an execution
PATCH/protocols/:id/executions/:eidAdminUpdate execution
POST/protocols/:id/executions/:eid/cancelAdminCancel execution
GET/protocols/:id/executions/:eid/audit-trailYesAudit trail
GET/protocols/:id/executions/:eid/stepsYesExecution step details
GET/protocols/:id/contextYesList context links
POST/protocols/:id/contextAdminAdd context link
DELETE/protocols/:id/context/:lidAdminRemove context link
GET/protocols/executions/tenantYesTenant-scoped executions
GET/protocols/:id/analyticsYesProtocol analytics
GET/protocols/analytics/overviewYesAnalytics overview