Teams

Overview

The Teams API enables programmatic management of teams, members, invitations, usage tracking, and access control. Base URL: /api/teams Authentication: All endpoints require session authentication unless otherwise noted. Team Identifiers: Endpoints accept either UUID (550e8400-e29b-xxxx-xxxxx-xxxxx) or numeric ID (123).

Error Response Format

All errors return JSON in this format:

{
  "code": "ERROR_CODE",
  "message": "Human-readable description",
  "details": {},
  "status": 400
}

Common Error Codes:

Code	Status	Description
`UNAUTHORIZED`	401	Session required
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Resource conflict (duplicate, wrong state)
`INVALID_INPUT`	422	Validation failed
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error

List Teams

Returns all teams the authenticated user belongs to.

GET /api/teams

Response:

{
  "teams": [
    {
      "uuid": "550e8400-e29b-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "Engineering",
      "status": "active",
      "role": "owner"
    }
  ]
}

Create Team

POST /api/teams

Request Body:

{
  "name": "Engineering"
}

Field	Type	Required	Description
`name`	string	Yes	2-50 characters. Letters, numbers, spaces, hyphens, underscores.

Response:

{
  "team": {
    "uuid": "550e8400-e29b-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "Engineering",
    "status": "active",
    "role": "owner"
  }
}

Errors:

409 CONFLICT: You already have a team with this name

Get Team Details

GET /api/teams/{teamUuid}

Response:

{
  "team": {
    "uuid": "550e8400-e29b-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "Engineering",
    "status": "active",
    "paused_at": null,
    "suspended_at": null,
    "invite_link_enabled": true,
    "invite_link_token": "abc123...",
    "default_member_usage_limit_usd": 100,
    "usage_limit_usd": null,
    "usage_limit_enforced": true,
    "balances": {
      "usd_balance": 250.00,
      "nano_balance": 1500.00
    },
    "role": "owner"
  }
}

Notes:

balances shows the team owner’s account balance
role is the requesting user’s role in this team

Update Team

PATCH /api/teams/{teamUuid}

Required Role: Owner or Admin Request Body:

{
  "name": "New Team Name",
  "status": "paused"
}

Field	Type	Required	Description
`name`	string	No	2-50 characters
`status`	string	No	`active`, `paused`, or `suspended`

Response:

{
  "team": {
    "uuid": "550e8400-e29b-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "New Team Name",
    "status": "paused"
  }
}

Delete Team

DELETE /api/teams/{teamUuid}

Required Role: Owner Request Body:

{
  "name": "Engineering"
}

Field	Type	Required	Description
`name`	string	Yes	Must exactly match team name (confirmation)

Response:

{
  "ok": true
}

Members

List Members

GET /api/teams/{teamUuid}/members

Query Parameters:

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	all	Results per page (max 100)

Response (with pagination):

{
  "members": [
    {
      "sessionId": 12345,
      "sessionUUID": "abc-123-def",
      "role": "owner",
      "joinedAt": "2024-01-15T10:30:00Z",
      "member_name": "Alice",
      "displayName": "Alice Smith",
      "email": "[email protected]",
      "usage_limit_usd": 150,
      "usage_limit_enforced": true,
      "usage_usd_monthly": 45.50
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3
  }
}

Update Member Role

PATCH /api/teams/{teamUuid}/members

Required Role: Owner or Admin Request Body:

{
  "sessionId": 12345,
  "role": "admin"
}

Field	Type	Required	Description
`sessionId`	number	Yes	Target member’s session ID
`role`	string	Yes	`admin` or `member` (cannot set `owner`)

Response:

{
  "ok": true
}

Errors:

403 FORBIDDEN: Cannot change the owner’s role
400 INVALID_INPUT: Cannot change your own role

Update Member Usage Limits

PATCH /api/teams/{teamUuid}/members

Required Role: Owner or Admin Request Body:

{
  "sessionId": 12345,
  "usage_limit_usd": 200,
  "usage_limit_enforced": true
}

Field	Type	Required	Description
`sessionId`	number	Yes	Target member’s session ID
`usage_limit_usd`	number\|null	No	Monthly limit in USD, or `null` to use team default
`usage_limit_enforced`	boolean	No	Hard-enforce the limit (blocks usage when exceeded)

Response:

{
  "ok": true
}

Remove Member

DELETE /api/teams/{teamUuid}/members

Required Role: Owner or Admin Request Body:

{
  "sessionId": 12345
}

Response:

{
  "ok": true
}

Errors:

403 FORBIDDEN: Cannot remove the team owner
400 INVALID_INPUT: Cannot remove yourself (use /leave)

Get Own Preferences

Returns the authenticated user’s preferences for this team.

GET /api/teams/{teamUuid}/members/self

Response:

{
  "bill_to_team": true,
  "name": "Alice",
  "usage_limit_usd": 150,
  "usage_limit_enforced": true,
  "default_member_usage_limit_usd": 100,
  "default_usage_limit_enforced": true,
  "effective_usage_limit_usd": 150,
  "effective_usage_limit_enforced": true
}

Notes:

effective_* fields show the resolved limit (member override or team default)

Update Own Preferences

PATCH /api/teams/{teamUuid}/members/self

Request Body:

{
  "bill_to_team": true,
  "name": "Alice Smith"
}

Field	Type	Required	Description
`bill_to_team`	boolean	No	Bill usage to team or personal account
`name`	string	No	Display name (1-100 characters)

Response:

{
  "ok": true,
  "preferences": {
    "bill_to_team": true,
    "name": "Alice Smith",
    "usage_limit_usd": 150,
    "usage_limit_enforced": true
  }
}

Leave Team

POST /api/teams/{teamUuid}/leave

Response:

{
  "ok": true
}

Errors:

403 FORBIDDEN: Owner must transfer ownership before leaving

Invitations

List Pending Invitations

GET /api/teams/{teamUuid}/invitations

Required Role: Owner or Admin Response:

{
  "invitations": [
    {
      "id": "inv-uuid-123",
      "email": "[email protected]",
      "role": "member",
      "status": "pending",
      "token": "abc123...",
      "created_at": "2024-01-15T10:30:00Z",
      "expires_at": "2024-01-22T10:30:00Z"
    }
  ]
}

Send Invitation

POST /api/teams/{teamUuid}/invitations

Required Role: Owner or Admin Request Body:

{
  "email": "[email protected]",
  "role": "member"
}

Field	Type	Required	Description
`email`	string	Yes	Valid email address
`role`	string	No	`admin` or `member` (default: `member`)

Response:

{
  "invitation": {
    "id": "inv-uuid-123",
    "email": "[email protected]",
    "role": "member",
    "status": "pending",
    "token": "abc123..."
  }
}

Revoke Invitation

PATCH /api/teams/{teamUuid}/invitations

Required Role: Owner or Admin Request Body:

{
  "action": "revoke",
  "id": "inv-uuid-123"
}

Field	Type	Required	Description
`action`	string	No	Must be `revoke` (default)
`id`	string	No*	Invitation UUID
`token`	string	No*	Invitation token (min 16 chars)

*Provide either id or token Response:

{
  "ok": true
}

Accept Invitation

POST /api/teams/invitations/accept

Request Body:

{
  "token": "abc123def456..."
}

Field	Type	Required	Description
`token`	string	Yes	Invitation token (min 16 characters)

Response:

{
  "ok": true
}

Errors:

409 CONFLICT: Invitation is not pending
409 CONFLICT: Invitation has expired

Lookup Invitation

Public endpoint to check invitation details before accepting.

GET /api/teams/invitations/lookup?token=abc123...

Authentication: Not required Response (email invitation):

{
  "type": "invitation",
  "email": "[email protected]",
  "status": "pending",
  "teamName": "Engineering"
}

Response (invite link):

{
  "type": "link",
  "teamName": "Engineering",
  "enabled": true
}

Invite Links

Get Invite Link Status

GET /api/teams/{teamUuid}/invite-link

Required Role: Owner or Admin Response:

{
  "enabled": true,
  "token": "abc123def456..."
}

Enable/Disable Invite Link

POST /api/teams/{teamUuid}/invite-link

Required Role: Owner or Admin Request Body:

{
  "action": "enable"
}

Field	Type	Required	Description
`action`	string	No	`enable` (default) or `disable`

Response:

{
  "enabled": true,
  "token": "abc123def456..."
}

Send Invite Link via Email

POST /api/teams/{teamUuid}/invite-link/email

Required Role: Owner or Admin Rate Limit: 5 emails per minute Request Body:

{
  "emails": ["[email protected]", "[email protected]"]
}

Field	Type	Required	Description
`emails`	string[]	Yes	1-10 valid email addresses

Response:

{
  "ok": true
}

Errors:

403 FORBIDDEN: Invite link is disabled
429 RATE_LIMITED: Too many emails

Join via Invite Link

POST /api/teams/join

Request Body:

{
  "token": "abc123def456..."
}

Response:

{
  "ok": true
}

Or if already a member:

{
  "ok": true,
  "alreadyMember": true
}

Cancel Join Request

DELETE /api/teams/join

Request Body:

{
  "token": "abc123def456..."
}

Response:

{
  "ok": true
}

Join Requests

List Join Requests

GET /api/teams/{teamUuid}/join-requests

Required Role: Owner or Admin Response:

{
  "requests": [
    {
      "id": "req-uuid-123",
      "user_id": 12345,
      "status": "pending",
      "created_at": "2024-01-15T10:30:00Z",
      "name": "Charlie",
      "email": "[email protected]"
    }
  ]
}

Accept/Reject Join Request

PATCH /api/teams/{teamUuid}/join-requests

Required Role: Owner or Admin Request Body:

{
  "action": "accept",
  "id": "req-uuid-123"
}

Field	Type	Required	Description
`action`	string	No	`accept` (default) or `reject`
`id`	string	Yes	Join request UUID

Response:

{
  "ok": true
}

Delete Join Request

Delete a processed (non-pending) join request.

DELETE /api/teams/{teamUuid}/join-requests

Required Role: Owner or Admin Request Body:

{
  "id": "req-uuid-123"
}

Response:

{
  "ok": true
}

Errors:

409 CONFLICT: Cannot delete a pending request (must accept/reject first)

Usage & Billing

Get Team Usage

GET /api/teams/{teamUuid}/usage

Query Parameters:

Parameter	Type	Default	Description
`from`	string	-	Start date (ISO format)
`to`	string	-	End date (ISO format)

Response:

{
  "byActor": [
    {
      "actorSessionId": 12345,
      "displayName": "Alice Smith",
      "totalAmount": 45.50,
      "currency": "USD"
    },
    {
      "actorSessionId": 12346,
      "displayName": "Bob Jones",
      "totalAmount": 32.25,
      "currency": "USD"
    }
  ],
  "totals": [
    {
      "totalAmount": 77.75,
      "currency": "USD"
    }
  ]
}

Settings

Update Team Settings

PATCH /api/teams/{teamUuid}/settings

Required Role: Owner or Admin Request Body:

{
  "default_member_usage_limit_usd": 100,
  "usage_limit_enforced": true
}

Field	Type	Required	Description
`default_member_usage_limit_usd`	number\|null	No	Default monthly limit for members
`team_usage_limit_usd`	number\|null	No	Team-wide spending limit
`usage_limit_enforced`	boolean	No	Hard-enforce limits

Response:

{
  "ok": true
}

Model Access Control

Get Allowed Models

GET /api/teams/{teamUuid}/allowed-models

Response:

{
  "allowed_models": {
    "claude-sonnet-4-5": true,
    "gpt-5-1": true,
    "claude-opus-4-5": false
  },
  "all_allowed": false
}

Or if all models are allowed:

{
  "allowed_models": null,
  "all_allowed": true
}

Update Allowed Models

PATCH /api/teams/{teamUuid}/allowed-models

Required Role: Owner or Admin Request Body:

{
  "allowed_models": {
    "claude-sonnet-4-5": true,
    "gpt-5-1": true,
    "claude-opus-4-5": false
  }
}

To allow all models:

{
  "allowed_models": null
}

Field	Type	Required	Description
`allowed_models`	object\|null	Yes	Map of model keys to boolean, or `null` for all

Response:

{
  "ok": true,
  "allowed_models": {
    "claude-sonnet-4-5": true,
    "gpt-5-1": true,
    "claude-opus-4-5": false
  },
  "all_allowed": false
}

Notes:

Models not listed in the map are allowed by default
Set a model to false to explicitly restrict it
Set allowed_models to null to allow all models

Ownership

Transfer Ownership

POST /api/teams/{teamUuid}/owner

Required Role: Owner Request Body:

{
  "sessionId": 12345
}

Field	Type	Required	Description
`sessionId`	number	Yes	New owner’s session ID

Response:

{
  "ok": true
}

Side Effects:

Current owner becomes admin
Target member becomes owner

Errors:

409 CONFLICT: Target is already the owner
400 INVALID_INPUT: Cannot transfer ownership to yourself

Role Reference

Role	Create Team	View Team	Manage Members	Manage Settings	Delete Team
Owner	-	Yes	Yes	Yes	Yes
Admin	-	Yes	Yes	Yes	No
Member	-	Yes	No	No	No

Rate Limits

Endpoint	Limit
`POST /api/teams/{teamUuid}/invite-link/email`	5 emails per minute

Webhooks (Coming Soon)

Future webhook events:

team.member.joined
team.member.removed
team.usage.limit_reached
team.status.changed

Get Started

Endpoint Examples

API Reference

Miscellaneous

Integrations

​Overview

​Error Response Format

​Teams

​List Teams

​Create Team

​Get Team Details

​Update Team

​Delete Team

​Members

​List Members

​Update Member Role

​Update Member Usage Limits

​Remove Member

​Get Own Preferences

​Update Own Preferences

​Leave Team

​Invitations

​List Pending Invitations

​Send Invitation

​Revoke Invitation

​Accept Invitation

​Lookup Invitation

​Invite Links

​Get Invite Link Status

​Enable/Disable Invite Link

​Send Invite Link via Email

​Join via Invite Link

​Cancel Join Request

​Join Requests

​List Join Requests

​Accept/Reject Join Request

​Delete Join Request

​Usage & Billing

​Get Team Usage

​Settings

​Update Team Settings

​Model Access Control

​Get Allowed Models

​Update Allowed Models

​Ownership

​Transfer Ownership

​Role Reference

​Rate Limits

​Webhooks (Coming Soon)

Overview

Error Response Format

Teams

List Teams

Create Team

Get Team Details

Update Team

Delete Team

Members

List Members

Update Member Role

Update Member Usage Limits

Remove Member

Get Own Preferences

Update Own Preferences

Leave Team

Invitations

List Pending Invitations

Send Invitation

Revoke Invitation

Accept Invitation

Lookup Invitation

Invite Links

Get Invite Link Status

Enable/Disable Invite Link

Send Invite Link via Email

Join via Invite Link

Cancel Join Request

Join Requests

List Join Requests

Accept/Reject Join Request

Delete Join Request

Usage & Billing

Get Team Usage

Settings

Update Team Settings

Model Access Control

Get Allowed Models

Update Allowed Models

Ownership

Transfer Ownership

Role Reference

Rate Limits

Webhooks (Coming Soon)