> ## Documentation Index
> Fetch the complete documentation index at: https://docs.productbrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Share links

> Mint, audit, and revoke public read-only links to a project.

A share link is a public, read-only view of a project: titles, descriptions and structure, with free-text notes excluded. Anyone with the URL can open it without logging in, so treat the token as a long-lived secret.

```
POST   /api/v1/share                         mint
GET    /api/v1/share?projectId=              list
DELETE /api/v1/share?projectId=&token=       revoke
```

## Mint a link

```bash theme={null}
curl -X POST "https://productbrain.com/api/v1/share" \
  -H "Authorization: Bearer pb_..." \
  -H "Content-Type: application/json" \
  -d '{ "projectId": "my-project", "expiresInDays": 30 }'
```

```json theme={null}
{
  "token": "h8EqUkVz2nX8hxAi4VlL-",
  "url": "https://productbrain.com/shared/h8EqUkVz2nX8hxAi4VlL-",
  "expiresAt": "2026-10-17T23:21:36.088Z",
  "_meta": { "_tip": "Expires 2026-10-17T23:21:36.088Z. List with GET /api/v1/share?projectId=…; revoke with DELETE …&token=…. Treat the token as a secret." }
}
```

* `expiresInDays` is optional. Without it the link never expires and `expiresAt` is `null`. Only a positive number sets a TTL; anything else is treated as absent.
* `settings.includedGoalIds` scopes the shared view to specific goals: `{ "projectId": "...", "settings": { "includedGoalIds": ["goal-1"] } }`. If none of the ids are goals in the project, the link is still minted but the view will be empty, and `_meta._tip` warns you.

## List links

```bash theme={null}
curl -s "https://productbrain.com/api/v1/share?projectId=my-project" \
  -H "Authorization: Bearer pb_..."
```

```json theme={null}
{
  "tokens": [
    {
      "token": "h8EqUkVz2nX8hxAi4VlL-",
      "url": "https://productbrain.com/shared/h8EqUkVz2nX8hxAi4VlL-",
      "settings": {},
      "createdAt": "2026-09-17T23:21:36.142667+00:00",
      "expiresAt": "2026-10-17T23:21:36.088+00:00",
      "revokedAt": null,
      "active": true
    }
  ],
  "_meta": { "_tip": "Each token is a PUBLIC link. ..." }
}
```

`active` is `false` once a link is revoked or expired. Newest first.

## Revoke a link

```bash theme={null}
curl -X DELETE "https://productbrain.com/api/v1/share?projectId=my-project&token=h8EqUkVz2nX8hxAi4VlL-" \
  -H "Authorization: Bearer pb_..."
```

```json theme={null}
{ "success": true, "revoked": "h8EqUkVz2nX8hxAi4VlL-", "_meta": { "_tip": "Link revoked. ... stops serving within ~30s (edge cache); the DB record is dead immediately." } }
```

Revoking a token that is already revoked, expired, or unknown returns `200` with `"revoked": null` and a tip saying no active token matched.

## Access

Owners and members can mint, list and revoke. A project you cannot access returns `403 { "error": "Not your project" }`; an unknown project returns `404`. List periodically and revoke anything you do not recognise.