Mipmaps and Assets

The mipmaps and assets endpoints provide direct access to canvas content files by their content hash. Mipmaps are pre-generated, progressively downscaled versions of image and PDF assets that enable efficient rendering at different zoom levels. The assets endpoint provides access to the original, full-resolution file.

These endpoints use a content-addressable scheme: you access files by their hash rather than by widget ID or canvas ID. The hash is available on image and PDF widgets via the hash field (see the widgets endpoint).

When you would use this API:

Building a custom canvas viewer that needs to render images at different zoom levels
Downloading thumbnail or preview versions of canvas images without fetching the full file
Implementing efficient WebGL-based rendering of canvas content
Downloading the original asset file by its content hash
Retrieving individual pages of a multi-page PDF

Key Concepts

Mipmap levels:

Level 0 is the original resolution
Each higher level halves the dimensions (level 1 = half size, level 2 = quarter size, etc.)
The maximum level is where both width and height are at most 128 pixels and at least 2 pixels
Mipmap levels are generated on demand and cached by the server

File format:

All mipmap images are returned in WebP format, regardless of the original file type

Caching:

All mipmap and asset responses include Cache-Control: private, max-age=157680000, immutable. Content is immutable once generated -- the hash changes if the content changes. Clients should cache aggressively.

Multi-page assets (PDFs):

Use the page query parameter to access individual pages
Page numbering starts at 0 (first page is page=0)

Where to find the asset hash:

On Image widgets: use the hash field
On PDF widgets: use the hash field
On canvas backgrounds: use the image.hash field from the canvas background endpoint

Authentication

Both the Private-Token and canvas-id headers are required. The canvas ID identifies which canvas the asset belongs to, and the token authenticates the user's access to that canvas.

Private-Token: YOUR_TOKEN (required)
canvas-id: <canvas-uuid> (required)

Note: The canvasId query parameter is NOT a substitute for the canvas-id header. Requests without the canvas-id header will return 404 regardless of query parameters.

Get Mipmap Info

Returns metadata about the available mipmap levels for an asset, including the original resolution, the maximum mipmap level, and the page count.

Method: GET
URL: /api/v1/mipmaps/:hash
Authentication: See above
Streaming: Not supported

Path parameters:

hash (string, required) -- The content hash of the asset (from the widget's hash field)

Query parameters:

page (integer, optional) -- Page number for multi-page assets (default: 0)

Request headers:

Private-Token (string, required) -- API access token
canvas-id (string, required) -- UUID of the canvas that contains this asset

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  -H "canvas-id: 3ad9ece4-28be-4e19-9f9a-1a01a4dbae28" \
  https://canvus.example.com/api/v1/mipmaps/cbcb439a796b

Example response (200 OK):

{
  "resolution": {
    "width": 4096,
    "height": 3072
  },
  "max_level": 5,
  "pages": 1
}

Response fields:

resolution (object) -- Original image dimensions as width and height in pixels
max_level (number) -- The highest mipmap level available. Level 0 is original size, and each subsequent level halves the dimensions.
pages (number) -- Number of pages in the asset. Always 1 for images; may be higher for PDFs.

Example request for a PDF page:

curl -H "Private-Token: YOUR_TOKEN" \
  -H "canvas-id: 3ad9ece4-28be-4e19-9f9a-1a01a4dbae28" \
  "https://canvus.example.com/api/v1/mipmaps/a1b2c3d4e5f6?page=2"

Download a Mipmap Level

Downloads the image data for a specific mipmap level. The response is a binary WebP image file.

Method: GET
URL: /api/v1/mipmaps/:hash/:level
Authentication: See above
Streaming: Not supported

Path parameters:

hash (string, required) -- The content hash of the asset
level (integer, required) -- The mipmap level to download (0 = original size)

Query parameters:

page (integer, optional) -- Page number for multi-page assets (default: 0)

Request headers:

Private-Token (string, required) -- API access token
canvas-id (string, required) -- UUID of the canvas that contains this asset

Example request -- download the smallest mipmap (thumbnail):

curl -H "Private-Token: YOUR_TOKEN" \
  -H "canvas-id: 3ad9ece4-28be-4e19-9f9a-1a01a4dbae28" \
  -o thumbnail.webp \
  https://canvus.example.com/api/v1/mipmaps/cbcb439a796b/5

Example request -- download half-resolution version:

curl -H "Private-Token: YOUR_TOKEN" \
  -H "canvas-id: 3ad9ece4-28be-4e19-9f9a-1a01a4dbae28" \
  -o half-res.webp \
  https://canvus.example.com/api/v1/mipmaps/cbcb439a796b/1

Response:

Binary WebP image data. The Content-Disposition header indicates the filename. The Cache-Control header is set to private, max-age=157680000, immutable.

Download an Asset by Hash

Downloads the original, full-resolution asset file by its content hash. Unlike mipmap downloads, this returns the file in its original format (JPEG, PNG, PDF, MP4, etc.).

Method: GET
URL: /api/v1/assets/:hash
Authentication: See above
Streaming: Not supported

Path parameters:

hash (string, required) -- The content hash of the asset

Request headers:

Private-Token (string, required) -- API access token
canvas-id (string, required) -- UUID of the canvas that contains this asset

Example request:

curl -H "Private-Token: YOUR_TOKEN" \
  -H "canvas-id: 3ad9ece4-28be-4e19-9f9a-1a01a4dbae28" \
  -o original-photo.jpg \
  https://canvus.example.com/api/v1/assets/cbcb439a796b

Response:

Binary file data in the original format. The Content-Disposition header provides the filename. The Cache-Control header is set to private, max-age=157680000, immutable.

Error Responses

400 Bad Request -- Mipmap level is outside the valid range (less than 0 or greater than max_level)
401 Unauthorized -- Missing or invalid authentication
403 Forbidden -- User is blocked or does not have access
404 Not Found -- No asset exists with the given hash, or the user does not have access
501 Not Implemented -- The asset type does not support mipmap generation

All errors return a JSON body:

{
  "msg": "error description"
}

Typical Workflow

List widgets on a canvas using GET /api/v1/canvases/:canvas_id/widgets
Find an image or PDF widget in the response and note its hash value
Call GET /api/v1/mipmaps/:hash to get the mipmap info (resolution, max level, page count)
Choose the appropriate mipmap level based on your display size
Download the mipmap level with GET /api/v1/mipmaps/:hash/:level
Or download the original file with GET /api/v1/assets/:hash