---
title: sherlink
description: The v1 reference for short links and access policy.
---

# sherlink

Base path `/api/sherlink/v1`. See [API reference](/api) for
authentication and the `api.shebang.pro` rewrite.

Every route requires an `shb_...` key or bearer with `link` in scope
(master keys always qualify). `project` behaves exactly as described in
[platform](/api/platform#projects). Every sherpage page and sherserve
object gets a link automatically at creation — see
[short links and aliases](/sherlink/short-links-and-aliases). Deleting a
link deletes the wrapped resource too (a link is 1:1 with its resource,
never left orphaned).

The **Link** every route below returns:

```json
{
  "id": "uuid",
  "app": "sherpage | sherserve",
  "resourceType": "page | object",
  "resourceId": "uuid",
  "title": "string",
  "resourceSlug": "string",
  "public_id": "string",
  "resourceContentType": "string | null",
  "resourceSizeBytes": "number | null",
  "code": "string",
  "alias": "string | null",
  "shortUrl": "string",
  "url": "string",
  "access": "private | password | allow_list | public",
  "hasPassword": "boolean",
  "status": "active | archived",
  "expiresAt": "ISO 8601 | null",
  "maxViews": "number | null",
  "viewCount": "number",
  "lastOpenedAt": "ISO 8601 | null",
  "createdAt": "ISO 8601",
  "updatedAt": "ISO 8601"
}
```

`GET /links` additionally includes `project` (the resolved project's
slug, shared by the whole list) on each entry.

### GET /api/sherlink/v1/links

Lists links across both sherpage and sherserve for one project.

- **Auth** — `link` scope.
- **Query params** — `project` (slug, optional).
- **Response** — `200 { "links": [Link, ...] }`.
- **Errors** — `403 insufficient_scope`.

### GET /api/sherlink/v1/links/{id}

Fetches one link.

- **Auth** — `link` scope, read access to the link's project.
- **Path params** — `id` (uuid).
- **Response** — `200 Link`.
- **Errors** — `404 not_found`, `403 insufficient_scope`.

### PATCH /api/sherlink/v1/links/{id}

Updates a link's access policy and/or metadata.

- **Auth** — `link` scope, write access to the link's project.
- **Path params** — `id` (uuid).
- **Request body** — any of `access`, `password` (string or `null`),
  `expiresAt` (string or `null`), `maxViews` (number or `null`), `alias`
  (string or `null`), `title`, `status` (`"active"` or `"archived"`) —
  all optional.
- **Response** — `200 Link`.
- **Errors** — `400` (invalid field value), `404 not_found`, `409
  alias_conflict`, `400 password_required`, `403 insufficient_scope`.

### DELETE /api/sherlink/v1/links/{id}

Deletes a link — and, since a link is 1:1 with its resource, the wrapped
page or object along with it.

- **Auth** — `link` scope, write access to the link's project.
- **Path params** — `id` (uuid).
- **Response** — `204` (empty body).
- **Errors** — `404 not_found`, `403 insufficient_scope`, `500
  storage_cleanup_failed`, `500 link_cleanup_failed`.

## Next

[sherbase](/api/sherbase) — databases.