Teams API

Teams group creators, roles, and projects. Tokens always resolve a single team via the mandatory scope:team:<uuid> tuple in their abilities array, and these endpoints let you introspect and manage the teams your account can act on.

Creating a team is a Growth capability; deleting one is not. Create and update require a platform tier that includes Teams; on a lower tier they return 403 TEAM_TIER_REQUIRED and change nothing, the same gate the dashboard applies at Settings → Teams. Delete is not gated. See what the tier gates below.

Background

What the tier gates

Teams, roles and groups sell on the Growth tier, so one rule runs through every write in this part of the API:

Granting access is a paid capability. Withdrawing it is not.

	Gated on Growth
Create a team, role or group	Yes
Rename or re-permission one	Yes
Invite a collaborator, or change their role	Yes
Delete a team, role or group	No
Remove a collaborator, or withdraw an invitation	No
Replace a group's members	Only if the sync adds somebody

The asymmetry is deliberate. A creator who drops below Growth still has collaborators attached, and gating removal would leave them unable to revoke access they no longer want to be paying for; a downgrade would become a permanent grant. So the tier decides what you can build, never what you can take apart.

The same rule holds on the MCP tools and in the dashboard.

Endpoints

GET/v1/teamsList teams POST/v1/teamsCreate a team GET/v1/teams/currentGet the current team GET/v1/teams/{team}Get a team PATCH/v1/teams/{team}Rename a team DELETE/v1/teams/{team}Delete a team

List teams

GET

curl https://api.subscriby.net/v1/teams \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN"

Every team the caller owns or is a member of; teams belonging to other creators are invisible. Never paginated. Useful for a re-auth flow that wants to surface a team picker before the user mints a token scoped to a specific team.

Requires ability

team:view-any

The token must hold this ability, or the call is refused with 403.

MCP tool

list_teams

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

A personal access token minted on the dashboard under Settings, then Tokens, sent as Authorization: Bearer sbt_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team.

In: header

Responses

200OKapplication/json

Array of TeamResource

data*array<>

The items.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

The token is valid but does not carry the ability this endpoint requires; error.context.required_ability names the one to grant. An endpoint that also checks who owns a row or which tier the account is on answers FORBIDDEN, TEAM_TIER_REQUIRED or CONNECTOR_TIER_REQUIRED with the same status, and says so in its own description.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/teams"

{  "data": [    {      "id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",      "name": "Research Collective",      "owner_user_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",      "personal": false,      "created_at": "2026-01-12T10:05:00Z"    }  ]}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: TeamResource[];}export interface TeamResource {  id: string;  name: string;  owner_user_id: string;  personal: boolean;  created_at: string | null;}

Create a team

POST

curl -X POST https://api.subscriby.net/v1/teams \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \  -H "Idempotency-Key: $(uuidgen)" \  -H "Content-Type: application/json" \  -d '{"name": "Research Collective"}'

The caller becomes the team owner. Ownership is not a membership row: the owner cannot be removed from the team, cannot be re-roled, and is the only account permitted to rename or delete it.

A new team starts empty. Add people with Team Members, and give them something to hold with Roles. Answers 201 with the team and emits team.created.

Requires ability

team:create

The token must hold this ability, or the call is refused with 403.

Fires one event

team.created

Delivered to every endpoint subscribed to it once the change is made.

MCP tool

create_team

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Header Parameters

Idempotency-Key*string

A key unique to this operation, such as a fresh UUID. The same key replays the original 2xx response for 24 hours (with Idempotent-Replay: true), so a retry after a timeout never repeats the write; the same key with a different body is refused with 409.

Formatuuid

Request body

JSONWhat the request carriesRequiredapplication/json

A team's name: required on create, optional on update. Ownership does not transfer through this body, and membership moves through its own routes.

name*string

The team's name, up to 255 characters; the only mutable field.

Lengthlength <= 255

Responses

201Createdapplication/json

The new team.

data*

The response's payload.

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

422Validation failedVALIDATION_FAILEDapplication/json

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X POST "https://example.com/v1/teams" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

{  "data": {    "id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",    "name": "Research Collective",    "owner_user_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",    "personal": false,    "created_at": "2026-01-12T10:05:00Z"  }}

Type definitions

The shapes above as types, ready to paste into your client.

Request

export interface StoreTeamRequest {  name: string;}

Response

export interface Response {  data: TeamResource;}export interface TeamResource {  id: string;  name: string;  owner_user_id: string;  personal: boolean;  created_at: string | null;}

Get the current team

GET

curl https://api.subscriby.net/v1/teams/current \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN"

Exactly the team the token is scoped to via scope:team:<uuid>. Zapier's connection test calls this on save to validate the bearer token.

Requires ability

team:view

The token must hold this ability, or the call is refused with 403.

MCP tool

get_me

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Responses

200OKapplication/json

The team named by the token's scope:team: ability.

data*

The response's payload.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundTENANT_MISMATCHapplication/json

With reason: missing_team_scope when the token carries no team scope. RESOURCE_NOT_FOUND: when the scoped team no longer exists.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/teams/current"

{  "data": {    "id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",    "name": "Research Collective",    "owner_user_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",    "personal": false,    "created_at": "2026-01-12T10:05:00Z"  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: TeamResource;}export interface TeamResource {  id: string;  name: string;  owner_user_id: string;  personal: boolean;  created_at: string | null;}

Get a team

GET

curl https://api.subscriby.net/v1/teams/$TEAM_ID \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN"

The team if the caller belongs to it; 404 RESOURCE_NOT_FOUND otherwise, never 403, so foreign-team existence does not leak.

Requires ability

team:view

The token must hold this ability, or the call is refused with 403.

MCP tool

get_team

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

team*string

The team, resolved by the route binder.

Formatuuid

Responses

200OKapplication/json

The team.

data*

The response's payload.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

An id in the path names nothing the token can see. TENANT_MISMATCH: the project sits outside the token's scope:project: allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/teams/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "data": {    "id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",    "name": "Research Collective",    "owner_user_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",    "personal": false,    "created_at": "2026-01-12T10:05:00Z"  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: TeamResource;}export interface TeamResource {  id: string;  name: string;  owner_user_id: string;  personal: boolean;  created_at: string | null;}

Rename a team

PATCH

curl -X PATCH https://api.subscriby.net/v1/teams/$TEAM_ID \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \  -H "Idempotency-Key: $(uuidgen)" \  -H "Content-Type: application/json" \  -d '{"name": "Research Collective (EU)"}'

name is the only mutable field. Ownership does not transfer through this endpoint, and membership moves through its own routes. Owner only. Answers 200 with the team and emits team.updated.

Requires ability

team:update

The token must hold this ability, or the call is refused with 403.

Fires one event

team.updated

Delivered to every endpoint subscribed to it once the change is made.

MCP tool

update_team

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

team*string

The team, resolved by the route binder.

Formatuuid

Header Parameters

Idempotency-Key*string

Formatuuid

Request body

JSONWhat the request carriesRequiredapplication/json

A team's name: required on create, optional on update. Ownership does not transfer through this body, and membership moves through its own routes.

name*string

The team's name, up to 255 characters; the only mutable field.

Lengthlength <= 255

Responses

200OKapplication/json

The team after the change.

data*

The response's payload.

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

422Validation failedVALIDATION_FAILEDapplication/json

The payload broke a rule, and error.fields maps each offending key to its messages. A refusal from the domain, such as a plan that cannot go on sale or a member who cannot be removed, uses the same code with error.message saying why and no fields. On this endpoint: VALIDATION_FAILED: when the caller belongs to the team but does not own it; error.context.team_id names it.

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X PATCH "https://example.com/v1/teams/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

{  "data": {    "id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",    "name": "Research Collective",    "owner_user_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",    "personal": false,    "created_at": "2026-01-12T10:05:00Z"  }}

Type definitions

The shapes above as types, ready to paste into your client.

Request

export interface StoreTeamRequest {  name: string;}

Response

export interface Response {  data: TeamResource;}export interface TeamResource {  id: string;  name: string;  owner_user_id: string;  personal: boolean;  created_at: string | null;}

Delete a team

DELETE

curl -X DELETE https://api.subscriby.net/v1/teams/$TEAM_ID \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \  -H "Idempotency-Key: $(uuidgen)"

Returns 204 No Content and emits team.deleted.

This takes everything with it. Deleting a team deletes every project, plan, subscription and member scoped to it. There is no restore and no soft-delete. If you only want to stop selling, archive the projects instead.

Requires ability

team:delete

The token must hold this ability, or the call is refused with 403.

Fires one event

team.deleted

Delivered to every endpoint subscribed to it once the change is made.

MCP tool

delete_team

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

team*string

The team, resolved by the route binder.

Formatuuid

Header Parameters

Idempotency-Key*string

Formatuuid

Responses

204No content

No content

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

422Validation failedVALIDATION_FAILEDapplication/json

When the team is the caller's only one: an account with no tenant is a state nothing else in the product can produce, and an unscoped token would have nowhere to resolve to. VALIDATION_FAILED: when the caller is a member, not the owner: belonging to a team is not licence to dismantle it for everyone else in it.

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X DELETE "https://example.com/v1/teams/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12"

No body on this response.

Team Members APIInvite, re-role and remove collaborators Roles APIThe permission sets a member can hold Groups APINamed permission bundles several people share team.* eventsTeam creation, rename, deletion, and membership changes.

Teams API

What the tier gatesCopy Anchor Link

EndpointsCopy Anchor Link

List teamsCopy Anchor Link

AuthorizationCopy Anchor Link

ResponsesCopy Anchor Link

Create a teamCopy Anchor Link

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Request bodyCopy Anchor Link

ResponsesCopy Anchor Link

Get the current teamCopy Anchor Link

AuthorizationCopy Anchor Link

ResponsesCopy Anchor Link

Get a teamCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Rename a teamCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request bodyCopy Anchor Link

ResponsesCopy Anchor Link

Delete a teamCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Related

On this page

What the tier gates

Endpoints

List teams

Authorization

Responses

Create a team

Authorization

Header Parameters

Request body

Responses

Get the current team

Authorization

Responses

Get a team

Authorization

Path Parameters

Responses

Rename a team

Authorization

Path Parameters

Header Parameters

Request body

Responses

Delete a team

Authorization

Path Parameters

Header Parameters

Responses