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.

Endpoint: GET /api/v1/libraries
Required Scope: read:libraries

Query Parameters

ParameterTypeDefaultDescription
pageinteger1Page number for pagination
limitinteger20Items per page (max: 100)
workspace_idstringnullFilter by workspace ID

Response Format

FieldTypeDescription
Library Object Fields
idstring (UUID)Unique library identifier
titlestringLibrary title/name
slugstringURL-friendly slug for routing
descriptionstring | nullLibrary description text
cover_image_pathstring | nullURL path to cover image
published_atstring (ISO 8601)Publication timestamp
is_paidbooleanWhether library requires payment
pricenumber | nullPrice amount (if paid library)
currencystringCurrency code (e.g., "USD", "EUR")
asset_countintegerTotal number of assets in library
view_countintegerNumber of times library has been viewed
created_atstring (ISO 8601)Creation timestamp
workspace_idstring | nullAssociated workspace ID (if any)
Pagination Object Fields
pageintegerCurrent page number
limitintegerItems per page
totalintegerTotal number of libraries
total_pagesintegerTotal number of pages
has_nextbooleanWhether there is a next page
has_prevbooleanWhether there is a previous page
cURLbash
curl -X GET "https://yourdomain.com/api/v1/libraries?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScriptjavascript
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.

Endpoint: GET /api/v1/libraries/{library_id}
Required Scope: read:libraries

Essential 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

ParameterTypeDefaultDescription
include_assetsbooleanfalseInclude full asset details in sections (highly recommended for display)

Response Format

FieldTypeDescription
Root Library Fields
idstring (UUID)Unique library identifier
titlestringLibrary title (display as page heading)
slugstringURL-friendly slug (use for routing)
descriptionstring | nullLibrary description (display below title)
cover_image_pathstring | nullCover/hero image URL
cover_overlay_colorstring | nullHex color for cover overlay (e.g., "#000000")
cover_overlay_opacitynumber | nullOverlay opacity (0.0 to 1.0)
published_atstring (ISO 8601)Publication date
is_paidbooleanWhether library requires payment
pricenumber | nullPrice amount (if paid)
currencystringCurrency code (e.g., "USD", "EUR")
show_asset_countbooleanWhether to display asset count on page
allow_individual_downloadsbooleanShow download buttons for each asset
allow_bulk_downloadbooleanShow "Download All" button
view_countintegerTotal views
created_atstring (ISO 8601)Creation timestamp
updated_atstring (ISO 8601)Last update timestamp
workspace_idstring | nullAssociated workspace ID
Section Object Fields (in sections array)
idstring (UUID)Section identifier
titlestringSection heading
descriptionstring | nullSection description
display_orderintegerOrder for rendering sections
collapsed_by_defaultbooleanWhether section starts collapsed
assetsarray | undefinedArray of asset objects (only if include_assets=true)
asset_countinteger | undefinedNumber of assets (only if include_assets=false)
Asset Object Fields (in sections[].assets or unsectioned_assets)
idstring (UUID)Asset identifier
titlestringAsset title (may be customized per library)
descriptionstring | nullAsset description (may be customized)
asset_typestringType: "pdf", "image", "video", "audio", "document"
thumbnail_urlstring | nullThumbnail/preview image URL
display_orderintegerOrder within section
cURL - Get Library with Full Asset Detailsbash
curl -X GET "https://yourdomain.com/api/v1/libraries/550e8400-e29b-41d4-a716-446655440000?include_assets=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScript - Full Response Examplejavascript
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:

React Component Examplejavascript
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

  1. Always use include_assets=true for display pages: This gives you complete asset details needed for rendering
  2. Respect display settings: Honor show_asset_count, allow_individual_downloads, and allow_bulk_download flags
  3. Sort by display_order: Both sections and assets have display_order fields - use them to maintain intended layout
  4. Handle cover overlays properly: Combine cover_overlay_color and cover_overlay_opacity for hero images
  5. Cache responses: Library content doesn't change frequently - implement client-side caching
  6. Show appropriate pricing: Display price and currency if is_paid is true

Next Steps