---
title: "List shareable links"
method: GET
path: "/api/v1/workspaces/{workspace_id}/share-links"
tags: ["🔗 Share Links"]
---

# List shareable links

`GET /api/v1/workspaces/{workspace_id}/share-links`

## Request

- Base URL: `https://api.contentstudio.io`
- URL: `https://api.contentstudio.io/api/v1/workspaces/{workspace_id}/share-links`
- Auth: API key in header `X-API-Key`

Retrieve the workspace's planner share links, newest first. Neither the link password nor its external-approval tokens are ever returned.

## Path parameters

- `workspace_id` string, required

## Query parameters

- `page` integer
- `per_page` integer
- `search` string

## Response `200`

Share links retrieved

- ShareLinkList
  - `status` boolean
  - `message` string
  - `current_page` integer
  - `per_page` integer
  - `total` integer
  - `last_page` integer
  - `from` integer, nullable
  - `to` integer, nullable
  - `data` ShareLink[]
    - `id` string: Reusable OpenAPI schemas for the public-API share-link responses. The link object is returned by list, create, update and delete-adjacent responses, so it is described once and referenced via `@OA\JsonContent(ref="#/components/schemas/<Name>")`. Note what is deliberately ABSENT from ShareLink: `password` and `approval_tokens`. Both exist on the model and on ShareLinkData, and the internal endpoints return them — documenting them here would be documenting a leak.
    - `_id` string: Deprecated alias for `id` — will be removed once clients migrate.
    - `name` string
    - `link_id` string: The public token in the URL: a slug of the name plus a unique suffix.
    - `url` string, nullable: Built on the workspace's own domain, so white-labelled workspaces get their own host.
    - `scope` 'selection' | 'future' | 'all', nullable: `selection` shares an explicit post list; `future`/`all` share a calendar window. Null if the stored value is not one the UI produces.
    - `view` 'list' | 'calendar' | 'compact_list', nullable: Presentation hint. Null for an unrecognised stored value.
    - `is_password_protected` boolean
    - `is_disabled` boolean: A disabled link stops resolving without being deleted.
    - `show_notes` boolean
    - `is_single_post` boolean
    - `allow_external_comments` boolean
    - `allow_external_approval_actions` boolean
    - `approval_flow` boolean: Whether the external-approval-by-email flow is enabled.
    - `approval_emails` string[]
    - `approval_option` 'anyone' | 'everyone', nullable
    - `approval_status` string, nullable
    - `outstanding_invitations_count` integer: External approvers with a live, un-actioned invitation.
    - `created_at` string, nullable
    - `updated_at` string, nullable

## Other responses

- `401`: Unauthorized - Invalid or missing API key
- `403`: Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.
- `429`: Too Many Requests - Rate limit exceeded

## Changes

- **2026-09-22** `ad0b687289a3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/contentstudio/apis/contentstudio-api-v1/changes/api/v1/workspaces/:workspace_id/share-links/get.md)

---

[API](https://skmtc.dev/contentstudio/apis/contentstudio-api-v1.md) - [All operations](https://skmtc.dev/contentstudio/apis/contentstudio-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/contentstudio/apis/contentstudio-api-v1/revisions/2ce09d50369c?raw)