# ZoomHub API reference: Assets

Part of the [ZoomHub API reference](https://zoomhub.net/docs/api.md), whose index covers authentication, errors and the other resources.

> **Beta:** The v2 API is in beta: endpoints, attributes and error codes may still change before it is final. Questions or feedback: [daniel@zoomhub.net](mailto:daniel@zoomhub.net).

Base URL: `https://api.zoomhub.net`. Send your API key as `Authorization: Bearer <key>`; see [Authentication](https://zoomhub.net/docs/api.md#authentication).

## Assets

An asset is a single zoomable image. Create one from an image or a PDF on the web by its URL, or from a file on your computer through an [upload](https://zoomhub.net/docs/api/uploads.md#uploads). ZoomHub turns it into tiles you can zoom into, with a page to share and a script to embed. A PDF becomes a [collection](https://zoomhub.net/docs/api/collections.md#collections) of its pages once it is processed.

Processing takes from seconds to minutes. Poll [Retrieve an asset](https://zoomhub.net/docs/api/assets.md#assets-retrieve) until its `status` is `succeeded` or `failed`, waiting longer between attempts as you go.

### The asset object

A zoomable image, its settings, and how far processing has come.

**Attributes**

- `object` (string): Always `asset`.
- `id` (string): The asset’s ID, which collections and viewers name it by.
- `title` (string, nullable): At most 250 characters, single line; surrounding whitespace is trimmed.
- `caption` (string, nullable): At most 250 characters, single line; surrounding whitespace is trimmed.
- `description` (string, nullable): At most 10000 characters, line breaks allowed; surrounding whitespace is trimmed.
- `reference_id` (string, nullable): The owner’s own identifier for the image, such as a catalog or accession number: unique among the owner’s assets. At most 100 characters, single line; surrounding whitespace is trimmed.
- `visibility` (enum): Who may view the asset.
  - `public`: Anyone may view it, and it may be listed on its owner’s profile.
  - `unlisted`: Anyone with its link may view it; it is listed nowhere.
  - `protected`: Viewing it needs its password, or its owner’s key.
- `status` (enum): How processing went. `succeeded` and `failed` are final.
  - `unverified`: Submitted on ZoomHub’s site with an email address, and waiting for the link ZoomHub emailed to be followed. Assets created with a key skip this.
  - `queued`: Waiting to be processed.
  - `processing`: Being turned into tiles.
  - `succeeded`: Done: `kind` describes the tiles.
  - `failed`: Processing failed, and the asset has no tiles. Delete it and create it again to retry.
- `progress` (number): How far processing has come, from `0` to `1`.
- `source` (object, nullable): Where the image came from, or `null` for a few images from Zoom.it’s time, whose source isn’t known.
  - `type` (enum): The kind of source, which is also the key its details are under.
    - `url`: An image or PDF fetched from the web; its details are under `url`.
    - `upload`: A file uploaded through an upload. `upload` is an empty object: an upload’s file isn’t exposed.
  - `url` (object, optional): Present when `type` is `url`.
    - `original_url` (string): The URL the asset was created from.
  - `upload` (object, optional): Present, and empty, when `type` is `upload`.
- `kind` (object): What kind of asset it is, known once it is processed.
  - `type` (enum): What kind of asset it is, which is also the key its details are under.
    - `unknown`: Not processed yet, or processing failed.
    - `image`: A zoomable image; its tiles are under `image`.
  - `image` (object, optional): Present when `type` is `image`.
    - `dzi` (object): The Deep Zoom Image to view.
      - `url` (string): The DZI manifest’s URL. Read the tiles through it, but don’t store it: it changes when the asset’s protection does.
      - `width` (integer): The image’s width in pixels.
      - `height` (integer): The image’s height in pixels.
      - `tile_size` (integer): The edge of a tile in pixels, overlap excluded.
      - `tile_overlap` (integer): How many pixels each tile overlaps its neighbors.
      - `tile_format` (enum): The tiles’ image format, which is also their file extension.
        - `jpeg`: JPEG tiles.
        - `jpg`: JPEG tiles, named with the older extension.
        - `png`: PNG tiles.
        - `webp`: WebP tiles.
- `links` (object): Where the asset lives.
  - `self` (string): This asset in the API.
  - `share` (string): The asset’s page on ZoomHub.
  - `embed` (string): A script that embeds a viewer for the image where its `<script>` tag is.
  - `collection` (string, nullable): The collection a PDF’s pages were split into, in the API, or `null` for anything else.
- `created_at` (string): When the asset was created, in RFC 3339 UTC.

**Example 1**

```json
{
  "caption": null,
  "created_at": "2026-09-30T00:00:00Z",
  "description": null,
  "id": "smpAsset1",
  "kind": {
    "image": {
      "dzi": {
        "height": 3072,
        "tile_format": "jpeg",
        "tile_overlap": 1,
        "tile_size": 254,
        "url": "https://cache.zoomhub.net/content/smpAsset1.dzi",
        "width": 4096
      }
    },
    "type": "image"
  },
  "links": {
    "collection": null,
    "embed": "https://zoomhub.net/a/smpAsset1.js",
    "self": "https://api.zoomhub.net/v2/assets/smpAsset1",
    "share": "https://zoomhub.net/a/smpAsset1"
  },
  "object": "asset",
  "progress": 1,
  "reference_id": null,
  "source": {
    "type": "url",
    "url": {
      "original_url": "https://example.com/photo.jpg"
    }
  },
  "status": "succeeded",
  "title": "Sample photo",
  "visibility": "unlisted"
}
```

**Example 2**

```json
{
  "caption": null,
  "created_at": "2026-09-30T00:00:00Z",
  "description": null,
  "id": "smpAsset1",
  "kind": {
    "type": "unknown"
  },
  "links": {
    "collection": null,
    "embed": "https://zoomhub.net/a/smpAsset1.js",
    "self": "https://api.zoomhub.net/v2/assets/smpAsset1",
    "share": "https://zoomhub.net/a/smpAsset1"
  },
  "object": "asset",
  "progress": 0.5,
  "reference_id": null,
  "source": {
    "type": "upload",
    "upload": {}
  },
  "status": "processing",
  "title": "Sample photo",
  "visibility": "unlisted"
}
```

### Create an asset — `POST /v2/assets`

**Authentication:** API key. Send an API key.

Creates an asset from an image or a PDF on the web, and starts processing it.

The asset is yours and starts processing at once. A file that isn’t on the web goes through an [upload](https://zoomhub.net/docs/api/uploads.md#uploads) instead.

Creating is safe to repeat: the URL of one of your assets answers with that asset as it is, and the settings you sent are ignored. A URL someone else submitted is refused, and the answer names no asset. Deleting an asset frees its URL to be submitted again.

Protected takes a password, so `visibility` can’t be `protected` here: create the asset, then protect it with [Update an asset](https://zoomhub.net/docs/api/assets.md#assets-update).

**Body parameters**

- `source` (object, required): Where the image comes from.
  - `type` (enum, required): Always `url`: files come in through uploads.
    - `url`: An image or PDF on the web.
  - `url` (object, required): Where to fetch it.
    - `original_url` (string, required): The image’s or PDF’s URL, starting with `http://` or `https://`.
- `title` (string, optional): At most 250 characters, single line; surrounding whitespace is trimmed.
- `caption` (string, optional): At most 250 characters, single line; surrounding whitespace is trimmed.
- `description` (string, optional): At most 10000 characters, line breaks allowed; surrounding whitespace is trimmed.
- `reference_id` (string, optional): Your own identifier for the image, such as a catalog number, unique among your assets. Needs a plan that includes reference IDs. At most 100 characters, single line; surrounding whitespace is trimmed.
- `visibility` (enum, optional): Who may view the asset. To protect it with a password, update it once it is created.
  - `public`: Anyone may view it, and it may be listed on its owner’s profile.
  - `unlisted`: Anyone with its link may view it; it is listed nowhere. The default.

**Responses**

- `201 Created`: The new asset object, `queued`. Its `links.self` is also in the `Location` header.
- `200 OK`: The URL is one of your assets: that asset object, as it is.
- `400 Bad Request`, error code `bad_request`: The body isn’t JSON, misses `source`, has a key the endpoint doesn’t know, or breaks a limit; or `visibility` is `protected`. The detail says which.
- `400 Bad Request`, error code `invalid_url`: The `original_url` isn’t a URL ZoomHub can fetch, or points into ZoomHub’s own uploads: upload the file instead.
- `401 Unauthorized`, error code `not_authenticated`: No `Authorization` header.
- `401 Unauthorized`, error code `invalid_api_key`: The key is unknown or revoked, or the header isn’t a `Bearer` key.
- `403 Forbidden`, error code `plan_required`: The key is valid, but its account’s plan doesn’t include the API.
- `403 Forbidden`, error code `forbidden`: The account’s email address may not submit content.
- `403 Forbidden`, error code `subscription_required`: The account’s plan doesn’t include reference IDs.
- `409 Conflict`, error code `url_already_exists`: Someone else already submitted this URL. The answer doesn’t say who, or which asset.
- `409 Conflict`, error code `reference_id_taken`: Another of the owner’s assets already uses this `reference_id`.
- `429 Too Many Requests`, error code `upload_limit_reached`: The account has reached its upload limit.
- `503 Service Unavailable`, error code `uploads_disabled`: ZoomHub isn’t accepting new content right now. Retry later.

**Request**

```bash
curl "https://api.zoomhub.net/v2/assets" \
  --header "Authorization: Bearer $ZOOMHUB_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "source": {
      "type": "url",
      "url": {
        "original_url": "https://example.com/photo.jpg"
      }
    },
    "title": "Sample photo"
  }'
```

**Response** `201 Created`

```json
{
  "caption": null,
  "created_at": "2026-09-30T00:00:00Z",
  "description": null,
  "id": "smpAsset1",
  "kind": {
    "type": "unknown"
  },
  "links": {
    "collection": null,
    "embed": "https://zoomhub.net/a/smpAsset1.js",
    "self": "https://api.zoomhub.net/v2/assets/smpAsset1",
    "share": "https://zoomhub.net/a/smpAsset1"
  },
  "object": "asset",
  "progress": 0,
  "reference_id": null,
  "source": {
    "type": "url",
    "url": {
      "original_url": "https://example.com/photo.jpg"
    }
  },
  "status": "queued",
  "title": "Sample photo",
  "visibility": "unlisted"
}
```

**Response** `200 OK`

```json
{
  "caption": null,
  "created_at": "2026-09-30T00:00:00Z",
  "description": null,
  "id": "smpAsset1",
  "kind": {
    "image": {
      "dzi": {
        "height": 3072,
        "tile_format": "jpeg",
        "tile_overlap": 1,
        "tile_size": 254,
        "url": "https://cache.zoomhub.net/content/smpAsset1.dzi",
        "width": 4096
      }
    },
    "type": "image"
  },
  "links": {
    "collection": null,
    "embed": "https://zoomhub.net/a/smpAsset1.js",
    "self": "https://api.zoomhub.net/v2/assets/smpAsset1",
    "share": "https://zoomhub.net/a/smpAsset1"
  },
  "object": "asset",
  "progress": 1,
  "reference_id": null,
  "source": {
    "type": "url",
    "url": {
      "original_url": "https://example.com/photo.jpg"
    }
  },
  "status": "succeeded",
  "title": "Sample photo",
  "visibility": "unlisted"
}
```

### Retrieve an asset — `GET /v2/assets/{id}`

**Authentication:** API key optional. Works without a key; a key opens your own Protected items.

Returns the asset with the given ID.

Anyone may read an asset that isn’t Protected. Send your key to read your own Protected assets: the answer then carries `Cache-Control: no-store, private`. Poll it until `status` is `succeeded` or `failed`.

> **Note:** Reading what isn’t Protected needs no key: leave out the `Authorization` header. A key that fails to verify counts as no key: what’s public answers as usual, and what’s Protected answers `403` `forbidden`.

**Path parameters**

- `id` (string, required): The asset’s ID.

**Responses**

- `200 OK`: The asset object.
- `403 Forbidden`, error code `forbidden`: The asset is Protected and the key’s account may not view it. The answer is the same whatever the reason, so it doesn’t reveal which rule refused.
- `404 Not Found`, error code `content_not_found`: No asset has this ID, or it was deleted.

**Request**

```bash
curl "https://api.zoomhub.net/v2/assets/smpAsset1"
```

**Response** `200 OK`

```json
{
  "caption": null,
  "created_at": "2026-09-30T00:00:00Z",
  "description": null,
  "id": "smpAsset1",
  "kind": {
    "image": {
      "dzi": {
        "height": 3072,
        "tile_format": "jpeg",
        "tile_overlap": 1,
        "tile_size": 254,
        "url": "https://cache.zoomhub.net/content/smpAsset1.dzi",
        "width": 4096
      }
    },
    "type": "image"
  },
  "links": {
    "collection": null,
    "embed": "https://zoomhub.net/a/smpAsset1.js",
    "self": "https://api.zoomhub.net/v2/assets/smpAsset1",
    "share": "https://zoomhub.net/a/smpAsset1"
  },
  "object": "asset",
  "progress": 1,
  "reference_id": null,
  "source": {
    "type": "url",
    "url": {
      "original_url": "https://example.com/photo.jpg"
    }
  },
  "status": "succeeded",
  "title": "Sample photo",
  "visibility": "unlisted"
}
```

### Update an asset — `PATCH /v2/assets/{id}`

**Authentication:** API key. Send an API key.

Changes an asset’s title, caption, description, reference ID, visibility or password.

Only the asset’s owner, or an admin, may update it, and the owner’s plan decides what may be set. Send only what changes: a key you leave out keeps its value, and `null` clears it.

To protect an asset, set a `password`. To open it again, set `password` to `null`, which makes it Unlisted, or set `visibility` to the tier you want. A PDF’s pages follow their document: change the document’s protection instead.

**Path parameters**

- `id` (string, required): The asset’s ID.

**Body parameters**

- `title` (string, optional, nullable): At most 250 characters, single line; surrounding whitespace is trimmed.
- `caption` (string, optional, nullable): At most 250 characters, single line; surrounding whitespace is trimmed.
- `description` (string, optional, nullable): At most 10000 characters, line breaks allowed; surrounding whitespace is trimmed.
- `reference_id` (string, optional, nullable): Your own identifier for the image, such as a catalog number, unique among your assets. Needs a plan that includes reference IDs. At most 100 characters, single line; surrounding whitespace is trimmed.
- `visibility` (enum, optional): Who may view the asset. It can’t be `null`.
  - `public`: Anyone may view it, and it may be listed on its owner’s profile.
  - `unlisted`: Anyone with its link may view it; it is listed nowhere.
  - `protected`: Viewing it needs its password, or its owner’s key. Needs a password, sent now or set before.
- `password` (string, optional, nullable): The password that opens a Protected asset: 8 to 256 characters. Setting one protects the asset, so it can’t come with `visibility` `public` or `unlisted`. `null` removes it.

**Responses**

- `200 OK`: The updated asset object.
- `400 Bad Request`, error code `bad_request`: The body isn’t JSON, has a key the endpoint doesn’t know, or breaks a limit; or the protection change isn’t allowed, such as protecting a PDF’s page or an asset without an owner. The detail says which.
- `401 Unauthorized`, error code `not_authenticated`: No `Authorization` header.
- `401 Unauthorized`, error code `invalid_api_key`: The key is unknown or revoked, or the header isn’t a `Bearer` key.
- `403 Forbidden`, error code `plan_required`: The key is valid, but its account’s plan doesn’t include the API.
- `403 Forbidden`, error code `forbidden`: The key’s account neither owns the asset nor is an admin.
- `403 Forbidden`, error code `subscription_required`: The owner’s plan doesn’t include password protection or reference IDs.
- `404 Not Found`, error code `content_not_found`: No asset has this ID, or it was deleted.
- `409 Conflict`, error code `reference_id_taken`: Another of the owner’s assets already uses this `reference_id`.
- `409 Conflict`, error code `in_foreign_collection`: The asset is a member of a collection someone else owns, so it can’t be protected. Ask them to remove it first.
- `503 Service Unavailable`, error code `protection_unavailable`: Protection can’t be changed right now; nothing was changed.
- `503 Service Unavailable`, error code `protection_pending`: The asset is Protected, but the CDN wasn’t updated yet; ZoomHub finishes within a minute, and retrying is safe.

**Request**

```bash
curl "https://api.zoomhub.net/v2/assets/smpAsset1" \
  --request PATCH \
  --header "Authorization: Bearer $ZOOMHUB_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "caption": null,
    "reference_id": "SMP-0447",
    "title": "Sample photo"
  }'
```

**Response** `200 OK`

```json
{
  "caption": null,
  "created_at": "2026-09-30T00:00:00Z",
  "description": null,
  "id": "smpAsset1",
  "kind": {
    "image": {
      "dzi": {
        "height": 3072,
        "tile_format": "jpeg",
        "tile_overlap": 1,
        "tile_size": 254,
        "url": "https://cache.zoomhub.net/content/smpAsset1.dzi",
        "width": 4096
      }
    },
    "type": "image"
  },
  "links": {
    "collection": null,
    "embed": "https://zoomhub.net/a/smpAsset1.js",
    "self": "https://api.zoomhub.net/v2/assets/smpAsset1",
    "share": "https://zoomhub.net/a/smpAsset1"
  },
  "object": "asset",
  "progress": 1,
  "reference_id": null,
  "source": {
    "type": "url",
    "url": {
      "original_url": "https://example.com/photo.jpg"
    }
  },
  "status": "succeeded",
  "title": "Sample photo",
  "visibility": "unlisted"
}
```

### Delete an asset — `DELETE /v2/assets/{id}`

**Authentication:** API key. Send an API key.

Deletes an asset, its tiles, and its membership in every collection.

Only the asset’s owner, or an admin, may delete it. Its page, share link and embeds stop working, and its URL is free to be submitted again. Deleting a PDF deletes its pages and the collection made of them too.

> **Warning:** A deletion can’t be undone through the API.

**Path parameters**

- `id` (string, required): The asset’s ID.

**Responses**

- `204 No Content`: Deleted.
- `401 Unauthorized`, error code `not_authenticated`: No `Authorization` header.
- `401 Unauthorized`, error code `invalid_api_key`: The key is unknown or revoked, or the header isn’t a `Bearer` key.
- `403 Forbidden`, error code `plan_required`: The key is valid, but its account’s plan doesn’t include the API.
- `403 Forbidden`, error code `forbidden`: The key’s account neither owns the asset nor is an admin.
- `404 Not Found`, error code `content_not_found`: No asset has this ID, or it was deleted.

**Request**

```bash
curl "https://api.zoomhub.net/v2/assets/smpAsset1" \
  --request DELETE \
  --header "Authorization: Bearer $ZOOMHUB_API_KEY"
```