Teams API

The /v1/teams endpoints manage teams — groupings of accounts within your organization used to organize channels and control access. An account belongs to at most one team at a time (assignment moves the account; there are no join rows). Accounts without a team live in the default team.

Requires authentication.

---

List teams

GET /api/v1/teams

Returns all teams in your organization inside data.

---

Create a team

POST /api/v1/teams

Request body

Field	Type	Required	Description
name	string	yes	1–100 characters
slug	string	no	URL-friendly identifier
description	string	no	Up to 280 characters
avatarUrl	string	no	Team avatar URL
accountIds	string[]	no	Accounts to assign to the team on create

Example

curl -X POST https://<your-api-origin>/api/v1/teams \
  -H "Authorization: Bearer sx_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Launch squad",
    "description": "Accounts used for product launches",
    "accountIds": ["acc_instagram", "acc_x"]
  }'

Response — 200 OK

The new team inside data.

---

Get a team

GET /api/v1/teams/{id}

Returns one team inside data; 404 not_found otherwise.

---

Update a team

PATCH /api/v1/teams/{id}

Updates team fields (name, slug, description, avatar). Returns the updated team inside data.

---

Delete a team

DELETE /api/v1/teams/{id}

Deletes the team. A team that still owns accounts cannot be deleted:

{
  "error": {
    "code": "in_use",
    "message": "Move or remove the team's accounts first."
  }
}

Status	Body	When
409	{ "error": { "code": "in_use", ... } }	Team still owns accounts
404	{ "error": { "code": "not_found", ... } }	Unknown team

On success: { "data": { "success": true } }. Deleting a team does not disconnect its accounts — move them first (below), and they land in the default team.

---

Assign an account to a team

POST /api/v1/teams/{id}/accounts

Request body

Field	Type	Required	Description
accountId	string	yes	Account to assign

Because membership is 1:1, assigning an account that already belongs to another team moves it. Returns the updated team (or assignment result) inside data.

Errors

Status	Body
403	{ "error": { "code": "forbidden", "message": "Account not accessible" } }

---

Remove an account from a team

DELETE /api/v1/teams/{id}/accounts/{accountId}

Removes the account from the team and reassigns it to the default team. Returns { "data": { "success": true } }.

Related

• Teams — the user-facing guide.
• Accounts API — list the accounts you can assign.