Organizations API

Organizations are company-level entities that own and group workspaces. They provide a higher level of administration for teams that manage multiple workspaces (e.g., production, staging, sandbox environments).

Endpoints

List Organizations

GET /api/v1/organizations

Returns all organizations the authenticated user is a member of. Does not require the X-Workspace-ID header.

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "avatar_url": "",
    "settings": {},
    "created_by": "660e8400-e29b-41d4-a716-446655440000",
    "workspace_count": 3,
    "member_count": 15,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
]

Example

curl -X GET https://composable.zeotap.com/api/v1/organizations \
  -H "Authorization: Bearer <token>"

Create Organization

POST /api/v1/organizations

Creates a new organization. The authenticated user becomes the organization owner.

Request Body

{
  "name": "Acme Corp",
  "slug": "acme-corp"
}

Response

Returns the created organization with status 201 Created.

Example

curl -X POST https://composable.zeotap.com/api/v1/organizations \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp"
  }'

Get Organization

GET /api/v1/organizations/{orgId}

Returns a single organization by ID.

Update Organization

PUT /api/v1/organizations/{orgId}

Updates organization details. Requires org_owner or org_admin role.

Request Body

Delete Organization

DELETE /api/v1/organizations/{orgId}

Deletes an organization. Requires org_owner role. All workspaces under the organization must be deleted first.

Response

{
  "status": "deleted"
}

Workspace Management

List Org Workspaces

GET /api/v1/organizations/{orgId}/workspaces

Returns all workspaces belonging to the organization.

Create Workspace in Org

POST /api/v1/organizations/{orgId}/workspaces

Creates a new workspace under the organization.

Request Body

{
  "name": "Production",
  "slug": "production"
}

Member Management

Organization Roles

List Members

GET /api/v1/organizations/{orgId}/members

Returns all organization members with their roles and account details.

Response

[
  {
    "organization_id": "550e8400-e29b-41d4-a716-446655440000",
    "account_id": "660e8400-e29b-41d4-a716-446655440000",
    "role": "org_owner",
    "email": "alice@example.com",
    "name": "Alice Smith",
    "avatar_url": "https://...",
    "created_at": "2024-01-01T00:00:00Z"
  }
]

Invite Member

POST /api/v1/organizations/{orgId}/members/invite

Sends an email invitation to add a new member to the organization. The new account is created on acceptance.

Request Body

Update Member Role

PUT /api/v1/organizations/{orgId}/members/{accountId}/role

Changes a member’s organization role.

Request Body

Remove Member

DELETE /api/v1/organizations/{orgId}/members/{accountId}

Removes a member from the organization. Also removes them from all workspaces under the organization.

Invitations

Invitations are managed via the members/invite endpoint (see Invite Member above) and the invites collection below.

List Invitations

GET /api/v1/organizations/{orgId}/invites

Returns all pending invitations.

Response

[
  {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "organization_id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "newuser@example.com",
    "role": "org_member",
    "invited_by": "660e8400-e29b-41d4-a716-446655440000",
    "inviter_name": "Alice Smith",
    "status": "pending",
    "expires_at": "2024-02-15T00:00:00Z",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
]

Cancel Invitation

DELETE /api/v1/organizations/{orgId}/invites/{inviteId}

Cancels a pending invitation.

Accept Invitation

POST /api/v1/organizations/{orgId}/invites/{inviteId}/accept

Accepts an invitation. The authenticated user is added to the organization with the invited role.

Resend Invitation

POST /api/v1/organizations/{orgId}/invites/{inviteId}/resend

Resends the invitation email for a pending invite.

Organization Object

Organization Member Object

Organization Invite Object