Reference

Teams API

Teams, members, invites and instance settings.

19 operations. Every call needs a session cookie or an Authorization: Bearer nct_… token unless marked Public. Conventions, errors and scopes

GET/instance

Instance settings

Whether team creation is allowed; SMTP details only for the instance admin (the first user).

Response 200 · OK · application/json

InstanceSettings

allowTeamCreationbooleanrequired
Whether any user may create a team (the instance admin always may)
canManagebooleanrequired
The caller is the instance admin and may change these settings
smtpConfiguredbooleanrequired
Invites can be emailed through the instance relay
smtpFromstring
smtpHoststring
smtpInsecureSkipVerifyboolean
smtpPasswordSetboolean
smtpPortinteger (int64)
smtpTlsenum: implicit | starttls | none
smtpUsernamestring

Errors

401Unauthorized
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PATCH/instance

Change the instance settings

Instance admin only: allow team creation and the SMTP relay used to mail invites when a team has no email channel.

Request body · application/json · required

UpdateInstanceInputBody

allowTeamCreationboolean
smtpFromstring
smtpHoststring
smtpInsecureSkipVerifyboolean
smtpPasswordstring
Write-only. Empty clears it.
smtpPortinteger (int64)
smtpTlsenum: implicit | starttls | none
smtpUsernamestring

Response 200 · OK · application/json

InstanceSettings

allowTeamCreationbooleanrequired
Whether any user may create a team (the instance admin always may)
canManagebooleanrequired
The caller is the instance admin and may change these settings
smtpConfiguredbooleanrequired
Invites can be emailed through the instance relay
smtpFromstring
smtpHoststring
smtpInsecureSkipVerifyboolean
smtpPasswordSetboolean
smtpPortinteger (int64)
smtpTlsenum: implicit | starttls | none
smtpUsernamestring

Errors

401Unauthorized
403Forbidden
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/invites/{token}Public

Preview an invite (public)

What the invite link offers: team, role, expiry. 404 invite_invalid, 410 invite_expired or invite_used otherwise. Rate limited per IP.

Parameter	In	Type	Description
`token`required	path	string

Response 200 · OK · application/json

InvitePreview

accountExistsbooleanrequired
emailstring
Set when the invite is bound to one email address
expiresAtstring (date-time)required
invitedBystring
Display name of the person who created the invite
roleenum: owner | admin | developer | viewerrequired
teamNamestringrequired
teamSlugstringrequired

Errors

404Not Foundinvite_invalid
410Goneinvite_expired
422Unprocessable Entity
429Too Many Requests
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/invites/{token}/acceptPublic

Accept an invite

Signed in: joins the team and makes it the session's current team. Not signed in: send name and password (and email for link invites) to create the account and join in one step; the session is started. 409 account_exists when the email already has an account (sign in instead), 403 invite_email_mismatch for an invite sent to another address.

Parameter	In	Type	Description
`token`required	path	string

Request body · application/json

AcceptInviteInputBody

emailstring
Sign-up only
namestring
Sign-up only
passwordstring
Sign-up only: creates the account

Response 200 · OK · application/json

AcceptedInvite

createdAccountbooleanrequired
A new account was created through the invite and signed in
Teamrequired

Errors

403Forbiddeninvite_email_mismatch
404Not Found
409Conflictaccount_exists
410Gone
422Unprocessable Entity
429Too Many Requests
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/teams

List the caller's teams

Every team the signed-in user belongs to, with their role in each. current marks the team the request acts in.

Response 200 · OK · application/json

ListTeamsOutputBody

Team[] | nullrequired

Errors

401Unauthorized
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/teams

Create a team

The caller becomes its owner. 403 team_creation_disabled when the instance admin turned team creation off.

Parameter	In	Type	Description
`Idempotency-Key`	header	string	Client-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours.

Request body · application/json · required

CreateTeamInputBody

namestringrequired

Response 201 · Created · application/json

Team

createdAtstring (date-time)required
currentbooleanrequired
The team the caller is acting in
idstringrequired
memberCountinteger (int64)required
namestringrequired
projectIdsstring[] | null
The caller's project restriction; absent = all projects
roleenum: owner | admin | developer | viewerrequired
The caller's role in this team
slugstringrequired

Errors

401Unauthorized
403Forbiddenteam_creation_disabled
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/teams/{teamId}

Get a team

Parameter	In	Type	Description
`teamId`required	path	string

Response 200 · OK · application/json

Team

createdAtstring (date-time)required
currentbooleanrequired
The team the caller is acting in
idstringrequired
memberCountinteger (int64)required
namestringrequired
projectIdsstring[] | null
The caller's project restriction; absent = all projects
roleenum: owner | admin | developer | viewerrequired
The caller's role in this team
slugstringrequired

Errors

401Unauthorized
403Forbidden
404Not Found
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PATCH/teams/{teamId}

Rename a team

Parameter	In	Type	Description
`teamId`required	path	string

Request body · application/json · required

RenameTeamInputBody

namestringrequired

Response 200 · OK · application/json

Team

createdAtstring (date-time)required
currentbooleanrequired
The team the caller is acting in
idstringrequired
memberCountinteger (int64)required
namestringrequired
projectIdsstring[] | null
The caller's project restriction; absent = all projects
roleenum: owner | admin | developer | viewerrequired
The caller's role in this team
slugstringrequired

Errors

401Unauthorized
403Forbidden
404Not Found
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/teams/{teamId}

Delete a team

Owners only. Requires confirm=<slug> and a team without servers (409 team_has_servers). Deletes every project, token and setting of the team.

Parameter	In	Type	Description
`teamId`required	path	string
`confirm`	query	string	The team's slug

Response 204 · No Content

No body.

Errors

401Unauthorized
403Forbidden
404Not Found
409Conflictteam_has_servers
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/teams/{teamId}/invites

List a team's pending invites

Parameter	In	Type	Description
`teamId`required	path	string

Response 200 · OK · application/json

ListInvitesOutputBody

TeamInvite[] | nullrequired

Errors

401Unauthorized
403Forbidden
404Not Found
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/teams/{teamId}/invites

Invite someone to a team

With email the link is mailed (team email channel, else the instance SMTP relay) and works once for that address; without it a link invite is created with an expiry and a use limit. delivery tells whether the email went out; the response always carries the link.

Parameter	In	Type	Description
`Idempotency-Key`	header	string	Client-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours.
`teamId`required	path	string

Request body · application/json · required

CreateInviteInputBody

emailstring
Mail the invite to this address (single use). Omit for a link invite.
expiresInDaysinteger (int64)
Default 7
maxUsesinteger (int64)
Link invites: how many people may use it (default 1)
projectIdsstring[] | null
Restrict the new member to these projects (developer and viewer only)
roleenum: owner | admin | developer | viewerrequired

Response 201 · Created · application/json

CreatedInvite

deliveryenum: sent | link_only | not_configured | failedrequired
emailErrorstring
TeamInviterequired
linkstringrequired
Where the invitee accepts: an absolute URL when NEBULACTRL_PUBLIC_URL is set, otherwise a path
tokenstringrequired
The raw invite token. Shown once.

Errors

401Unauthorized
403Forbidden
404Not Found
409Conflict
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/teams/{teamId}/invites/{inviteId}

Revoke an invite

Parameter	In	Type	Description
`teamId`required	path	string
`inviteId`required	path	string

Response 204 · No Content

No body.

Errors

401Unauthorized
403Forbidden
404Not Found
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/teams/{teamId}/members

List a team's members

Parameter	In	Type	Description
`teamId`required	path	string

Response 200 · OK · application/json

ListMembersOutputBody

TeamMember[] | nullrequired

Errors

401Unauthorized
403Forbidden
404Not Found
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PATCH/teams/{teamId}/members/{userId}

Change a member's role or project restriction

Owners and admins; only owners manage owners. 409 last_owner when the change would leave the team without an owner.

Parameter	In	Type	Description
`teamId`required	path	string
`userId`required	path	string

Request body · application/json · required

UpdateMemberInputBody

allProjectsboolean
true lifts the project restriction
projectIdsstring[]
Restrict the member to these projects (developer and viewer only); an empty list sees no project
roleenum: owner | admin | developer | viewer

Response 200 · OK · application/json

TeamMember

emailstringrequired
joinedAtstring (date-time)required
namestringrequired
projectIdsstring[] | null
Absent = every project of the team
roleenum: owner | admin | developer | viewerrequired
userIdstringrequired
youbooleanrequired

Errors

401Unauthorized
403Forbidden
404Not Found
409Conflictlast_owner
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/teams/{teamId}/members/{userId}

Remove a member (or leave the team)

Owners and admins remove members; any member may remove themselves. 409 last_owner for the last owner.

Parameter	In	Type	Description
`teamId`required	path	string
`userId`required	path	string

Response 204 · No Content

No body.

Errors

401Unauthorized
403Forbidden
404Not Found
409Conflictlast_owner
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/teams/{teamId}/members/{userId}/password-reset

Generate a password reset link for a member

Owners and admins (admins cannot reset an owner); signed-in users only. The link works once for 30 minutes, needs no SMTP setup and is shown once. Using it ends every session of the member. 409 no_password for members who only sign in through an identity provider.

Parameter	In	Type	Description
`teamId`required	path	string
`userId`required	path	string

Response 201 · Created · application/json

PasswordResetLink

expiresAtstring (date-time)required
linkstringrequired
Where the member sets a new password: an absolute URL when NEBULACTRL_PUBLIC_URL is set, otherwise a path
tokenstringrequired

Errors

401Unauthorized
403Forbidden
404Not Found
409Conflictno_password
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/teams/{teamId}/security

A team's two-factor requirement

Parameter	In	Type	Description
`teamId`required	path	string

Response 200 · OK · application/json

TeamSecurityBody

enrolledinteger (int64)required
Members that have 2FA enabled
membersinteger (int64)required
require2fabooleanrequired
Members must enrol 2FA before acting in this team

Errors

401Unauthorized
403Forbidden
404Not Found
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PUT/teams/{teamId}/security

Require two-factor authentication of every member of the team

Members without 2FA are blocked from acting in the team until they enrol. The caller must have 2FA themselves (409 enrol_first).

Parameter	In	Type	Description
`teamId`required	path	string

Request body · application/json · required

SetTeamSecurityInputBody

require2fabooleanrequired

Response 200 · OK · application/json

TeamSecurityBody

enrolledinteger (int64)required
Members that have 2FA enabled
membersinteger (int64)required
require2fabooleanrequired
Members must enrol 2FA before acting in this team

Errors

401Unauthorized
403Forbidden
404Not Found
409Conflictenrol_first
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/teams/{teamId}/switch

Make a team the session's current team

Re-checks membership (404 for non-members) and stores the team in the session. Browser sessions only: an API token belongs to one team.

Parameter	In	Type	Description
`teamId`required	path	string

Response 200 · OK · application/json

Team

createdAtstring (date-time)required
currentbooleanrequired
The team the caller is acting in
idstringrequired
memberCountinteger (int64)required
namestringrequired
projectIdsstring[] | null
The caller's project restriction; absent = all projects
roleenum: owner | admin | developer | viewerrequired
The caller's role in this team
slugstringrequired

Errors

401Unauthorized
403Forbidden
404Not Found
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.