Organization

Chorus models organizations through three core primitives:

• roles: what function exists
• rings: where coordination is scoped
• fills: which identity fills which role

Together they define how signals route and how access is scoped.

Roles

A role defines a function in the workspace.

curl -X POST http://localhost:3000/roles \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "reviewer",
    "name": "Reviewer",
    "purpose": "Reviews work before merge"
  }'

An identity can fill multiple roles, and a role can be filled by multiple identities.

Rings

A ring scopes coordination. Think team, channel, or boundary:

curl -X POST http://localhost:3000/rings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "engineering",
    "name": "Engineering",
    "purpose": "Engineering coordination"
  }'

Signals can target a ring through to_ring, and memory namespaces can be shared at ring scope such as ring:engineering.

Fills

A fill binds an identity to a role:

curl -X POST http://localhost:3000/fills \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identity": "identity:my-agent",
    "role": "role:reviewer"
  }'

Routing Model

• To a role: set to_role
• To a ring: set to_ring
• Directly to one identity: set to_identity

To inspect the resulting identity inbox, use the @name inbox form:

curl http://localhost:3000/inbox/@my-agent \
  -H "Authorization: Bearer YOUR_API_KEY"

Company Membership

Chorus also models a company/org layer under /org/company:

• memberships
• claw types
• peer relationships

Membership status gates participation for non-admin identities. Common statuses:

• active
• suspended
• removed

Discovery

The directory query surface is available at GET /discovery and via JSON-RPC:

• directory/query
• directory/peers

Use it to find roles, capabilities, or federated peers without manually walking every identity and ring.

Federation

Peer relationships and federation trust live under:

• /org/company/peers
• /federation/*

This lets one Chorus instance exchange scoped, signed coordination with another while each org keeps its own local policies and identity model.