Libraries API
The Libraries API allows you to retrieve and display digital library collections on external websites. This is the primary endpoint for embedding your library content on other platforms.
Perfect for External Websites
This API is specifically designed for displaying library content on your other websites. All responses include complete data for rendering library pages, including sections, assets, thumbnails, and display settings.
List Libraries
Retrieve a paginated list of all your published libraries. Use this to display a library index or selection page.
GET /api/v1/librariesread:librariesQuery Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number for pagination |
limit | integer | 20 | Items per page (max: 100) |
workspace_id | string | null | Filter by workspace ID |
Response Format
| Field | Type | Description |
|---|---|---|
| Library Object Fields | ||
id | string (UUID) | Unique library identifier |
title | string | Library title/name |
slug | string | URL-friendly slug for routing |
description | string | null | Library description text |
cover_image_path | string | null | URL path to cover image |
published_at | string (ISO 8601) | Publication timestamp |
is_paid | boolean | Whether library requires payment |
price | number | null | Price amount (if paid library) |
currency | string | Currency code (e.g., "USD", "EUR") |
asset_count | integer | Total number of assets in library |
view_count | integer | Number of times library has been viewed |
created_at | string (ISO 8601) | Creation timestamp |
workspace_id | string | null | Associated workspace ID (if any) |
| Pagination Object Fields | ||
page | integer | Current page number |
limit | integer | Items per page |
total | integer | Total number of libraries |
total_pages | integer | Total number of pages |
has_next | boolean | Whether there is a next page |
has_prev | boolean | Whether there is a previous page |
curl -X GET "https://yourdomain.com/api/v1/libraries?page=1&limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"const response = await fetch('https://yourdomain.com/api/v1/libraries?page=1&limit=10', {
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const data = await response.json();
console.log(data);
// {
// "libraries": [
// {
// "id": "550e8400-e29b-41d4-a716-446655440000",
// "title": "Marketing Assets 2024",
// "slug": "marketing-assets-2024",
// "description": "Complete marketing materials for Q1 campaign",
// "cover_image_path": "/uploads/covers/marketing-2024.jpg",
// "published_at": "2024-01-15T10:30:00Z",
// "is_paid": false,
// "price": null,
// "currency": "USD",
// "asset_count": 24,
// "view_count": 156,
// "created_at": "2024-01-10T08:00:00Z",
// "workspace_id": null
// }
// ],
// "pagination": {
// "page": 1,
// "limit": 10,
// "total": 3,
// "total_pages": 1,
// "has_next": false,
// "has_prev": false
// }
// }Get Single Library (Detailed)
Retrieve complete details for a specific library including all sections and assets. This is the key endpoint for rendering library pages on external websites.
GET /api/v1/libraries/{library_id}read:librariesEssential for Library Pages
Use include_assets=true query parameter to get full asset details within sections. Without this parameter, you'll only receive asset counts per section.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
include_assets | boolean | false | Include full asset details in sections (highly recommended for display) |
Response Format
| Field | Type | Description |
|---|---|---|
| Root Library Fields | ||
id | string (UUID) | Unique library identifier |
title | string | Library title (display as page heading) |
slug | string | URL-friendly slug (use for routing) |
description | string | null | Library description (display below title) |
cover_image_path | string | null | Cover/hero image URL |
cover_overlay_color | string | null | Hex color for cover overlay (e.g., "#000000") |
cover_overlay_opacity | number | null | Overlay opacity (0.0 to 1.0) |
published_at | string (ISO 8601) | Publication date |
is_paid | boolean | Whether library requires payment |
price | number | null | Price amount (if paid) |
currency | string | Currency code (e.g., "USD", "EUR") |
show_asset_count | boolean | Whether to display asset count on page |
allow_individual_downloads | boolean | Show download buttons for each asset |
allow_bulk_download | boolean | Show "Download All" button |
view_count | integer | Total views |
created_at | string (ISO 8601) | Creation timestamp |
updated_at | string (ISO 8601) | Last update timestamp |
workspace_id | string | null | Associated workspace ID |
Section Object Fields (in sections array) | ||
id | string (UUID) | Section identifier |
title | string | Section heading |
description | string | null | Section description |
display_order | integer | Order for rendering sections |
collapsed_by_default | boolean | Whether section starts collapsed |
assets | array | undefined | Array of asset objects (only if include_assets=true) |
asset_count | integer | undefined | Number of assets (only if include_assets=false) |
Asset Object Fields (in sections[].assets or unsectioned_assets) | ||
id | string (UUID) | Asset identifier |
title | string | Asset title (may be customized per library) |
description | string | null | Asset description (may be customized) |
asset_type | string | Type: "pdf", "image", "video", "audio", "document" |
thumbnail_url | string | null | Thumbnail/preview image URL |
display_order | integer | Order within section |
curl -X GET "https://yourdomain.com/api/v1/libraries/550e8400-e29b-41d4-a716-446655440000?include_assets=true" \
-H "Authorization: Bearer YOUR_API_KEY"const libraryId = '550e8400-e29b-41d4-a716-446655440000';
const response = await fetch(
`https://yourdomain.com/api/v1/libraries/${libraryId}?include_assets=true`,
{ headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const library = await response.json();
console.log(library);
// {
// "id": "550e8400-e29b-41d4-a716-446655440000",
// "title": "Marketing Assets 2024",
// "slug": "marketing-assets-2024",
// "description": "Complete collection of marketing materials",
// "cover_image_path": "/uploads/covers/marketing-2024.jpg",
// "cover_overlay_color": "#000000",
// "cover_overlay_opacity": 0.4,
// "published_at": "2024-01-15T10:30:00Z",
// "is_paid": false,
// "price": null,
// "currency": "USD",
// "show_asset_count": true,
// "allow_individual_downloads": true,
// "allow_bulk_download": false,
// "view_count": 156,
// "created_at": "2024-01-10T08:00:00Z",
// "updated_at": "2024-01-15T10:30:00Z",
// "workspace_id": null,
// "sections": [
// {
// "id": "660e8400-e29b-41d4-a716-446655440001",
// "title": "Brand Guidelines",
// "description": "Official brand assets and guidelines",
// "display_order": 1,
// "collapsed_by_default": false,
// "assets": [
// {
// "id": "770e8400-e29b-41d4-a716-446655440002",
// "title": "Logo Package 2024",
// "description": "Complete logo set in all formats",
// "asset_type": "pdf",
// "thumbnail_url": "/uploads/thumbnails/logo-package.jpg",
// "display_order": 1
// },
// {
// "id": "880e8400-e29b-41d4-a716-446655440003",
// "title": "Color Palette Guide",
// "description": "Brand colors and usage",
// "asset_type": "pdf",
// "thumbnail_url": "/uploads/thumbnails/colors.jpg",
// "display_order": 2
// }
// ]
// },
// {
// "id": "990e8400-e29b-41d4-a716-446655440004",
// "title": "Social Media Templates",
// "description": "Ready-to-use social templates",
// "display_order": 2,
// "collapsed_by_default": false,
// "assets": [
// {
// "id": "aa0e8400-e29b-41d4-a716-446655440005",
// "title": "Instagram Post Template",
// "description": "1080x1080 Photoshop template",
// "asset_type": "image",
// "thumbnail_url": "/uploads/thumbnails/ig-template.jpg",
// "display_order": 1
// }
// ]
// }
// ],
// "unsectioned_assets": []
// }Rendering a Library Page
Here's a complete example of fetching and rendering a library page on your external website:
import { useEffect, useState } from 'react';
export function LibraryPage({ slug }) {
const [library, setLibrary] = useState(null);
const [loading, setLoading] = useState(true);
useEffect(() => {
async function fetchLibrary() {
// First, get all libraries to find the one with matching slug
const listRes = await fetch('https://yourdomain.com/api/v1/libraries', {
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const { libraries } = await listRes.json();
const match = libraries.find(lib => lib.slug === slug);
if (!match) {
setLoading(false);
return;
}
// Get full library details with assets
const detailRes = await fetch(
`https://yourdomain.com/api/v1/libraries/${match.id}?include_assets=true`,
{ headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const data = await detailRes.json();
setLibrary(data);
setLoading(false);
}
fetchLibrary();
}, [slug]);
if (loading) return <div>Loading...</div>;
if (!library) return <div>Library not found</div>;
return (
<div>
{/* Hero Section */}
{library.cover_image_path && (
<div className="relative h-96">
<img src={library.cover_image_path} alt={library.title} />
{library.cover_overlay_color && (
<div
className="absolute inset-0"
style={{
backgroundColor: library.cover_overlay_color,
opacity: library.cover_overlay_opacity
}}
/>
)}
</div>
)}
{/* Header */}
<h1>{library.title}</h1>
{library.description && <p>{library.description}</p>}
{/* Show asset count if enabled */}
{library.show_asset_count && (
<p>Total Assets: {library.sections.reduce((sum, s) =>
sum + (s.assets?.length || 0), 0
)}</p>
)}
{/* Sections */}
{library.sections.map((section) => (
<section key={section.id}>
<h2>{section.title}</h2>
{section.description && <p>{section.description}</p>}
{/* Assets in section */}
<div className="grid grid-cols-3 gap-4">
{section.assets?.map((asset) => (
<div key={asset.id} className="asset-card">
{asset.thumbnail_url && (
<img src={asset.thumbnail_url} alt={asset.title} />
)}
<h3>{asset.title}</h3>
<p>{asset.description}</p>
<span className="badge">{asset.asset_type}</span>
{/* Show download button if allowed */}
{library.allow_individual_downloads && (
<a href={`/api/v1/assets/${asset.id}/download`}>
Download
</a>
)}
</div>
))}
</div>
</section>
))}
{/* Unsectioned assets */}
{library.unsectioned_assets?.length > 0 && (
<section>
<h2>Additional Resources</h2>
<div className="grid grid-cols-3 gap-4">
{library.unsectioned_assets.map((asset) => (
<div key={asset.id} className="asset-card">
{/* Same asset rendering as above */}
</div>
))}
</div>
</section>
)}
{/* Bulk download if enabled */}
{library.allow_bulk_download && (
<button>Download All Assets</button>
)}
</div>
);
}Common Use Cases for External Websites
Embedding Libraries on Your Marketing Site
Display your digital product libraries directly on your company website. The API provides all necessary data including cover images, sections, assets, and display settings.
Key fields: cover_image_path, cover_overlay_color/opacity, sections[], allow_individual_downloads
Creating Custom Library Portals
Build a dedicated portal or subdomain for your resource libraries using this API. Perfect for client-facing resource centers or member-only content areas.
Key fields: sections[].collapsed_by_default, is_paid, price, allow_bulk_download
White-Label Library Pages
Pull library data into your own branded interface on any website. Use the slug-based routing and complete asset metadata to create a seamless experience.
Key fields: slug, title, description, sections[].assets[]
Best Practices for Displaying Libraries
- Always use include_assets=true for display pages: This gives you complete asset details needed for rendering
- Respect display settings: Honor
show_asset_count,allow_individual_downloads, andallow_bulk_downloadflags - Sort by display_order: Both sections and assets have
display_orderfields - use them to maintain intended layout - Handle cover overlays properly: Combine
cover_overlay_colorandcover_overlay_opacityfor hero images - Cache responses: Library content doesn't change frequently - implement client-side caching
- Show appropriate pricing: Display
priceandcurrencyifis_paidis true
Next Steps
- • Review Assets API for downloading individual files
- • Learn about Lead Capture API for gating access
- • View Complete Code Examples