---
title: "Create a share link"
method: POST
path: "/api/pages/{id}/shares"
tags: ["shares"]
---

# Create a share link

`POST /api/pages/{id}/shares`

## Request

- Base URL: `https://telawiki.com`
- URL: `https://telawiki.com/api/pages/{id}/shares`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `tela_session`

`editor+`. Produces an unguessable token; the returned `url` is what you hand out. Optionally covers the page's whole subtree, sets a password, and expires.

## Request body

- object
  - `include_descendants` boolean: Share the page's whole subtree, not just the page.
  - `password` string, nullable: Gate the link behind a password.
  - `expires_at` string, nullable: `YYYY-MM-DD HH:MM:SS` UTC, must be in the future.

## Response `201`

Created.

- object
  - `share` ShareLink, required
    - `id` integer, required
    - `token` string, required
    - `page_id` integer, required
    - `include_descendants` boolean, required
    - `has_password` boolean, required: The password itself is never returned.
    - `created_by` integer, required
    - `created_at` string, required: `YYYY-MM-DD HH:MM:SS` in UTC.
    - `expires_at` string, nullable
    - `revoked_at` string, nullable
    - `url` string, required: The link to hand out: `<origin>/share/{token}[/{title-slug}]`.

## Other responses

- `400`: Malformed request. `code` is usually `bad_request` or `invalid_json`.
- `403`: `viewer_no_write` — editor or owner role required.
- `404`: `not_found`.
- `500`: `internal` — server error.

---

[API](https://skmtc.dev/telawiki/apis/tela-rest-api.md) · [All operations](https://skmtc.dev/telawiki/apis/tela-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/telawiki/apis/tela-rest-api/revisions/f316f31f6fcb?raw)