Shares

The Shares API manages share aggregates created for images and collections. Every share is private by default and must be explicitly published to be accessible to whoever holds the link.

List Shares

Endpoint: GET /api/shares

Authentication: JWT Token required

Query Parameters:

• limit - Items per page (default: 10)
• cursor - Pagination cursor (optional)
• orderBy - Sort field (default: createdAt)
• order - Sort direction: asc or desc (default: desc)
• searchTerm - Free-text search (optional)
• expiry - Filter by expiration: any, hasExpiry, expired, noExpiry (optional)
• protection - Filter by password: any, passwordProtected, noPassword (optional)
• type - Filter by shareable type: all, image, collection (optional)
• shareableId - Restrict to a specific shareable UUID (optional)
• shareableType - Restrict to image or collection (optional)

Response:

{
  "meta": {
    "size": 10,
    "total": 42,
    "nextCursor": "cursor-string",
    "prevCursor": null
  },
  "data": [
    {
      "shareId": "share-uuid",
      "shareUrl": "https://your-domain.com/i/abc123",
      "shortCode": "abc123",
      "type": "image",
      "isPublished": true,
      "expiresAt": "2026-05-01T00:00:00+00:00",
      "isExpired": false,
      "requiresPassword": true,
      "createdAt": "2026-04-25T18:11:42+00:00",
      "shareable": {
        "id": "image-uuid",
        "name": "example.jpg",
        "previewUrl": "/image/image-uuid_thumbnail.jpg"
      },
      "variant": {
        "width": 800,
        "height": null,
        "filter": null,
        "format": "jpg"
      },
      "id": "share-uuid"
    }
  ]
}

nextCursor and prevCursor are only present when the corresponding direction has more results.

Check If Any Shares Exist

Lightweight existence probe used by SSR to avoid empty-state flicker.

Endpoint: GET /api/shares/exists

Authentication: JWT Token required

Response:

{
  "exists": true
}

Publish Share

Marks the share as published so its link becomes reachable.

Endpoint: PUT /api/share/{id}/publish

Authentication: JWT Token required

Response:

HTTP 204 No Content

Unpublish Share

Reverts the share to private. The link returns 404 to anyone who tries it.

Endpoint: PUT /api/share/{id}/unpublish

Authentication: JWT Token required

Response:

HTTP 204 No Content

Set Share Password

Sets, updates, or clears the share’s password. Send null (or omit) to remove the password.

Endpoint: PUT /api/share/{id}/password

Authentication: JWT Token required

Request:

{
  "password": "correct-horse-battery-staple"
}

Passwords must be at least 6 characters.

To clear the password:

{
  "password": null
}

Response:

HTTP 204 No Content

Set Share Expiration

Sets or clears the share’s expiration timestamp. Send null to remove expiration.

Endpoint: PUT /api/share/{id}/expiration

Authentication: JWT Token required

Request:

{
  "expiresAt": "2026-12-31T23:59:59+00:00"
}

To clear the expiration:

{
  "expiresAt": null
}

Response:

HTTP 204 No Content

Setting an expiration that is in the past returns HTTP 400 Bad Request.

Unlock Share

Submits a password to unlock a password-protected share. On success, an HTTP-only cookie is set (24-hour TTL) so the share can be opened without re-prompting.

Endpoint: POST /api/share/{id}/unlock

Authentication: None required (this is the public unlock endpoint)

Request:

{
  "password": "correct-horse-battery-staple"
}

Response:

• HTTP 204 No Content with a Set-Cookie header on success.
• HTTP 204 No Content with no cookie if the share has no password set (no-op).
• HTTP 400 Bad Request with body {"error": {"message": "invalid_password", ...}} if the password is wrong.
• HTTP 404 Not Found if the share does not exist.