Skip to content

Workspaces

Availability: The workspace endpoints are available on every plan, including Free. API keys need the workspaces:read scope.

The workspace endpoints return the workspaces your API key can reach. Most other endpoints take a workspace’s public_id, so this is usually your first call. A key restricted to one workspace sees only that workspace.

Endpoints

MethodPathScope
GET/api/v1/workspacesworkspaces:read
GET/api/v1/workspaces/{workspace_public_id}workspaces:read

List workspaces

Returns every workspace you’re an active member of, plus archived workspaces you own. A key restricted to one workspace returns only that workspace. The list isn’t paginated.

curl https://app.shortn.link/api/v1/workspaces \
  -H "Authorization: Bearer $SHORTN_API_KEY"
{
  "data": [
    {
      "public_id": "8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10",
      "name": "Acme Marketing",
      "slug": "acme-marketing",
      "description": "",
      "is_personal": false,
      "active": true,
      "role": "owner",
      "team_count": 2,
      "member_count": 4,
      "link_count": 120,
      "created_at": "2026-03-02T10:15:00Z",
      "updated_at": "2026-11-10T08:00:00Z"
    }
  ]
}
FieldNotes
public_idThe ID other endpoints take.
is_personaltrue for the personal workspace every account has.
activefalse when the workspace is archived.
roleYour role in the workspace: owner, administrator, collaborator or read_only. See members and roles.
team_count, member_count, link_countThe workspace’s teams, active members and links.

Get a workspace

Returns one active workspace, with the same fields as the list.

curl https://app.shortn.link/api/v1/workspaces/8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10 \
  -H "Authorization: Bearer $SHORTN_API_KEY"
{
  "data": {
    "public_id": "8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10",
    "name": "Acme Marketing",
    "slug": "acme-marketing",
    "description": "",
    "is_personal": false,
    "active": true,
    "role": "owner",
    "team_count": 2,
    "member_count": 4,
    "link_count": 120,
    "created_at": "2026-03-02T10:15:00Z",
    "updated_at": "2026-11-10T08:00:00Z"
  }
}

An archived workspace returns 404 here, although the list includes it.

Errors

StatuscodeWhen
400invalid_workspace_idThe ID isn’t a workspace public_id.
403api_key_workspace_mismatchThe key is restricted to a different workspace.
404workspace_not_foundThe workspace doesn’t exist, is archived, or you aren’t a member.

Errors look like this:

{
  "code": "workspace_not_found",
  "error": "Workspace not found"
}

Errors every endpoint can return (a missing key, a missing scope, rate limits) are listed on authentication.

Last updated on