Shares - clarife

Endpoints

Method	Path	Scope	Description
GET	/shares	shares:read	List share links
POST	/shares	shares:write	Create a share link
GET	/shares/:id	shares:read	Get a share with view stats
PATCH	/shares/:id	shares:write	Update a share link
DELETE	/shares/:id	shares:write	Delete a share link

List Shares

bash

curl "https://my.clarife.app/api/v1/shares?document_id=d1a2b3c4-..." \
  -H "Authorization: Bearer clrf_your_key"

Query parameters:

Param	Type	Default	Description
limit	integer	50	Results per page (max 100)
offset	integer	0	Number of results to skip
document_id	uuid	-	Filter shares by document

Response:

json

{
  "data": [
    {
      "id": "s1a2b3c4-...",
      "slug": "aBcDeFgH12345678",
      "document_id": "d1a2b3c4-...",
      "is_active": true,
      "has_password": false,
      "expires_at": null,
      "show_branding": true,
      "view_count": 47,
      "unique_viewers": 15,
      "created_at": "2026-03-20T10:00:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Create a Share

bash

curl -X POST https://my.clarife.app/api/v1/shares \
  -H "Authorization: Bearer clrf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "d1a2b3c4-...",
    "password": "s3cret",
    "allowed_emails": ["jane@company.com"],
    "branding_id": "b1a2b3c4-...",
    "show_branding": true
  }'

Field	Type	Required	Description
document_id	uuid	Yes	Document to share
view_style	string	No	minimalistic (default) or with_navigation
password	string	No	Password-protect the link (paid plans)
allowed_emails	string[]	No	Allowed email addresses (paid plans)
allowed_domains	string[]	No	Allowed email domains (paid plans)
embed_allowed	boolean	No	Allow embedding (paid plans)
embed_type	string	No	iframe, widget, or popup
branding_id	uuid	No	Custom branding to apply (Business plan)
show_branding	boolean	No	Show branding on the share page (Business plan)

Response (201 Created):

json

{
  "data": {
    "id": "s2b3c4d5-...",
    "slug": "aBcDeFgH12345678",
    "document_id": "d1a2b3c4-...",
    "view_style": "minimalistic",
    "show_branding": true,
    "is_active": true,
    "embed_allowed": false,
    "embed_type": null,
    "view_count": 0,
    "unique_viewers": 0,
    "created_at": "2026-03-28T12:00:00Z"
  }
}

Get a Share

bash

curl https://my.clarife.app/api/v1/shares/s1a2b3c4-... \
  -H "Authorization: Bearer clrf_your_key"

Returns the share link with view statistics.

Update a Share

bash

curl -X PATCH https://my.clarife.app/api/v1/shares/s1a2b3c4-... \
  -H "Authorization: Bearer clrf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "password": null,
    "expires_at": "2026-06-01T00:00:00Z",
    "show_branding": false
  }'

Pass null for password to remove password protection. Use expires_at (ISO 8601 or null) to set or clear the expiration date. All fields are optional.

Delete a Share

bash

curl -X DELETE https://my.clarife.app/api/v1/shares/s1a2b3c4-... \
  -H "Authorization: Bearer clrf_your_key"

Response: 204 No Content - empty body.

ℹ️ Note: Deleting a share permanently removes the link. The URL stops working immediately and cannot be restored.

Share URL Format

Public share links follow this format:

https://clarife.app/s/{slug}

Build the URL from the slug field returned when you create or retrieve a share.