Assets API

The Assets API allows you to list, create, and manage digital assets programmatically.

List Assets

Retrieve a paginated list of published digital assets.

Endpoint: GET /api/v1/assets

Required Scope: read:assets

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	20	Results per page (max: 100)
`asset_type`	string	-	Filter by type: pdf, document, image, video, audio, link, collection, git
`search`	string	-	Search in title and description
`sort`	string	created_at	Sort by: created_at, title, updated_at
`order`	string	desc	Sort order: asc, desc

Example Request

cURLbash

curl -X GET "https://yourdomain.com/api/v1/assets?asset_type=pdf&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScriptjavascript

const response = await fetch('https://yourdomain.com/api/v1/assets?asset_type=pdf&per_page=10', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();

Pythonpython

import requests

response = requests.get(
    'https://yourdomain.com/api/v1/assets',
    params={'asset_type': 'pdf', 'per_page': 10},
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()

Example Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Product Guide 2024",
      "slug": "product-guide-2024",
      "description": "Comprehensive guide to our products",
      "asset_type": "pdf",
      "file_path": "/uploads/assets/product-guide.pdf",
      "file_size": 2048576,
      "mime_type": "application/pdf",
      "thumbnail_path": "/uploads/thumbnails/product-guide.jpg",
      "page_count": 24,
      "download_count": 156,
      "is_public": true,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:22:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 45,
    "total_pages": 5
  }
}

Get Single Asset

Retrieve details of a specific asset by ID.

Endpoint: GET /api/v1/assets/{asset_id}

Required Scope: read:assets

cURLbash

curl -X GET "https://yourdomain.com/api/v1/assets/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Asset

Create a new digital asset.

Endpoint: POST /api/v1/assets

Required Scope: write:assets

Request Body

Field	Type	Required	Description
`title`	string	Yes	Asset title (max 500 chars)
`description`	string	No	Asset description
`asset_type`	string	Yes	One of: pdf, document, image, video, external_video, audio, link, collection, git
`external_url`	string	Conditional	Required for external_video and link types
`is_public`	boolean	No	Make asset publicly accessible (default: false)

File Upload

For file-based assets, you'll need to upload the file first using a separate endpoint (coming soon) or provide a file_path if the file is already on the server.

Example Request

cURLbash

curl -X POST "https://yourdomain.com/api/v1/assets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Product Demo",
    "description": "Video demonstration of our latest product",
    "asset_type": "external_video",
    "external_url": "https://youtube.com/watch?v=example",
    "is_public": true
  }'

JavaScriptjavascript

const response = await fetch('https://yourdomain.com/api/v1/assets', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'New Product Demo',
    description: 'Video demonstration of our latest product',
    asset_type: 'external_video',
    external_url: 'https://youtube.com/watch?v=example',
    is_public: true
  })
});
const asset = await response.json();

Pythonpython

import requests

response = requests.post(
    'https://yourdomain.com/api/v1/assets',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'title': 'New Product Demo',
        'description': 'Video demonstration of our latest product',
        'asset_type': 'external_video',
        'external_url': 'https://youtube.com/watch?v=example',
        'is_public': True
    }
)
asset = response.json()

Asset Types

PDF / Document

For PDF and document assets, the API automatically extracts metadata:

{
  "asset_type": "pdf",
  "file_size": 2048576,
  "mime_type": "application/pdf",
  "page_count": 24,
  "word_count": 5200
}

Image

Image assets include dimensions:

{
  "asset_type": "image",
  "mime_type": "image/jpeg",
  "width": 1920,
  "height": 1080,
  "file_size": 524288
}

External Video

For YouTube, Vimeo, or other external videos:

{
  "asset_type": "external_video",
  "external_url": "https://youtube.com/watch?v=example",
  "video_embed": "https://youtube.com/embed/example"
}

Error Responses

400 Bad Request

{
  "error": "Validation failed",
  "message": "Title is required",
  "field": "title"
}

403 Forbidden

{
  "error": "Insufficient permissions",
  "message": "API key does not have write:assets scope"
}

Next Steps

• Learn about Libraries API
• View Code Examples