Technical Reference

Share API

Create and manage shareable content from your installation.

Overview

The Share API enables creating temporary or permanent shareable links to installation content. Shares can include text, images, or interactive components with optional expiration.

Base endpoint

POST /api/v1/share

Create share

Creates a new shareable content item and returns a unique URL.

Request

 POST /api/v1/share
Content-Type: application/json
Authorization: Bearer <token>

{
  "content": {
    "type": "text",
    "body": "Content to share"
  },
  "options": {
    "expires": "2024-12-31T23:59:59Z",
    "password": "optional-password",
    "maxViews": 100
  }
} 

Parameters

Parameter	Type	Required	Description
`content.type`	string	Yes	Content type: `text`, `image`, `interactive`
`content.body`	string	Yes	Content to share (text, URL, or JSON)
`options.expires`	string	No	ISO 8601 timestamp for expiration
`options.password`	string	No	Optional password protection
`options.maxViews`	number	No	Maximum view count before expiration

Response (201 Created)

 {
  "success": true,
  "data": {
    "id": "sh_abc123xyz",
    "url": "https://your-domain.com/s/abc123xyz",
    "shortUrl": "https://your-domain.com/s/abc",
    "created": "2024-01-16T10:00:00Z",
    "expires": "2024-12-31T23:59:59Z",
    "viewCount": 0,
    "maxViews": 100
  }
} 

Retrieve share

Retrieves shared content by ID. Increments view count.

Request

 GET /api/v1/share/:id
Authorization: Bearer <token>  # Optional, required if password-protected 

Path parameters

Parameter	Type	Description
`id`	string	Share ID (e.g., `abc123xyz`)

Response (200 OK)

 {
  "success": true,
  "data": {
    "id": "sh_abc123xyz",
    "content": {
      "type": "text",
      "body": "Content to share"
    },
    "created": "2024-01-16T10:00:00Z",
    "expires": "2024-12-31T23:59:59Z",
    "viewCount": 1,
    "maxViews": 100,
    "remainingViews": 99
  }
} 

Error response (404 Not Found)

 {
  "success": false,
  "error": {
    "code": "SHARE_NOT_FOUND",
    "message": "Share does not exist or has expired"
  }
} 

Update share

Updates an existing share's options. Content cannot be modified after creation.

Request

 PATCH /api/v1/share/:id
Content-Type: application/json
Authorization: Bearer <token>

{
  "options": {
    "expires": "2025-01-16T10:00:00Z",
    "maxViews": 200
  }
} 

Updatable fields

• options.expires - Can be extended but not shortened past current time
• options.maxViews - Can be increased but not decreased
• options.password - Can be set, changed, or removed

Response (200 OK)

 {
  "success": true,
  "data": {
    "id": "sh_abc123xyz",
    "updated": "2024-01-16T11:00:00Z",
    "expires": "2025-01-16T10:00:00Z",
    "maxViews": 200
  }
} 

Delete share

Permanently deletes a share. Shared URL becomes immediately inaccessible.

Request

 DELETE /api/v1/share/:id
Authorization: Bearer <token> 

Response (200 OK)

 {
  "success": true,
  "data": {
    "id": "sh_abc123xyz",
    "deleted": "2024-01-16T12:00:00Z"
  }
} 

List shares

Retrieves all shares created by the authenticated user.

Request

 GET /api/v1/shares
Authorization: Bearer <token>

# Query parameters
?limit=50&offset=0&status=active 

Query parameters

Parameter	Type	Default	Description
`limit`	number	50	Maximum results per page
`offset`	number	0	Results to skip (pagination)
`status`	string	all	Filter: `active`, `expired`, `all`

Response (200 OK)

 {
  "success": true,
  "data": {
    "shares": [
      {
        "id": "sh_abc123xyz",
        "url": "https://your-domain.com/s/abc123xyz",
        "created": "2024-01-16T10:00:00Z",
        "expires": "2024-12-31T23:59:59Z",
        "viewCount": 42,
        "maxViews": 100,
        "status": "active"
      }
    ],
    "pagination": {
      "total": 156,
      "limit": 50,
      "offset": 0,
      "hasMore": true
    }
  }
} 

Content types

Different content types support different body formats and rendering.

Text content

 {
  "content": {
    "type": "text",
    "body": "Plain text or markdown content"
  }
} 

Image content

 {
  "content": {
    "type": "image",
    "body": "https://your-domain.com/images/example.jpg"
  }
} 

Interactive content

 {
  "content": {
    "type": "interactive",
    "body": {
      "component": "HandDrawnEmphasis",
      "props": {
        "text": "Shared interactive element",
        "variant": "underline"
      }
    }
  }
} 

Rate limits

Share API has specific rate limits to prevent abuse.

Endpoint	Limit	Window
Create share	30 requests	per minute
Retrieve share	300 requests	per minute
Update/Delete share	60 requests	per minute
List shares	60 requests	per minute

Code examples

Complete examples for common Share API use cases.

Create and share text

 createShare.js 
 async function createShare(content, options = {}) {
  const response = await fetch('/api/v1/share', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_TOKEN}`
    },
    body: JSON.stringify({
      content: {
        type: 'text',
        body: content
      },
      options
    })
  });

  const result = await response.json();

  if (result.success) {
    console.log('Share created:', result.data.url);
    return result.data;
  } else {
    console.error('Error:', result.error);
  }
}

// Usage
const share = await createShare(
  'Check out this amazing installation!',
  { expires: '2024-12-31T23:59:59Z', maxViews: 100 }
); 

Retrieve and display share

 displayShare.js 
 async function displayShare(shareId) {
  const response = await fetch(`/api/v1/share/${shareId}`);
  const result = await response.json();

  if (result.success) {
    const { content, viewCount, remainingViews } = result.data;

    console.log('Content:', content.body);
    console.log(`Views: ${viewCount} (remaining: ${remainingViews})`);

    return result.data;
  } else {
    console.error('Share not found or expired');
  }
}

// Usage
const share = await displayShare('abc123xyz'); 