---
title: "Browse one page of your images and videos with short-lived links"
method: GET
path: "/v1/gallery/browse"
tags: ["Gallery"]
---

# Browse one page of your images and videos with short-lived links

`GET /v1/gallery/browse`

## Request

- Base URL: `https://contentmaschine.ai/api`
- URL: `https://contentmaschine.ai/api/v1/gallery/browse`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://contentmaschine.ai/api/oauth/authorize`, token URL `https://contentmaschine.ai/api/oauth/token`)

The paged, link-carrying form of `GET /v1/gallery`, built for viewers such as the MCP
`show_gallery` tool. This call is free: no credits are charged, no model is called and
no bytes are returned. Every item carries presigned URLs that expire after 15 minutes.

- `thumbnail_url` opens a small stored thumbnail (or, for a video, its poster) inline.
- `view_url` opens the original image, or plays the video, inline; `download_url` saves it.
- **Every URL is a credential for 15 minutes**: anyone holding it can read the file. Do
  not log it or pass it on.
- An item stored only on the server disk, or one that cannot be presigned right now, is
  still listed, with its link fields `null`, so page sizes and offsets stay stable.

The `category` is intersected with the containers your token can read: a token holding
only `images:read` never sees videos, whatever it asks for. A literal path, so it is never
read as `GET /v1/gallery/{uuid}`.

## Query parameters

- `category` 'images' | 'videos' | 'all'
- `limit` integer
- `offset` integer

## Response `200`

One page of items with 15-minute links.

- object
  - `success` boolean
  - `data` object
    - `items` object[]
      - `uuid` string, uuid
      - `kind` 'image' | 'video'
      - `file_name` string
      - `mime_type` string, nullable
      - `width` integer, nullable
      - `height` integer, nullable
      - `created_at` string, date-time, nullable
      - `title` string, nullable
      - `thumbnail_url` string, nullable: Presigned inline URL for a small version or video poster. A credential.
      - `view_url` string, nullable: Presigned inline URL for the original image or video. A credential.
      - `download_url` string, nullable: Presigned download URL for the original. A credential.
    - `pagination` object
      - `total` integer
      - `limit` integer
      - `offset` integer
      - `has_more` boolean
    - `category` 'images' | 'videos' | 'all'
    - `expires_at` string, date-time
    - `expires_in_seconds` integer
  - `timestamp` string, date-time

## Other responses

- `400`: Invalid `category`, `limit` or `offset`.
- `401`: Missing or invalid API key.
- `403`: The token holds neither images:read nor videos:read.
- `default`: Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.

---

[API](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api.md) · [All operations](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/revisions/28c74f46051c?raw)