---
title: "Create a shared dashboard link"
method: POST
path: "/shared-dashboards"
tags: ["Shared Dashboards"]
---

# Create a shared dashboard link

`POST /shared-dashboards`

Mint a password-protected, publicly-reachable dashboard link for the shop — the thing a brand sends an agency or an investor. The response carries the `uuid` and the `share_url` to hand out; the password is never echoed back, so store what you sent.

One live link per shop: creating a second while one is active returns 409. Archive the old one first with DELETE, which mints a fresh uuid and password on the next create rather than resurrecting the old link.

Optionally lock the link to a fixed reporting window (`locked_start_date` + `locked_end_date`, both or neither) and choose what it shows via `report_config`. Outreach-volume metrics — TC invites, DMs sent, creators reached, sample counts — cannot be put on a share link and are rejected.

Requires `read_write` scope and an `Idempotency-Key` header. Single-shop only.

## Headers

- `Idempotency-Key` string, nullable

## Request body

- SharedDashboardCreateBody — A new password-protected share link for the caller's shop. ``shop_id`` is deliberately not a body field — the shop comes from ``x-shop-id``. Accepting a second, ignorable copy would let a caller believe they had scoped a link that they had not.
  - `password` string, required — Password the viewer must enter. At least 8 characters with an uppercase letter, a lowercase letter and a digit — or 12+ characters as a passphrase.
  - `locked_start_date` string, date, nullable — Start of a fixed reporting window (with locked_end_date).
  - `locked_end_date` string, date, nullable — End of a fixed reporting window (with locked_start_date).
  - `report_config` ShareReportConfig — Which metric cards and modules a share link shows an external viewer. An omitted/empty config is meaningful: it marks a legacy link, which renders the original fixed six-card layout. That is why ``metrics`` and ``modules`` default to None rather than to empty collections — "no opinion" and "the owner turned everything off" must stay distinguishable.
    - `v` integer — Config schema version
    - `metrics` string[], nullable — Metric keys to show, in display order
    - `modules` object, nullable — Per-module visibility, keyed by SHARE_MODULE_KEYS

## Response `201`

Successful Response

- MySharedDashboard — One share link, with the shop it belongs to.
  - `uuid` string, required
  - `share_url` string, required
  - `status` string, required
  - `created_at` string, required
  - `locked_start_date` string, date, nullable
  - `locked_end_date` string, date, nullable
  - `report_config` ShareReportConfig — Which metric cards and modules a share link shows an external viewer. An omitted/empty config is meaningful: it marks a legacy link, which renders the original fixed six-card layout. That is why ``metrics`` and ``modules`` default to None rather than to empty collections — "no opinion" and "the owner turned everything off" must stay distinguishable.
    - `v` integer — Config schema version
    - `metrics` string[], nullable — Metric keys to show, in display order
    - `modules` object, nullable — Per-module visibility, keyed by SHARE_MODULE_KEYS
  - `shop_id` integer, required — Shop this share link reports on.

## Other responses

- `400` — Validation error, or a missing/oversized Idempotency-Key.
- `403` — API key lacks `read_write` scope (`WRITE_NOT_PERMITTED`).
- `404` — Resource does not exist, or belongs to another shop.
- `409` — Idempotency conflict, or the resource already exists.
- `422` — Validation Error
- `429` — Write-tier rate limit (10/min, 50/hour, 100/day) exceeded.

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) · [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/reacherapp/reacher-data-api/revisions/5eefff009b5b/schema)