---
title: "Create a share link"
method: POST
path: "/v1/diagrams/{id}/links"
tags: ["Diagrams"]
---

# Create a share link

`POST /v1/diagrams/{id}/links`

## Request

- Base URL: `https://api.zindex.ai`
- URL: `https://api.zindex.ai/v1/diagrams/{id}/links`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

A share link shows the diagram's images and the dates of its versions, never its scene, to anyone who has it, until it is revoked, by you, or by Zindex if the diagram breaks the content policy; the diagram stays private. Its token is 22 random base58 characters, and it opens this diagram only. It follows the latest version; add @{revision} for one version. No request body. Share links need Pro or Team: on Free the answer is 403 FEATURE_UNAVAILABLE, and in a team workspace whose owners turned public sharing off, 403 SHARING_DISABLED. Listing and revoking links, and publishing (PUT /v1/diagrams/{id}/sharing), work on every plan.

## Path parameters

- `id` string, required

## Response `201`

The new link

- object
  - `id` string, required
  - `linkId` string, required: lnk_ plus 12 characters; names the link for revoking it
  - `url` string, uri, required: https://zindex.ai/d/{token}: the page, following the latest version; add @{revision} for one version
  - `svg` string, uri, required: The latest version's image as SVG
  - `png` string, uri, required: The latest version's image as PNG
  - `createdAt` string, date-time, required
  - `createdBy` object, nullable: Who made the link; null for older links and for an account that has closed
    - `userId` string, required
    - `name` string, required

## Other responses

- `401`: Missing or invalid API key. Response includes a `code` field that distinguishes the failure mode so clients (dashboard, MCP server) can render actionable copy: `AUTH_REQUIRED` (no key or session was sent), `API_KEY_INVALID` (key not found), `API_KEY_REVOKED` (key was revoked, or its person is no longer in its workspace), `API_KEY_EXPIRED` (key passed its expires_at), and for the site's session cookie `SESSION_EXPIRED` (past its 24 hours), `SESSION_REVOKED` (the account's sessions were ended, for example by a password reset) and `SESSION_INVALID` (not a session this server signed).
- `403`: FEATURE_UNAVAILABLE: the workspace's plan doesn't include share links; EMAIL_NOT_VERIFIED: verify the account's email first; READ_ONLY: a read key or a viewer; SHARING_DISABLED: the workspace's owners turned off public sharing
- `404`: NOT_FOUND
- `429`: RATE_LIMITED: over the request rate limit (see Rate Limiting). Wait retryAfter seconds (also the Retry-After header), then try again.

---

[API](https://skmtc.dev/zindex/apis/zindex-api.md) · [All operations](https://skmtc.dev/zindex/apis/zindex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zindex/apis/zindex-api/revisions/1d21bd5bbf8e?raw)