Teams
teams:read to list and read teams, and
teams:write to create, change and archive them.Teams group links and people inside a workspace. You list and create teams through their
workspace, and read, change and archive a single team by its slug. Other endpoints that
take teams, such as tags or UTM templates, use the team’s public_id.
These endpoints return their objects directly, without a data wrapper, and their errors
carry only an error message.
Endpoints
| Method | Path | Scope |
|---|---|---|
GET | /api/v1/workspaces/{workspace_public_id}/teams | teams:read |
POST | /api/v1/workspaces/{workspace_public_id}/teams | teams:write |
GET | /api/v1/teams/{slug} | teams:read |
PUT | /api/v1/teams/{slug} | teams:write |
DELETE | /api/v1/teams/{slug} | teams:write |
Team slugs
A team’s slug is unique only within its workspace. When a key can reach several
workspaces that each have a team with the same slug, add ?workspace=<workspace_public_id>
to the /api/v1/teams/{slug} endpoints. Without it, an ambiguous slug returns 409. A key
restricted to one workspace always looks the slug up in that workspace.
List teams
Returns the workspace’s active teams, newest first. Workspace owners and administrators see every team; other members see the teams they belong to.
curl https://app.shortn.link/api/v1/workspaces/8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10/teams \
-H "Authorization: Bearer $SHORTN_API_KEY"{
"teams": [
{
"id": 31,
"public_id": "5b7e0c2d-91a4-4f3e-8d6b-0a2c4e6f8b13",
"name": "Paid Social",
"slug": "paid-social",
"description": "Campaign links for paid social",
"workspace_id": 12,
"owner_user_id": 7,
"active": true,
"created_at": "2026-06-01T09:00:00Z",
"updated_at": "2026-10-20T14:30:00Z",
"member_count": 3,
"link_count": 48,
"template_count": 2
}
]
}member_count, link_count (links assigned to the team) and template_count (UTM
templates assigned to it) are left out when they’re 0.
Create a team
Owners, administrators and collaborators can create teams. You become the team’s owner.
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | Up to 120 characters. |
description | string | No |
curl -X POST https://app.shortn.link/api/v1/workspaces/8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10/teams \
-H "Authorization: Bearer $SHORTN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Paid Social", "description": "Campaign links for paid social"}'The slug is made from the name. If the workspace already has it, Shortn adds -2, -3 and
so on. The response is 200:
{
"id": 31,
"slug": "paid-social",
"public_id": "5b7e0c2d-91a4-4f3e-8d6b-0a2c4e6f8b13"
}Errors:
400invalid payload:nameis missing or empty.403forbidden: you’re a read-only member.409could not allocate a unique team slug.
Get a team
curl "https://app.shortn.link/api/v1/teams/paid-social?workspace=8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10" \
-H "Authorization: Bearer $SHORTN_API_KEY"{
"id": 31,
"public_id": "5b7e0c2d-91a4-4f3e-8d6b-0a2c4e6f8b13",
"name": "Paid Social",
"slug": "paid-social",
"description": "Campaign links for paid social",
"workspace_id": 12,
"workspace_public_id": "8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10",
"owner_user_id": 7,
"active": true,
"created_at": "2026-06-01T09:00:00Z",
"updated_at": "2026-10-20T14:30:00Z",
"member_count": 3
}You can read teams you belong to, or any team if you’re a workspace owner or administrator.
Otherwise the team returns 404.
Update a team
Change a team’s name, description, or both. Send only the fields you want to change. The slug doesn’t change when you rename a team.
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | No | Can’t be empty. Up to 120 characters. |
description | string | No |
curl -X PUT https://app.shortn.link/api/v1/teams/paid-social \
-H "Authorization: Bearer $SHORTN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Paid Social EU"}'The response is the updated team, as in Get a team.
Who can update a team:
- the team’s owner or administrators;
- the workspace’s owner or administrators.
Errors:
400:nothing to update,name cannot be empty, or the name is too long.403: you don’t have permission to update this team.404team not found.409: the slug is ambiguous (see team slugs).
Archive a team
DELETE archives the team: it no longer appears in lists, and its members are removed from
it. Only the team’s owner or the workspace owner can archive a team.
curl -X DELETE https://app.shortn.link/api/v1/teams/paid-social \
-H "Authorization: Bearer $SHORTN_API_KEY"{
"success": true
}A team that still has links, tags, UTM templates, destinations or other resources assigned
can’t be archived. You get a 409 naming how many resources still belong to the team:
{
"error": "team has 4 assigned resources; reassign them before archiving the team"
}Reassign those resources first.
Errors
| Status | error | When |
|---|---|---|
400 | invalid payload, nothing to update, name cannot be empty | The request body is invalid. |
403 | forbidden, you don't have permission to ... | Your role doesn’t allow the change. |
404 | team not found | No active team with this slug that you can see. |
409 | ambiguous slug, or ... assigned resources ... | See team slugs and archive a team. |
The workspace in the path is checked before the team endpoints run. That check returns the
API’s usual error shape, with a code:
400invalid_workspace_id;403api_key_workspace_mismatch;404workspace_not_found, which an archived workspace also returns.
Errors every endpoint can return (a missing key, a missing scope, rate limits) are listed on authentication.