---
title: "List your video, audio and image files"
method: GET
path: "/v1/files"
tags: ["Files"]
---

# List your video, audio and image files

`GET /v1/files`

## Request

- Base URL: `https://contentmaschine.ai/api`
- URL: `https://contentmaschine.ai/api/v1/files`
- 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`)

Newest first. Video and audio items carry `media` (duration, size, frame rate, codecs,
audio track); it is `null` for images, and its fields are `null` while a file is not
probed yet. For a token, items in a container it cannot read are left out of the page.

## Query parameters

- `type` string
- `limit` integer
- `offset` integer

## Response `200`

One page of files.

- object
  - `success` boolean
  - `data` object
    - `items` FileListItem[]
      - `uuid` string, uuid
      - `file_name` string
      - `mime_type` string
      - `size_bytes` integer, nullable
      - `width` integer, nullable
      - `height` integer, nullable
      - `created_at` string, nullable
      - `thumbnail_url` string, nullable: Session thumbnail path, or null.
      - `media` object, nullable: Video and audio only; null for images. Fields are null until the file is probed.
        - `duration_ms` integer, nullable
        - `width` integer, nullable
        - `height` integer, nullable
        - `fps` object, nullable
          - `num` integer
          - `den` integer
        - `has_audio` boolean, nullable
        - `video_codec` string, nullable
        - `audio_codec` string, nullable
    - `pagination` object
      - `limit` integer: Page size.
      - `offset` integer: Offset.
      - `total` integer: Matching files.
      - `has_more` boolean: Whether a further page exists.
  - `timestamp` string, date-time

## Other responses

- `400`: Unknown type.
- `401`: Missing or invalid API key.
- `403`: The token does not hold files: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)