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
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
Set User Responses Retention
responsesRetentionDaysaccepts integer values0..365ornull.nullclears the user-level override.- The setting is stored in
sessions.metadata.responsesRetentionDays.
store, retentionDays, and retention_days behavior.
Referral Link
Referral links let you share a signup link that is tied to your account.Get or Create Referral Link
Error Response Format
All errors return JSON in this format:Teams
List Teams
Returns all teams the authenticated user belongs to.Create Team
Response:
409 CONFLICT: You already have a team with this name
Get Team Details
balancesshows the team owner’s account balancehigh_spend_text_discountindicates whether a high-spend discount is currently active for this team (when active, it applies automatically)responses_retention_daysis the optional team default for/v1/responsesretention (0..365ornull). 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.roleis the requesting user’s role in this team
Update Team
Response:
Delete Team
Response:
Members
List Members
Response (with pagination):
Update Member Role
Response:
403 FORBIDDEN: Cannot change the owner’s role400 INVALID_INPUT: Cannot change your own role
Update Member Usage Limits
Response:
Remove Member
403 FORBIDDEN: Cannot remove the team owner400 INVALID_INPUT: Cannot remove yourself (use/leave)
Get Own Preferences
Returns the authenticated user’s preferences for this team.effective_*fields show the resolved limit (member override or team default)
Update Own Preferences
Response:
Leave Team
403 FORBIDDEN: Owner must transfer ownership before leaving
Invitations
List Pending Invitations
Send Invitation
Response:
Revoke Invitation
*Provide either
id or token
Response:
Accept Invitation
Response:
409 CONFLICT: Invitation is not pending409 CONFLICT: Invitation has expired
Lookup Invitation
Public endpoint to check invitation details before accepting.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.Invite Links
Get Invite Link Status
Enable/Disable Invite Link
Response:
Send Invite Link via Email
Response:
403 FORBIDDEN: Invite link is disabled429 RATE_LIMITED: Too many emails
Join via Invite Link
Cancel Join Request
Join Requests
List Join Requests
Accept/Reject Join Request
Response:
Delete Join Request
Delete a processed (non-pending) join request.409 CONFLICT: Cannot delete a pending request (must accept/reject first)
Usage & Billing
Get Team Usage
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
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), seeapi-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
Update BYOK Settings
List Team Provider Keys
Add or Replace a Team Provider Key
Revoke a Team Provider Key
Validate a Team Provider Key (Optional Preflight)
- In
prefer_teammode, 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
Update Allowed Models
Response:
allowed_models: nullmeans all models are allowed.- When
allowed_modelsis an object, only models with a value oftrueare allowed for non-owners. Any missing models (or models withfalse) are blocked. - An empty object
{}blocks all models for non-owners. - Team owners are not restricted by the allowlist.
Ownership
Transfer Ownership
Response:
- Current owner becomes admin
- Target member becomes owner
409 CONFLICT: Target is already the owner400 INVALID_INPUT: Cannot transfer ownership to yourself
Role Reference
Rate Limits
Webhooks (Coming Soon)
Future webhook events:team.member.joinedteam.member.removedteam.usage.limit_reachedteam.status.changed