---
title: "Create a shareable link"
method: POST
path: "/api/v1/workspaces/{workspace_id}/share-links"
tags: ["🔗 Share Links"]
---

# Create a shareable link

`POST /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`

Create a public link to a set of posts or a calendar window. `scope` defaults to `selection` (an explicit post list), which needs at least one `plans` or `notes` id. `future` and `all` share a calendar window instead: they require `view: calendar` plus a `calendar_date` range, and only that pairing takes no post ids — the window is resolved on every fetch, so any `plans`/`notes` sent with it are stored but never read. Approval invitations are not part of create — use the send-invitations endpoint afterwards.

## Path parameters

- `workspace_id` string, required

## Request body

- object
  - `name` string, required: Letters, digits and spaces only — it is slugified into the public URL.
  - `scope` 'selection' | 'future' | 'all': `selection` shares the listed posts. `future`/`all` share a calendar window and require `view: calendar`.
  - `view` 'list' | 'calendar' | 'compact_list': Presentation hint for the viewer.
  - `calendar_date` string: Range anchor, required for `future`/`all` and rejected otherwise.
  - `plans` string[]: Post IDs, each in this workspace. Required unless `notes` is given, except on a `future`/`all` calendar window, where the ids are ignored.
  - `notes` string[]: Note IDs, each in this workspace. Stands in for `plans`; ignored on a `future`/`all` calendar window.
  - `show_notes` boolean
  - `is_password_protected` boolean
  - `password` string: Write-only — never returned.
  - `is_single_post` boolean: When true, `plans` must hold exactly one id and `scope` must be `selection`.
  - `allow_external_comments` boolean
  - `allow_external_approval_actions` boolean: Must be false when `scope` is `future`/`all`.
  - `social_selections` object[]

## Response `201`

Share link created

- ShareLinkCreated
  - `status` boolean
  - `message` string
  - `data` ShareLink: A public, tokenized link to a planner calendar or post list. Never carries the link password or its external-approval tokens.
    - `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`.
- `422`: Validation failed (`VALIDATION_ERROR`) or the create failed (`SHARE_LINK_CREATE_FAILED`)
- `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/post.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)