← reference

Organizations and Teams API Documentation

Organizations API

Get All Organizations

GET /api/organizations

Returns all organizations the user has access to (based on RLS policies).

Response:

{
  "organizations": [
    {
      "id": "uuid",
      "name": "Acme Corp",
      "description": "A great company",
      "owner_id": "user-uuid",
      "settings": {},
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Get Single Organization

GET /api/organizations/:id

Returns a single organization with the user's role.

Response:

{
  "organization": {
    "id": "uuid",
    "name": "Acme Corp",
    "description": "A great company",
    "owner_id": "user-uuid",
    "settings": {},
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  },
  "user_role": "owner"
}

Create Organization

POST /api/organizations
Body: {
  "name": "Acme Corp",
  "description": "A great company",
  "settings": {}
}

Creates a new organization. The creator becomes the owner.

Response:

{
  "organization": {
    "id": "uuid",
    "name": "Acme Corp",
    "owner_id": "user-uuid",
    ...
  }
}

Update Organization

PUT /api/organizations/:id
Body: {
  "name": "Updated Name",
  "description": "Updated description",
  "settings": {}
}

Updates an organization. Only owners can update.

Delete Organization

DELETE /api/organizations/:id

Deletes an organization. Only owners can delete.

Get Organization Members

GET /api/organizations/:id/members

Returns all members of the organization.

Response:

{
  "members": [
    {
      "user_id": "uuid",
      "full_name": "John Doe",
      "avatar_url": "https://...",
      "role": "owner",
      "is_owner": true
    },
    {
      "user_id": "uuid",
      "full_name": "Jane Smith",
      "avatar_url": "https://...",
      "role": "admin",
      "is_owner": false,
      "joined_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Add Member to Organization

POST /api/organizations/:id/members
Body: {
  "user_id": "user-uuid",
  "role": "member" // "owner", "admin", or "member"
}

Adds a user to the organization. Only owners can add members.

Update Member Role

PUT /api/organizations/:id/members/:userId
Body: {
  "role": "admin" // "admin" or "member" (cannot set to "owner" here)
}

Updates a member's role. Only owners can update roles. Cannot set to "owner" (use transfer ownership endpoint).

Remove Member from Organization

DELETE /api/organizations/:id/members/:userId

Removes a member from the organization. Owners can remove members, or users can remove themselves.

Transfer Organization Ownership

POST /api/organizations/:id/transfer-ownership
Body: {
  "new_owner_id": "user-uuid"
}

Transfers ownership of the organization to another user. Only current owner can transfer.

Teams API

Get All Teams

GET /api/teams?org_id=uuid (optional)

Returns all teams the user has access to. Optionally filter by organization.

Response:

{
  "teams": [
    {
      "id": "uuid",
      "name": "Engineering",
      "description": "Engineering team",
      "org_id": "org-uuid",
      "admin_id": "user-uuid",
      "settings": {},
      "organizations": {
        "id": "org-uuid",
        "name": "Acme Corp"
      },
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Get Single Team

GET /api/teams/:id

Returns a single team with the user's role.

Response:

{
  "team": {
    "id": "uuid",
    "name": "Engineering",
    "org_id": "org-uuid",
    "admin_id": "user-uuid",
    "organizations": {
      "id": "org-uuid",
      "name": "Acme Corp"
    },
    ...
  },
  "user_role": "admin"
}

Create Team

POST /api/teams
Body: {
  "name": "Engineering",
  "description": "Engineering team",
  "org_id": "org-uuid",
  "admin_id": "user-uuid" (optional, defaults to creator),
  "settings": {}
}

Creates a new team. User must be a member of the organization.

Update Team

PUT /api/teams/:id
Body: {
  "name": "Updated Name",
  "description": "Updated description",
  "admin_id": "user-uuid" (optional, only org owners can change),
  "settings": {}
}

Updates a team. Team admins can update name/description. Only org owners can change admin.

Delete Team

DELETE /api/teams/:id

Deletes a team. Only team admins can delete.

Get Team Members

GET /api/teams/:id/members

Returns all members of the team.

Response:

{
  "members": [
    {
      "user_id": "uuid",
      "full_name": "John Doe",
      "avatar_url": "https://...",
      "role": "admin",
      "is_admin": true
    },
    {
      "user_id": "uuid",
      "full_name": "Jane Smith",
      "avatar_url": "https://...",
      "role": "member",
      "is_admin": false,
      "joined_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Add Member to Team

POST /api/teams/:id/members
Body: {
  "user_id": "user-uuid",
  "role": "member" // "admin" or "member"
}

Adds a user to the team. User must be a member of the organization first. Only team admins can add members.

Update Member Role

PUT /api/teams/:id/members/:userId
Body: {
  "role": "admin" // "admin" or "member"
}

Updates a member's role. Only team admins can update roles. Cannot change team admin role (use update team endpoint).

Remove Member from Team

DELETE /api/teams/:id/members/:userId

Removes a member from the team. Team admins can remove members, or users can remove themselves.

Permission Summary

Organizations

  • View: Members of the organization
  • Create: Any authenticated user
  • Update: Organization owners
  • Delete: Organization owners
  • Add Members: Organization owners
  • Update Member Roles: Organization owners
  • Transfer Ownership: Current owner

Teams

  • View: Members of the organization
  • Create: Members of the organization
  • Update: Team admins (name/description), Org owners (admin_id)
  • Delete: Team admins
  • Add Members: Team admins (user must be org member first)
  • Update Member Roles: Team admins
  • Remove Members: Team admins or self

Super Admins

Super admins have full access to all organizations and teams.

Error Responses

All endpoints return standard error responses:

{
  "error": "Error message"
}

Common status codes:

  • 400 - Bad request (missing/invalid parameters)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not found
  • 500 - Internal server error
ORG TEAM API — Docs | HiveJournal