Crismo REST API

A workspace-scoped HTTP API for your process models: diagrams, value chains, dictionaries, attributes, share links, and milestones. The MCP server and the crismo CLI are built on this API.

API access is an Enterprise feature. Generate an API key from your workspace once it is enabled. See plans.

Authentication

Send your API key as a bearer token. Keys look like crismo_XXXX_... and are scoped to a single workspace. Requests without a valid key return 401.

Base URL https://api.crismo.io (staging uses a separate host).

Authenticated request
curl https://api.crismo.io/diagrams \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"

Conventions

  • All responses are JSON. Collection endpoints return an object with a success flag and the named collection.
  • Diagram edits use a JSON Patch. Read the diagram, then send the changes; the server validates.
  • Unknown routes return 404. IDs in paths are URL-encoded.
Example response
{
  "success": true,
  "dictionaries": [
    { "id": "38dr58KE6HPF", "name": "Locations" }
  ]
}

Authentication

GET/auth/status

Check the current key and workspace.

Request
curl -X GET https://api.crismo.io/auth/status \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"

Diagrams

GET/diagrams

List all diagrams in the workspace.

Request
curl -X GET https://api.crismo.io/diagrams \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
GET/diagrams/{id}

Get a diagram. Returns BPMN XML plus a compact DSL.

Request
curl -X GET https://api.crismo.io/diagrams/id \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
POST/diagrams/create

Create a diagram from a patch definition.

Body: { name, patch, author? }

Request
curl -X POST https://api.crismo.io/diagrams/create \
  -H "Authorization: Bearer crismo_XXXX_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ name, patch, author? }'
POST/diagrams/{id}/patch

Apply a JSON Patch (add/remove/rename/move/reconnect). Server validates.

Body: { patch, author?, message? }

Request
curl -X POST https://api.crismo.io/diagrams/id/patch \
  -H "Authorization: Bearer crismo_XXXX_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ patch, author?, message? }'
DELETE/diagrams/{id}

Delete a diagram.

Request
curl -X DELETE https://api.crismo.io/diagrams/id \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"

Value chains

GET/value-chains

List value chains.

Request
curl -X GET https://api.crismo.io/value-chains \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
GET/value-chains/templates

List available templates.

Request
curl -X GET https://api.crismo.io/value-chains/templates \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
GET/value-chains/{id}

Get a value chain with its segments.

Request
curl -X GET https://api.crismo.io/value-chains/id \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
POST/value-chains

Create a value chain.

Body: { name, description?, type: core|support, template? }

Request
curl -X POST https://api.crismo.io/value-chains \
  -H "Authorization: Bearer crismo_XXXX_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ name, description?, type: core|support, template? }'
PUT/value-chains/{id}

Update name / description / status.

Body: { name?, description?, status? }

Request
curl -X PUT https://api.crismo.io/value-chains/id \
  -H "Authorization: Bearer crismo_XXXX_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ name?, description?, status? }'
DELETE/value-chains/{id}

Delete a value chain and its segments.

Request
curl -X DELETE https://api.crismo.io/value-chains/id \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
POST/value-chains/{id}/duplicate

Duplicate a value chain.

Body: { name? }

Request
curl -X POST https://api.crismo.io/value-chains/id/duplicate \
  -H "Authorization: Bearer crismo_XXXX_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ name? }'
GET/value-chains/{id}/segments

List segments.

Request
curl -X GET https://api.crismo.io/value-chains/id/segments \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
POST/value-chains/{id}/segments

Add a segment.

Body: { name, parent?, color, level: L1..L4 }

Request
curl -X POST https://api.crismo.io/value-chains/id/segments \
  -H "Authorization: Bearer crismo_XXXX_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ name, parent?, color, level: L1..L4 }'
DELETE/value-chains/{id}/segments/{segId}

Delete a segment.

Request
curl -X DELETE https://api.crismo.io/value-chains/id/segments/segId \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
POST/value-chains/{id}/segments/{segId}/link

Link a diagram to a segment.

Body: { diagramId }

Request
curl -X POST https://api.crismo.io/value-chains/id/segments/segId/link \
  -H "Authorization: Bearer crismo_XXXX_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ diagramId }'
DELETE/value-chains/{id}/segments/{segId}/link/{diagramId}

Unlink a diagram from a segment.

Request
curl -X DELETE https://api.crismo.io/value-chains/id/segments/segId/link/diagramId \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"

Dictionaries

GET/dictionaries

List dictionaries.

Request
curl -X GET https://api.crismo.io/dictionaries \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
GET/dictionaries/{id}

Get a dictionary.

Request
curl -X GET https://api.crismo.io/dictionaries/id \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
POST/dictionaries

Create a dictionary.

Body: { name, description? }

Request
curl -X POST https://api.crismo.io/dictionaries \
  -H "Authorization: Bearer crismo_XXXX_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ name, description? }'
DELETE/dictionaries/{id}

Delete a dictionary and its entries.

Request
curl -X DELETE https://api.crismo.io/dictionaries/id \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
GET/dictionaries/{id}/entries

List entries.

Request
curl -X GET https://api.crismo.io/dictionaries/id/entries \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
POST/dictionaries/{id}/entries

Add an entry.

Body: { term, definition?, synonyms? }

Request
curl -X POST https://api.crismo.io/dictionaries/id/entries \
  -H "Authorization: Bearer crismo_XXXX_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ term, definition?, synonyms? }'
DELETE/dictionaries/{id}/entries/{entryId}

Delete an entry.

Request
curl -X DELETE https://api.crismo.io/dictionaries/id/entries/entryId \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
GET/dictionaries/{id}/search?q={prefix}

Search entries by prefix.

Request
curl -X GET https://api.crismo.io/dictionaries/id/search?q=prefix \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
GET/dictionaries/{id}/entries/{entryId}/usages

Where an entry is used across diagrams.

Request
curl -X GET https://api.crismo.io/dictionaries/id/entries/entryId/usages \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
POST/diagrams/{id}/elements/{elementId}/links

Link a diagram element to a dictionary entry.

Body: { dictId, entryId }

Request
curl -X POST https://api.crismo.io/diagrams/id/elements/elementId/links \
  -H "Authorization: Bearer crismo_XXXX_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ dictId, entryId }'
DELETE/diagrams/{id}/elements/{elementId}/links/{entryId}

Unlink an element from an entry.

Request
curl -X DELETE https://api.crismo.io/diagrams/id/elements/elementId/links/entryId \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"

Attributes

GET/attributes

List attribute definitions.

Request
curl -X GET https://api.crismo.io/attributes \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
POST/attributes

Create an attribute definition.

Body: { name, type, scope, valueType, ... }

Request
curl -X POST https://api.crismo.io/attributes \
  -H "Authorization: Bearer crismo_XXXX_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ name, type, scope, valueType, ... }'
DELETE/attributes/{id}

Delete a definition and its values.

Request
curl -X DELETE https://api.crismo.io/attributes/id \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
GET/diagrams/{id}/elements/{elementId}/attributes

Get attribute values on an element.

Request
curl -X GET https://api.crismo.io/diagrams/id/elements/elementId/attributes \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
POST/diagrams/{id}/elements/{elementId}/attributes

Set an attribute value on an element.

Body: { attributeId, value? | dictEntries? }

Request
curl -X POST https://api.crismo.io/diagrams/id/elements/elementId/attributes \
  -H "Authorization: Bearer crismo_XXXX_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ attributeId, value? | dictEntries? }'
DELETE/diagrams/{id}/elements/{elementId}/attributes/{attributeId}

Remove a value from an element.

Request
curl -X DELETE https://api.crismo.io/diagrams/id/elements/elementId/attributes/attributeId \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
GET/dictionaries/{id}/entries/{entryId}/attributes

Get attribute values on a dictionary entry.

Request
curl -X GET https://api.crismo.io/dictionaries/id/entries/entryId/attributes \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
POST/dictionaries/{id}/entries/{entryId}/attributes

Set an attribute value on a dictionary entry.

Body: { attributeId, value? | dictEntries? }

Request
curl -X POST https://api.crismo.io/dictionaries/id/entries/entryId/attributes \
  -H "Authorization: Bearer crismo_XXXX_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ attributeId, value? | dictEntries? }'
DELETE/dictionaries/{id}/entries/{entryId}/attributes/{attributeId}

Remove a value from a dictionary entry.

Request
curl -X DELETE https://api.crismo.io/dictionaries/id/entries/entryId/attributes/attributeId \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"

Sharing

POST/diagrams/{id}/share

Create a share link.

Body: { title?, snapshot, comments, flags, access, anonymousComments }

Request
curl -X POST https://api.crismo.io/diagrams/id/share \
  -H "Authorization: Bearer crismo_XXXX_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ title?, snapshot, comments, flags, access, anonymousComments }'
GET/diagrams/{id}/shares

List share links for a diagram.

Request
curl -X GET https://api.crismo.io/diagrams/id/shares \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
GET/shares/{shareId}

Get share link details.

Request
curl -X GET https://api.crismo.io/shares/shareId \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
POST/shares/{shareId}/deactivate

Deactivate a share link (keeps it, stops access).

Request
curl -X POST https://api.crismo.io/shares/shareId/deactivate \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
DELETE/shares/{shareId}

Delete a share link permanently.

Request
curl -X DELETE https://api.crismo.io/shares/shareId \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"

Milestones

GET/diagrams/{id}/milestones

List milestones (checkpoints).

Request
curl -X GET https://api.crismo.io/diagrams/id/milestones \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
POST/diagrams/{id}/milestones

Create a checkpoint of the current state.

Body: { label?, description? }

Request
curl -X POST https://api.crismo.io/diagrams/id/milestones \
  -H "Authorization: Bearer crismo_XXXX_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ label?, description? }'
GET/diagrams/{id}/milestones/{milestoneId}

Get a milestone (includes BPMN XML).

Request
curl -X GET https://api.crismo.io/diagrams/id/milestones/milestoneId \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
POST/diagrams/{id}/milestones/{milestoneId}/restore

Restore to a milestone (auto-backs up first).

Request
curl -X POST https://api.crismo.io/diagrams/id/milestones/milestoneId/restore \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
GET/diagrams/{id}/milestones/compare?from={a}&to={b}

Compare two milestones.

Request
curl -X GET https://api.crismo.io/diagrams/id/milestones/compare?from=a&to=b \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"
DELETE/diagrams/{id}/milestones/{milestoneId}

Delete a milestone.

Request
curl -X DELETE https://api.crismo.io/diagrams/id/milestones/milestoneId \
  -H "Authorization: Bearer crismo_XXXX_your_api_key"

Diagram JSON Patch

POST /diagrams/create and POST /diagrams/{id}/patch accept a patch object. Read the diagram first, then send only the changes. The server rewires flows and validates the result.

patch
{
  "add": [
    {
      "type": "userTask | serviceTask | exclusiveGateway | subProcess | lane | ...",
      "id": "optional unique id",
      "name": "Display label",
      "x": 0, "y": 0, "width": 100, "height": 80,
      "lane": "Lane name to place element in",
      "after": "elementId to insert after (auto-rewires flows)",
      "attachedTo": "host element id (boundary events)"
    }
  ],
  "remove": ["elementId"],
  "reconnect": [
    { "from": "srcId", "to": "dstId", "label": "gateway branch label",
      "waypoints": [{ "x": 0, "y": 0 }] }
  ],
  "rename": [{ "id": "elementId", "name": "New label" }],
  "move":   [{ "id": "elementId", "x": 0, "y": 0 }]
}