Organizations

Organizations are the top-level container for all data. Every project, document, entity, and team member belongs to an organization.

List Organizations

GET /v1/organizations

List all organizations the authenticated user is a member of.

Response

{
  "data": {
    "organizations": [
      {
        "id": "...",
        "name": "My Company",
        "slug": "my-company",
        "member_count": 5,
        "created_at": "2026-01-15T10:00:00Z"
      }
    ]
  }
}

Create Organization

POST /v1/organizations

Request Body

{
  "name": "My Company"
}

Optional fields: slug (a globally-unique, human-readable identifier), plan_tier (free, starter, professional, or enterprise), logo_url, description, website, billing_email, and a settings object. Do not send id, created_at, or updated_at; these are assigned automatically. The creator is automatically assigned the owner role.

Response

Returns 201 Created with the new organization’s identifier. The organization starts active; fetch the full record with GET /v1/organizations/:orgId.

{
  "success": true,
  "data": {
    "id": "..."
  }
}

Response Codes

Get Organization

GET /v1/organizations/:orgId

Returns organization details.

Update Organization

PUT /v1/organizations/:orgId

Request Body

{
  "name": "Updated Company Name"
}

Members

List Members

GET /v1/organizations/:orgId/members

Add or Update a Member

POST /v1/organizations/:orgId/members

Adds a member (or updates an existing member's role) by user ID. Upsert semantics.

Request Body

{
  "user_id": "...",
  "role": "admin",
  "email": "teammate@example.com"
}

email is optional; it is only required when adding a user your organization cannot already see. Available roles: owner, admin, manager, developer, member, viewer, guest. The organization is taken from the path and the authenticated session; do not send org_id, is_active, or joined_at in the body; those are assigned automatically.

Response

Returns 201 Created with the membership identifier. The same status is returned whether a new membership was inserted or an existing member’s role was updated.

{
  "success": true,
  "data": {
    "id": "..."
  }
}

Response Codes

Remove Member

DELETE /v1/organizations/:orgId/members/:userId