Org Structures

CRUD for workspaces, nodes, and the edges between them.

`GET /api/org/structures`

List workspaces the authenticated user has access to.

Response

200 OK:


{
  "structures": [
    {
      "id": "uuid",
      "name": "Acme Labs",
      "role": "owner",
      "created_at": "2026-03-01T12:00:00Z",
      "node_count": 6
    },
    ...
  ]
}

`GET /api/org/structures/{structure_id}`

Full workspace detail — all nodes and their edges.

Response

200 OK:


{
  "id": "uuid",
  "name": "Acme Labs",
  "agents": [
    {
      "id": "node-uuid",
      "role_id": "executive-office-ceo",
      "label": "CEO",
      "parent_id": null,
      "x": 400,
      "y": 50,
      "state": "idle"
    },
    {
      "id": "node-uuid-2",
      "role_id": "executive-office-cmo",
      "label": "CMO",
      "parent_id": "node-uuid",
      "x": 200,
      "y": 200,
      "state": "working"
    },
    ...
  ]
}

The MCP list_peers() tool uses this to enumerate peers.

`POST /api/org/structures`

Create a new workspace.

Request


{
  "name": "My New Workspace",
  "template": "exec-team"  // or "sales-team", "research-lab", "personal", "blank"
}

Response

201 Created with the new structure record.

`POST /api/org/structures/{structure_id}/agents`

Add a node to a workspace.

Request


{
  "role_id": "executive-office-cmo",
  "label": "CMO",
  "parent_id": "ceo-node-uuid",
  "x": 300,
  "y": 200,
  "starting_context": "You are the CMO of Acme Labs, a B2B SaaS..."
}

Response

201 Created with the node record.

`DELETE /api/org/structures/{structure_id}/agents/{role_id}`

Remove a node. The node’s history, artifacts, and activity timeline are preserved in data/archived/ in case you want to restore.

`POST /api/org/structures/{structure_id}/agents/{role_id}/mcp-key`

Mint a per-node bearer token for Claude Desktop (see MCP setup).

Request


{
  "label": "My MacBook Pro"  // optional, shown in the revocation UI
}

Response

201 Created (returns the plaintext token once):


{
  "id": "key-uuid",
  "token": "of_dkmcp_<random>",
  "prefix": "of_dkmcp_",
  "label": "My MacBook Pro",
  "created_at": "2026-04-20T15:00:00Z"
}

Store the token immediately — the server only keeps the SHA-256 hash.

`DELETE /api/org/structures/{structure_id}/agents/{role_id}/mcp-key/{key_id}`

Revoke a previously-minted MCP key. Revocation is immediate; any open connection from that key starts receiving 401s.

`POST /api/org/structures/{structure_id}/share`

Invite a collaborator by email.

Request


{
  "email": "colleague@acme.com",
  "role": "operator"  // "viewer" | "operator" | "owner"
}

Response

200 OK — the invite email is sent. The invite expires after 14 days.