Skip to main content

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).

Default Team Selection

If you belong to multiple teams, you can set a default team. The default team affects which team context is used by the NanoGPT web app and other session-authenticated requests that support team billing and settings.

Set Default Team

Request Body (all fields optional):
Or by numeric ID:
To clear the default team and return to personal billing:
Response:

User Response Retention Default

Set a user-level default retention for /v1/responses. This applies when a request does not provide retention_days or retentionDays and no team override is active. This is currently exposed through the API endpoint below, not as a visible control in the main web Settings page.

Get User Responses Retention

Response:

Set User Responses Retention

Request Body:
To clear the user-level override and fall back to team/platform defaults:
Rules:
  • responsesRetentionDays accepts integer values 0..365 or null.
  • null clears the user-level override.
  • The setting is stored in sessions.metadata.responsesRetentionDays.
See Responses: response storage and retention for per-request store, retentionDays, and retention_days behavior.
Referral links let you share a signup link that is tied to your account.
Response:

Error Response Format

All errors return JSON in this format:
Common Error Codes:

Teams

List Teams

Returns all teams the authenticated user belongs to.
Response:

Create Team

Request Body:
Response:
Errors:
  • 409 CONFLICT: You already have a team with this name

Get Team Details

Response:
Notes:
  • balances shows the team owner’s account balance
  • high_spend_text_discount indicates whether a high-spend discount is currently active for this team (when active, it applies automatically)
  • responses_retention_days is the optional team default for /v1/responses retention (0..365 or null). It is exposed through the Teams API and is returned by team details; it is not currently shown as a visible control in the team Settings UI.
  • role is the requesting user’s role in this team

Update Team

Required Role: Owner or Admin Request Body:
Response:

Delete Team

Required Role: Owner Request Body:
Response:

Members

List Members

Query Parameters: Response (with pagination):

Update Member Role

Required Role: Owner or Admin Request Body:
Response:
Errors:
  • 403 FORBIDDEN: Cannot change the owner’s role
  • 400 INVALID_INPUT: Cannot change your own role

Update Member Usage Limits

Required Role: Owner or Admin Request Body:
Response:

Remove Member

Required Role: Owner or Admin Request Body:
Response:
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.
Response:
Notes:
  • effective_* fields show the resolved limit (member override or team default)

Update Own Preferences

Request Body:
Response:

Leave Team

Response:
Errors:
  • 403 FORBIDDEN: Owner must transfer ownership before leaving

Invitations

List Pending Invitations

Required Role: Owner or Admin Response:

Send Invitation

Required Role: Owner or Admin Request Body:
Response:

Revoke Invitation

Required Role: Owner or Admin Request Body:
*Provide either id or token Response:

Accept Invitation

Request Body:
Response:
Errors:
  • 409 CONFLICT: Invitation is not pending
  • 409 CONFLICT: Invitation has expired

Lookup Invitation

Public endpoint to check invitation details before accepting.
Authentication: Not required Response (email invitation):
Response (invite link):

Webhooks

Team owners and admins can set one HTTPS URL to receive signed events when members join or leave, the team reaches its usage limit, or its status changes. See Webhooks.
Required Role: Owner or Admin Response:

Required Role: Owner or Admin Request Body:
Response:

Required Role: Owner or Admin Rate Limit: 5 emails per minute Request Body:
Response:
Errors:
  • 403 FORBIDDEN: Invite link is disabled
  • 429 RATE_LIMITED: Too many emails

Request Body:
Response:
Or if already a member:

Cancel Join Request

Request Body:
Response:

Join Requests

List Join Requests

Required Role: Owner or Admin Response:

Accept/Reject Join Request

Required Role: Owner or Admin Request Body:
Response:

Delete Join Request

Delete a processed (non-pending) join request.
Required Role: Owner or Admin Request Body:
Response:
Errors:
  • 409 CONFLICT: Cannot delete a pending request (must accept/reject first)

Usage & Billing

Get Team Usage

Query Parameters: Response:

Notes:
  • Team-billed usage is charged against the team’s balances (shown on GET /api/teams/{teamUuid}).
  • Individual members can choose whether to bill to the team or their personal account via PATCH /api/teams/{teamUuid}/members/self (bill_to_team).

High-Spend Text Discount

Some teams may automatically qualify for discounted pricing on text model usage. When active, GET /api/teams/{teamUuid} will show:

Settings

Update Team Settings

Required Role: Owner or Admin Request Body:
Response:

BYOK (Team Settings & Provider Keys)

Teams can store provider keys and configure how team-billed traffic uses BYOK. For provider slugs and key formats (including JSON-based credentials like AWS/Azure), see api-reference/miscellaneous/byok. Rate Limits:
  • Key management (list/add/revoke): 5 operations per minute per team
  • Key validation: 10 requests per minute per team

Get BYOK Settings

Authorization: Any team member Response:
BYOK modes:

Update BYOK Settings

Authorization: Owner or Admin Request Body:
Response:

List Team Provider Keys

Authorization: Any team member Response:

Add or Replace a Team Provider Key

Authorization: Owner or Admin Request Body:
Response:

Revoke a Team Provider Key

Authorization: Owner or Admin Response:

Validate a Team Provider Key (Optional Preflight)

Authorization: Owner or Admin Request Body:
Response:
Or on failure:
Notes:
  • In prefer_team mode, team-billed traffic will not use a member’s personal BYOK keys unless the client explicitly enables BYOK for the request.

Model Access Control

Get Allowed Models

Response:
Or if all models are allowed:

Update Allowed Models

Required Role: Owner or Admin Request Body:
To allow all models:
Response:
Notes:
  • allowed_models: null means all models are allowed.
  • When allowed_models is an object, only models with a value of true are allowed for non-owners. Any missing models (or models with false) are blocked.
  • An empty object {} blocks all models for non-owners.
  • Team owners are not restricted by the allowlist.

Ownership

Transfer Ownership

Required Role: Owner Request Body:
Response:
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


Rate Limits


Webhooks (Coming Soon)

Future webhook events:
  • team.member.joined
  • team.member.removed
  • team.usage.limit_reached
  • team.status.changed