Skip to content

Teams

Availability: Teams are available in shared workspaces, so on Starter and higher (see teams). API keys need 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

MethodPathScope
GET/api/v1/workspaces/{workspace_public_id}/teamsteams:read
POST/api/v1/workspaces/{workspace_public_id}/teamsteams: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.

FieldTypeRequiredNotes
namestringYesUp to 120 characters.
descriptionstringNo
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:

  • 400 invalid payload: name is missing or empty.
  • 403 forbidden: you’re a read-only member.
  • 409 could 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.

FieldTypeRequiredNotes
namestringNoCan’t be empty. Up to 120 characters.
descriptionstringNo
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.
  • 404 team 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

StatuserrorWhen
400invalid payload, nothing to update, name cannot be emptyThe request body is invalid.
403forbidden, you don't have permission to ...Your role doesn’t allow the change.
404team not foundNo active team with this slug that you can see.
409ambiguous 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:

  • 400 invalid_workspace_id;
  • 403 api_key_workspace_mismatch;
  • 404 workspace_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.

Last updated on