Imported from Nebulit-GmbH/Eventmodelers-Build-Kits (eventmodelers-cli/shared/skills/learn-eventmodelers-api/SKILL.md). Install upstream with npx skills add Nebulit-GmbH/Eventmodelers-Build-Kits --skill learn-eventmodelers-api. Copyright stays with the author.

Eventmodelers Platform API Reference

You now have complete knowledge of the eventmodelers platform API. This is a reference for how a skill talks to the platform once you're already executing one — it is not a license to call the API directly instead of invoking the skill that matches the user's intent (see the Skill Selection table in CLAUDE.md). If a prompt matches a row in that table, invoke that skill first and let it decide which endpoint/tool to call; only reach for this reference directly when no skill matches the intent at all, or when you're implementing/debugging a skill itself.

Load this once per session, on demand — not as a mandatory preamble. Every other skill already documents the exact API calls it needs inline; none of them require this full reference to be loaded before they can run. Reach for this skill only when you hit a specific endpoint, field, or element type that a skill's own instructions don't cover, and don't reload it again later in the same session once you have.

Two transports exist for board operations: MCP tools (preferred) and raw REST/curl (fallback). The connect skill registers the MCP server in .mcp.json. Once mcp__eventmodelers__* tools are visible in your tool list, use them — they need no x-token/x-board-id/x-user-id headers (auth and org resolution happen server-side from the registered token) and return the same data as the REST endpoints below. Fall back to the numbered REST sections only when MCP tools aren't connected yet, or for the handful of endpoints (prompts lifecycle, snapshots, user management, board/extension CRUD) the MCP server intentionally doesn't expose — it only covers board-content operations (nodes, timelines, slices, comments, screens). This preference is about which transport a skill's own instructions should use, never about whether to invoke the skill in the first place.

MCP Tool Catalog (Preferred)

Server name: eventmodelers. Every tool takes boardId explicitly; none need orgId (resolved from the token) or x-user-id (the server attributes writes to the authenticated principal). REST section numbers below give the underlying implementation for tools that wrap a single endpoint 1:1.

Not exposed via MCP at all — always use REST/curl for these: §7 Config Import, §10 Snapshots, §11–12 Invitations, §13 Utility (/api/user, swagger), and the rest of §14 Prompts (submission, claiming, deletion, realtime-token) — only the status-update endpoint has an MCP tool (update_prompt_status, used by the update-prompt-status skill); everything else in Prompts is an intentionally separate lifecycle the board-content MCP server doesn't otherwise own.

Capabilities with no direct MCP filter — e.g. REST's GET .../nodes?cellId=<id>&timelineId=<id> and ?colId=<id>&timelineId=<id> (§3) have no equivalent params on get_nodes. Either call the REST endpoint directly, or get the same answer by calling get_node on the CHAPTER and reading meta.timelineData.cells (sparse array; a cell absent from it is empty) instead of asking the server to filter by cell/column.

Architecture Overview

• Framework: Express.js + @event-driven-io/emmett (event sourcing)
• Adapter: @event-driven-io/emmett-expressjs
• Database: PostgreSQL via Knex
• Storage / Auth: Supabase
• Route discovery: Dynamic glob (**/routes{,-*}.js) loaded from dist/src/slices
• Base URL (local): http://localhost:3000

Authentication & Headers

• CORS allowed origins: localhost:3000, localhost:3001, https://app.eventmodelers.ai

Element Types

MODEL_CONTEXT  // Context/domain modeling container
CHAPTER        // Timeline/sequence container — a "chapter" IS a timeline (chapterId === timelineId); the terms are used interchangeably across the API
ACTOR          // System participant (swimlane label)
AUTOMATION     // Automated action
API            // External service
SCREEN         // UI screen
COMMAND        // State-changing operation
EVENT          // Domain event
SPEC_ERROR     // Error scenario
TABLE          // Data table
READMODEL      // Query result / materialized view
SCENARIO       // GWT scenario
LANE           // Timeline row
SLICE_BORDER   // Slice boundary marker
MARKDOWN       // Free-text markdown note — the content type a `feedback` lane accepts (see §2)
VIDEO          // Embedded video (YouTube/Loom link in `data.url`). API/MCP-only — no palette button in
               // the UI, but renders on the board like any other node. Free-floating: create it via
               // `submit_node_events` with a position and no chapterId/cellId, same as a drawing.

Field Types

Every field on a COMMAND, EVENT, READMODEL, SCREEN, or TABLE element (meta.fields[]) has a type from this exact set — the canonical source is the event-modeling-spec schema ($defs.Field.properties.type):

String     // text
Boolean    // true / false
Int        // 32-bit integer
Long       // 64-bit integer
Double     // floating-point number
Decimal    // precise fixed-point number — prefer this over Double for money/currency
Date       // calendar date only, no time component (e.g. "2026-06-01")
DateTime   // date + time, ISO 8601 (e.g. "2026-06-01T09:00:00Z")
UUID       // universally unique identifier
Custom     // structured/nested value — use with `subfields` or `schema`

Other Field properties: name, example, subfields[] (nested Fields), mapping, optional, technicalAttribute, generated, idAttribute, pii, schema, cardinality ("List" | "Single").

Use exactly these type names (case-sensitive) — not lowercase (string), synonyms (Number, Text, Integer), or types outside this set.

Standard HTTP Status Codes

1. Boards

File: src/slices/change/api-boards/routes.ts

POST /api/org/:orgId/boards/:boardId/events

Persist board/timeline row events as an array of mixed event types.

Request body: Array of node, comment, edge, or board events
Response: 200 — processed results array

GET /api/boards

List all boards.

Response: 200 — Board[]

DELETE /api/org/:orgId/boards/:boardId

Delete a board.

Response: 204

GET /api/org/:orgId/boards/:boardId/events/search

Search events by node name.

Query params: name (string)
Response: 200 — matching event array

GET /api/org/:orgId/boards/:boardId/events

Get all board events in sequence.

Response: 200 — event array

GET /api/org/:orgId/boards/:boardId/nodes/:nodeId/comments

Get all comments for a node.

Response: 200 — comment array

POST /api/org/:orgId/boards/:boardId/bucket

Create a Supabase storage bucket for the board.

Response: 200 — { ok: boolean, bucket: string, alreadyExisted: boolean }

2. Chapters & Timelines

File: src/slices/change/api-chapters/routes.ts

A "chapter" is a timeline — the same entity, referenced as chapterId in node/placement payloads and as :timelineId in the column/lane/cell routes below.

POST /api/org/:orgId/boards/:boardId/chapters

Create a chapter node.

Request body: { position?: { x: number, y: number } }
Response: 200 — chapter data

Omitting position auto-stacks the new chapter below the lowest existing chapter on the board, using each existing chapter's actual current row-height total (not the height it was created with) plus a fixed margin — so a chapter that grew via add_lane/add_column after another was stacked below it won't get overlapped by yet another auto-stacked chapter.

GET /api/org/:orgId/boards/:boardId/chapters/bounds

Get the absolute canvas bounding box of every chapter on the board — the same real-current-size derivation create_chapter's auto-stacking uses internally, exposed for callers who want to compute a placement themselves (e.g. an explicit x/y, or a position relative to a specific chapter rather than "below everything").

Response: 200 — { chapters: Array<{ id: string, title?: string, x: number, y: number, width: number, height: number }> }

POST /api/org/:orgId/boards/:boardId/timelines/:timelineId/columns

Add a column to a timeline.

Request body: { index?: number } (integer index, optional)
Response: 200 — { columnId: string, index: number, totalColumns: number }

DELETE /api/org/:orgId/boards/:boardId/timelines/:timelineId/columns/:columnId

Delete a column from a timeline. Removes the column and all its cells. Cannot delete the last column.

Response:

• 200 — { columnId: string, totalColumns: number }
• 400 — validation error (e.g. last column)
• 404 — timeline or column not found

POST /api/org/:orgId/boards/:boardId/timelines/:timelineId/lanes

Add a lane (row) to a timeline.

Request body:

{
  type: 'actor' | 'interaction' | 'swimlane' | 'spec' | 'feedback'
  label?: string
  index?: number
  height?: number
}

Response: 200 — lane data

POST /api/org/:orgId/boards/:boardId/timelines/:timelineId/cells/:cellId/drop

Drop a node into a timeline cell. Validates placement rules. If the node was already placed in another cell on this timeline, that cell is automatically cleared as part of the same operation — a node can only ever occupy one cell.

Request body: { nodeId: string, nodeType: ElementType }

Placement rules:

• swimlane lane → accepts EVENT
• interaction lane → accepts COMMAND, READMODEL
• actor lane → accepts SCREEN, AUTOMATION
• feedback lane → accepts markdown
• spec lane → accepts SPEC_NODE

Response:

• 200 — drop result
• 400 — placement violation
• 404 — cell or node not found

Feedback lanes and MARKDOWN nodes (free-text notes)

A chapter has no feedback lane by default — add one first via the lanes endpoint above ({"type": "feedback", "label": "Notes"}), which returns a laneId. This is a normal row in meta.timelineData.rows (type: "feedback") alongside actor/interaction/swimlane/spec.

Place a free-text markdown note in that lane the same way any other node is placed — a plain node:created event through POST .../nodes/events (§3), not the cell-drop endpoint above. cellId is "<feedbackRowId>-<columnId>", same convention as every other lane:

{
  "id": "<event-uuid>",
  "eventType": "node:created",
  "nodeId": "<node-uuid>",
  "boardId": "<boardId>",
  "timestamp": 1234567890,
  "chapterId": "<chapterId>",
  "cellId": "<feedbackRowId>-<columnId>",
  "meta": {
    "type": "MARKDOWN",
    "title": "Modeling Reasoning — <Chapter Name>",
    "description": "# Heading\n\nFull markdown body here — headings, lists, bold, etc. all render."
  }
}

The node's content lives in meta.description (a plain string of markdown source) — not meta.content; that field is silently accepted and stored but never rendered, producing a visibly empty note. There is no fields[] array on this element type, and no separate render/sketch call is needed (unlike SCREEN/HTML_SCREEN). node.type comes back as "markdown" (lowercase) on read.

3. Nodes

File: src/slices/change/api-nodes/routes.ts

All node endpoints require header: x-user-id

POST /api/org/:orgId/boards/:boardId/nodes/events

Submit node change events.

Any node:created event carrying a chapterId plus cellId/cellName (i.e. placing a node on a timeline) also triggers a best-effort, fire-and-forget auto-connect to type-compatible neighbors — same rules as the auto-connect endpoint below. Failures there never fail this call.

A node:deleted event cascades: if the deleted node is a chapter (timeline), every node placed in one of its cells and any node parented to it (e.g. a SLICE_BORDER spanning one of its columns) is deleted too, along with all their edges.

Request body: NodeChangeEvent[]

interface NodeChangeEvent {
  id: string                    // uuid
  eventType: 'node:created' | 'node:changed' | 'node:deleted'
  nodeId: string
  boardId: string
  timestamp: number             // unix ms
  userId?: string
  hash?: string                 // content hash
  changedAttributes?: string[]  // dot-paths e.g. 'meta.title'
  node?: {
    id: string
    data: {
      backgroundColor?: string
      title?: string
      url?: string
      linkedTo?: string            // rendering mirror only — meta.linkedTo (below) is authoritative
      // ...other node data fields
      // Do NOT set a "type" here — the server derives the node's render type from
      // meta.type automatically. Setting one yourself risks it being read as the
      // render type itself and breaking rendering.
    }
  }
  meta?: {
    type: ElementType
    title?: string
    description?: string
    fields?: Record<string, unknown>
    linkedTo?: string            // origin node id — the authoritative linked-copy pointer
    // ...
  }
  edges?: Array<{
    id: string
    source: string
    target: string
    sourceHandle?: string
    targetHandle?: string
  }>
  chapterId?: string   // for cell placement
  cellName?: string    // spreadsheet-style, always <letter(s)><number> e.g. "B2", "AA10" — pass through as-is, never decompose or interpret it
}

Response: 200 — { hashes: { [eventId: string]: string } }

GET /api/org/:orgId/boards/:boardId/nodes

List all nodes on a board.

Query params:

• type?: ElementType — exact match.
• cellId?: string — return only the node occupying this timeline cell (format <rowId>-<colId>). Requires timelineId. Empty array if the cell is unoccupied.
• colId?: string — return every node occupying this column, across all rows of the timeline (e.g. to check for an existing COMMAND/READMODEL/SCREEN/AUTOMATION before placing one, since the server caps those at one per column even across separate lane rows). Requires timelineId. Combine with type to narrow to one element type.
• timelineId?: string — the CHAPTER node cellId/colId are resolved against. Required together with either of those two; 400 if omitted.

Cell/column occupancy lives only in the CHAPTER node's meta.timelineData.cells, never on the node rows themselves — this endpoint resolves cellId/colId against that timeline internally so callers don't have to fetch and parse the whole chapter node just to check occupancy.

Response: 200 — node record array. 400 — cellId/colId given without timelineId. 404 — timelineId doesn't reference an existing CHAPTER node with grid data.

GET /api/org/:orgId/boards/:boardId/nodes/:nodeId

Get a single node.

Response: 200 — node record OR 404

POST /api/org/:orgId/boards/:boardId/nodes/:nodeId/auto-connect

Auto-connect a node to its timeline neighbors — mirrors the frontend's auto-connect-on-place behavior. Looks only at the node's own timeline column and the previous column (never ahead), and creates edge:added events to every type-compatible neighbor found there, using the same pairing rules as connections created via node events (COMMAND→EVENT, SCREEN→COMMAND, EVENT→READMODEL, READMODEL→SCREEN, READMODEL→AUTOMATION, AUTOMATION→COMMAND).

Incompatible or already-connected neighbors are reported in skipped, not an error. Returns an empty result for nodes not placed on any timeline, or not a connectable element type (e.g. SCENARIO/spec nodes are never auto-connected).

A COMMAND is driven by exactly one upstream trigger — one SCREEN or one AUTOMATION, never both. The previous column's SCREEN/AUTOMATION is skipped whenever the COMMAND already has an inbound trigger, whether that's a SCREEN or AUTOMATION sitting in its own column, or a pre-existing inbound edge already in the DB (e.g. from a prior auto-connect run or a manual connection).

Connections (both auto-connect and set_connection) only ever pair nodes on the same timeline — a node in Chapter A can never be wired directly to a node in Chapter B, even when the type pair is otherwise valid (e.g. EVENT→READMODEL). No direct cross-timeline connection is possible.

The supported workaround is a linked copy: place a plain EVENT node into its own swimlane on the consuming timeline, then call link_element (below) to link it to the origin node. Linking means first create, then link. eventmodeling-checking-completeness documents how to recognize a linked copy when reading the board — it's an intentional copy, never a duplicate to clean up.

Response:

• 200 — { connected: [{edgeId, source, target, created}], skipped: [{nodeId, reason}] }
• 404 — node not found

POST /api/org/:orgId/boards/:boardId/connections

Create a single type-checked directed edge between two existing nodes — the REST fallback for set_connection.

Request body: { source: string, target: string } (node ids)

Response: 200/201 — { edgeId, source, target } on success · 400 — the pair is not one of the allowed type combinations · 404 — a node id doesn't exist

EVENT → READMODEL is conditionally exempt from column ordering — an event in a later column can connect to a read model in an earlier column, but only when that read model already feeds an AUTOMATION (i.e. a READMODEL → AUTOMATION edge already exists). Such an accumulator read model is a continuously-listening projection, not a point-in-time action, so it can go on collecting events from anywhere later on its timeline (e.g. a running total feeding a downstream process). A plain display read model with no automation still rejects a backward connection — wire the READMODEL → AUTOMATION edge first if the backward connect is rejected and you expect this exemption to apply. This exemption is deliberate-only via this endpoint — auto-connect never infers a backward EVENT → READMODEL pairing. Every other pair (SCREEN → COMMAND, COMMAND → EVENT, READMODEL → SCREEN, READMODEL → AUTOMATION, AUTOMATION → COMMAND) is always forward-only, no exceptions. If a connection you expect to work gets rejected, retry once before concluding it's blocked — a transient rejection has been observed on an otherwise-valid pair.

POST /api/org/:orgId/boards/:boardId/nodes/:nodeId/link

Link two existing same-type nodes — the REST fallback for link_element. Linking means first create, then link: targetNodeId must already exist. It's replaced with a full copy of :nodeId's meta (not a merge) plus meta.linkedTo. COMMAND/EVENT/READMODEL only; :nodeId must not itself already be a linked copy.

Request body:

{
  targetNodeId: string  // existing same-type node to convert into a linked copy
}

Response: 200 — { nodeId, linkedTo, type } · 400 — missing targetNodeId, type mismatch, self-link, unsupported element type, or the original is itself a linked copy · 404 — the original or targetNodeId doesn't exist

4. Images

File: src/slices/change/api-images/routes.ts

POST /api/org/:orgId/boards/:boardId/images/:imageId

Update a board image.

Request: multipart/form-data — field file (binary)
Response: 204

POST /api/org/:orgId/boards/:boardId/imagesnapshots/:imageId

Update an image snapshot.

Request: multipart/form-data — field file (binary)
Response: 204

POST /api/org/:orgId/boards/:boardId/image-nodes/:nodeId

Create an image node.

Request: multipart/form-data — fields: file, chapterId, cellName
Response: 204

POST /api/org/:orgId/boards/:boardId/images/:imageId/sketch

Render a sketch description to WebP and upload.

Request body:

{
  elements: object[]           // sketch element descriptors
  semanticDescription?: string // human-readable description stored in metadata
}

Response: 204

POST /api/org/:orgId/boards/:boardId/image-nodes/:nodeId/sketch

Create a SCREEN node from a sketch description.

Request body:

{
  chapterId: string
  cellName: string
  description: { elements: object[] }
  semanticDescription?: string
}

Response: 204 OR 400 (validation error)

5. Slices

File: src/slices/change/api-.slices/routes.ts

POST /api/org/:orgId/boards/:boardId/timelines/:timelineId/slices

Create a complete slice (1 column + 3 nodes automatically placed).

Request body:

{
  type: 'state-change' | 'state-view' | 'automation'
  index?: number
  nodes?: {
    actor?: Partial<NodeData> & { rowId?: string }
    interaction?: Partial<NodeData> & { rowId?: string }
    swimlane?: Partial<NodeData> & { rowId?: string }
  }
}

Slice node mapping:

• state-change → HTML_SCREEN (actor) + COMMAND (interaction) + EVENT (swimlane)
• state-view → HTML_SCREEN (actor) + READMODEL (interaction) + EVENT (swimlane)
• automation → AUTOMATION (actor) + COMMAND (interaction) + EVENT (swimlane)

Each chapter has exactly one actor/interaction/swimlane lane by default, but a chapter can have several lanes of the same type (e.g. multiple actor lanes). Without a rowId, the node is always placed in the first lane of the matching type — pass nodes.<actor|interaction|swimlane>.rowId (a row id from the chapter's timelineData.rows) to target a specific lane instead. An invalid rowId (not found, or found but the wrong lane type) is a 400 ROW_NOT_FOUND/ROW_TYPE_MISMATCH error.

The actor HTML_SCREEN is created as a stub — a single visibly-placeholder page ("Untitled screen — design pending") unless nodes.actor.pages is passed explicitly. Whoever calls this (the add-next-slice skill — the one that creates a brand-new slice from scratch, as opposed to eventmodeling-slicing-event-models, which only makes existing elements explicit) is responsible for immediately replacing that stub via the html-screen skill — including gathering the board's existing screens first so the new one matches their established style, since html-screen itself has no visibility into other screens.

Response: 200 — slice data

POST /api/org/:orgId/boards/:boardId/timelines/:timelineId/slice-definitions

Create a standalone SLICE_BORDER node spanning an existing column. Unlike the endpoint above, this does not add a column or any actor/interaction/swimlane content nodes — the column must already exist (e.g. created via POST .../slices or the column API) and is referenced by columnId.

Request body:

{
  columnId: string   // id of an existing column on this timeline
  title: string      // slice title — always taken from this field, never derived
  data?: Record<string, unknown>   // optional node.data payload
  meta?: Record<string, unknown>   // optional extra meta fields (type, colId, title are always set explicitly and cannot be overridden here)
}

Response: 200 — { nodeId, timelineId, columnId, title } Errors: 400 missing columnId/title or column not found · 404 timeline not found

6. Specifications (GWT Scenarios)

File: src/slices/change/api-specs/routes.ts

POST /api/org/:orgId/boards/:boardId/contexts/:contextName/slices/:sliceName/scenarios

Append a Given-When-Then scenario to a spec node.

Request body:

{
  id: string
  title: string
  vertical?: boolean
  examples?: unknown[]
  given: string[]   // nodeIds — must be EVENTs from same timeline
  when: string[]    // nodeIds — at most one COMMAND; empty if then has READMODEL
  then: string[]    // nodeIds — EVENTs only OR exactly one READMODEL (not mixed)
}

Validation rules:

• given: only EVENTs from same timeline
• when: max one COMMAND; must be empty when then contains a READMODEL
• then: all EVENTs OR exactly one READMODEL — never mixed
• All referenced nodes must belong to the same chapter/timeline

Response:

• 201 — { scenario, scenarios, specNodeId, isNewNode: boolean }
• 400 — validation error
• 404 — context or slice not found
• 409 — duplicate scenario title

GET /api/org/:orgId/boards/:boardId/contexts/:contextName/spec-info

Get valid elements for a context (by name lookup).

Response: 200 — { chapterId: string, elements: ElementRecord[] }

GET /api/org/:orgId/boards/:boardId/contexts/:contextName/slices/:sliceName/spec-info

Get valid elements for a specific slice.

Response: 200 — { chapterId: string, elements: ElementRecord[] }

Storylines

Create a storyline whenever eventmodeling-elaborating-scenarios's GWT-vs-storyline decision rule calls for one (e.g. a todo list's open→close lifecycle) — that skill's own per-read-model judgment is the trigger, not a specific word in the user's request. GWT scenarios via add_scenario/POST .../scenarios still cover everything the decision rule doesn't.

An ordered, branchable walkthrough of existing board elements ("beats"), stored alongside GWT scenarios on the same SCENARIO spec node, in a sibling meta.storylines collection.

POST /api/org/:orgId/boards/:boardId/timelines/:timelineId/columns/:columnId/storylines

Append one or more storylines to a column's spec node. The spec node is auto-created if missing (shared with scenarios).

Request body: a single storyline object or an array:

{
  id: string
  title: string          // must be unique within the spec node
  description?: string
  layout?: 'horizontal' | 'vertical'
  beats: Array<{
    instanceId: string   // unique per beat, even when refId repeats
    refId: string        // board node id — must belong to the same timeline
    type?: string
    title?: string
    isError?: boolean    // marks an alternate/error branch off the previous beat
    fields?: unknown[]
    expectEmptyList?: boolean
    exampleMode?: string
    examples?: unknown[]
  }>
}

Response:

• 201 — { specNodeId, storylines, added, isNewNode }
• 400 — validation error
• 404 — timeline, column, or referenced node not found
• 409 — duplicate storyline title

7. Config Import

File: src/slices/change/config-import/routes.ts

POST /api/org/:orgId/boards/:boardId/import-config

Import an EventModelingJson config to populate a board.

Request: multipart/form-data with field file OR application/json body:

{ slices: SliceDefinition[] }

Response: 200 — transformed canvas with nodes and edges

8. Slice Data

File: src/slices/slicedata/routes.ts

GET

Build structured slice data from board state.

Query params (one required): contextId OR contextName; optional: sliceId
Response: 200 — slice data matching event modeling schema

GET /api/org/:orgId/boards/:boardId/slicedata/slices

List all slices on a board.

Response: 200 — { slices: Array<{ id: string, title: string, status: string }> }

9. Extensions

File: src/slices/extensions/routes.ts

GET /api/org/:orgId/boards/:boardId/extensions

List extension configs for a board.

Response: 200 — extension record array

PUT /api/org/:orgId/boards/:boardId/extensions/:type

Enable or disable an extension.

Request body: { enabled: boolean, config?: object }
Response: 200 — updated extension config

10. Snapshots

File: src/slices/Snapshots/routes.ts

All snapshot endpoints require Supabase JWT authentication.

Constraints: max 3 snapshots per user, max 30-day retention, max 50 MB file size.

GET /api/snapshots

List current user's snapshots.

Response: 200 — Array<{ id, name, payload_id, expiry, shared }>

POST /api/snapshots

Create a snapshot.

Request: multipart/form-data — fields: payloadFile (binary), name (string), retention? (days, max 30)
Response: 201 — { ok: true, id: string }

GET /api/snapshots/:id

Load a snapshot's payload.

Response: 200 — snapshot payload JSON

PATCH /api/snapshots/:id/share

Share a snapshot (makes it publicly accessible).

Response: 200 — { ok: true }

DELETE /api/snapshots/:id

Delete a snapshot.

Response: 200 — { ok: true }

11. Invitations (Organization Membership) — Commands

Files: src/slices/organization/InviteUser/routes.ts, src/slices/organization/ConfirmInvitation/routes.ts, src/slices/organization/DeleteInvitation/routes.ts

There is no generic "group"/"role-assignment" API — an organization is the group, and a member's role is set once, at invite time (there is no separate call to change an existing member's role afterward). All of these require a Supabase JWT (Authorization: Bearer), never a bot x-token.

POST /api/org/:orga_id/invitations

Invite a user to join an organization with a given role. Caller must already be an admin of orga_id.

Body: { role: string, email: string, description?: string } Response: 201 — invitation created Errors: 400 role/email missing · 403 caller is not an org admin · 409 user already invited or already a member

POST /api/invitations/:token/confirm

Accept an invitation — token is the invitation's own token (from the invite email link), not an API token. The confirming user's own account email must match the invited email.

Response: 200 — invitation confirmed, membership created Errors: 404 invitation not found

DELETE /api/org/:orga_id/invitations/:invitation_id

Cancel a pending invitation.

Response: 200/204 on success

12. Invitations (Organization Membership) — Read Models

All require a Supabase JWT (Authorization: Bearer).

GET /api/user-organizations

Organizations (and the caller's role in each) that the authenticated user belongs to.

GET /api/client/org/:orgId/invitations

Pending invitations for an organization (client-facing list — used by the org settings UI).

13. Utility

GET /api/user

Get current authenticated user info.

Response: { user_id: string, email: string, metadata: object }

GET /api-docs

Swagger UI (interactive API explorer)

GET /swagger.json

OpenAPI specification (JSON)

14. Prompts

File: src/slices/change/api-prompts/routes.ts

Prompts are how a human submits work to a modeling agent from the board UI, and how that agent reports its lifecycle back onto the board. Every prompt row has a status: ADDED (submitted, default) → CLAIMED (an agent has picked it up) → IN_PROGRESS (an agent is actively working it) → DONE (finished). See the update-prompt-status skill for the agent-side half of this lifecycle.

POST /api/org/:orgId/prompts

Submit a prompt for a board timeline. Auth: Supabase JWT (Authorization: Bearer).

Request body:

{
  prompt: string
  board_id: string
  timeline_id: string
  node_id?: string
  comment_id?: string
  priority?: boolean          // default false
  hidden?: boolean            // default false — agent-only task, never returned to a client
  context?: {                 // optional canvas-selection context for the agent to use
    selectedCell?: object | null
    selectedNodes?: string[]  // every element selected when the prompt was sent
    timelineId?: string | null
    focusArea?: {             // what was on screen at submit time — orientation, not a task
      nodes: { id: string, title?: string, type?: string }[]
      truncated: boolean      // more were visible than the list holds (cap: 15)
    }
  }
}

context is stored and handed back verbatim — the backend validates only the shape of selectedCell/selectedNodes/timelineId and passes everything else (focusArea included) through opaquely, so new context fields need no backend change.

focusArea.nodes is ordered by how much each element says about where the user is, not by position alone: chapters first, then the model itself (COMMAND, READMODEL, QUERY, EVENT), then specs (SCENARIO, SPEC_*), then everything else (screens, notes, drawings, slice frames); within one of those tiers, nearest the centre of the view first. Every entry carries its type, so a chapter is told from a command without a second lookup.

hidden: true marks an agent-only task: still claimed by /prompts/next like any other prompt, but excluded from every client read (and from Supabase's prompts_select RLS policy), so it never shows up in the user's prompt list. A canvas poke (Alt+Shift+P) is exactly this — a hidden prompt whose text is the bare word Focus, carrying node_id (when a single element was selected) plus the focusArea, and nothing else.

Response: 201 — the created row, status: "ADDED". Errors: 400 missing required fields or malformed context · 403 no access to board · 404 board/timeline not found or no API token configured for the org

GET /api/org/:orgId/prompts/next

Claim the next pending (ADDED) prompt for a board — atomically flips it to CLAIMED and returns it. This is what a running modeling agent's warm loop polls. Auth: x-token and a Supabase JWT (Authorization: Bearer) together.

Query params: board_id (required) Response: 200 — the claimed row (now status: "CLAIMED"), including its parsed context and the hidden flag · 404 — no ADDED prompts available

POST /api/org/:orgId/prompts/:id/status

Set a prompt's status, optionally attaching a progress comment. Auth: x-token only (bot token — no user JWT needed, this is meant to be called directly by the agent working the prompt).

Prefer MCP: mcp__eventmodelers__update_prompt_status { "promptId": "<id>", "newStatus": "IN_PROGRESS", "comment": "..." } — no orgId/x-token needed, same validation and response shape. Fall back to the curl below only when MCP tools aren't connected.

Request body:

{
  status: 'ADDED' | 'CLAIMED' | 'IN_PROGRESS' | 'DONE'
  comment?: string   // shown alongside the prompt in the board UI
}

Response: 200 — the updated row Errors: 400 invalid/missing status · 403 token not for this prompt's org · 404 prompt not found

DELETE /api/org/:orgId/prompts/:id

Delete a prompt outright. Auth: x-token only. Manual/admin cleanup — not part of the normal agent lifecycle (use the status endpoint above instead).

Response: 204 · 404 prompt not found

DELETE /api/org/:orgId/prompts/:id/user

Delete a prompt you submitted yourself. Auth: Supabase JWT — only deletes rows owned by the calling user.

Response: 204 · 404 prompt not found or not yours

GET /api/org/:orgId/prompts/realtime-token

Exchange an x-token for a short-lived Supabase-compatible JWT, used to subscribe to the org's realtime channel for live prompt notifications. Auth: x-token only.

Response: 200 — { token: string }

POST /api/agent-alive

Record a heartbeat ping for a running modeling/build agent. Auth: Supabase JWT (Authorization: Bearer) — exchange the x-token for one first via GET /api/org/:orgId/prompts/realtime-token above; a raw x-token alone is not accepted here.

Body: { token: string, board_id?: string, agent_type: 'MODELING' | 'BUILD', agent_id: string } Response: 200 — { ok: true } Errors: 400 agent_id/agent_type missing · 404 token not found

GET /api/org/:orgId/boards/:boardId/agent-alive

Check whether an agent has pinged for a board within the last 45s. Auth: x-token (bot) or a Supabase JWT (Authorization: Bearer) — either works.

Response: 200 — { alive: boolean, agentTypes: string[] }

Domain Events

Snapshot Events (src/events/SnapshotsEvents.ts)

SnapshotStored          // { name, id, payloadId, expiry }
SnapshotDeleted         // { id }
SnapshotCleanedUp       // { id }
PublishedSnapshotDeleted // { id }
SnapshotShared          // { id }
SnapshotPublished       // { id, payloadId, bucket, path }

Invitation Events (src/slices/organization/OrganizationEvent.ts)

UserInvited                  // { orgaId, userId, role, invitationId, token, description?, boardId?, email? }
InvitationConfirmed          // { orgaId, userId, invitationId, token?, email? }
InvitationDeleted            // { invitationId }
UserAssignedToOrganization   // { id, userId, orgaId, role?, boardId?, email? }
UserRemovedFromOrganization  // { orgaId, userId }

All events support optional metadata: user_id, correlation_id, causation_id

Key Source Files