---
title: "List files"
method: GET
path: "/api/v1/files"
tags: ["Files"]
---

# List files

`GET /api/v1/files`

## Request

- Base URL: `https://your-deployment.example.com`
- URL: `https://your-deployment.example.com/api/v1/files`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Lists the files you own, newest first, excluding archived and deleted ones. Files shared with you are not listed, though `GET /api/v1/files/{id}` resolves them by id: listing shares would need access checks that cannot be paged by cursor. Items carry no `download_url`; fetch a file by id for its bytes. `search` keeps only files whose name contains it, ignoring case; results stay newest first with no relevance ranking. Cursor-paginated (see the pagination convention): pass `next_cursor` back as `cursor`, with the same `search`, until it is `null`. Safe (GET) requests are exempt from the per-day API-key quota; only the per-minute burst limit applies. Authenticate with an API key (`b4m_live_`) carrying `files:read`, or a JWT.

## Query parameters

- `limit` integer
- `cursor` string
- `search` string

## Response `200`

One page of files, newest first by `id`.

- ListFilesResponse200
  - `data` object[], required
    - `id` string, required
    - `file_name` string, required
    - `mime_type` string, required
    - `file_size` number, required
    - `moderation_status` 'pending' | 'scanning' | 'clean' | 'blocked' | 'null', nullable, required
    - `created_at` string, required
  - `next_cursor` string, nullable, required

## Other responses

- `401`: Missing or invalid credentials.
- `403`: The API key lacks `files:read`.
- `405`: The path does not serve this HTTP method.
- `422`: `limit` or `search` is out of range, or `cursor` is malformed or was issued by a different endpoint. A cursor is opaque: pass back exactly the `next_cursor` you were given.
- `429`: Per-user rate limit exceeded.

---

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