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

# List files

`GET /api/v1/files`

## Request

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

Returns the organization's non-deleted files ordered newest first, with cursor pagination (default 50 per page, max 200). By default only ready files appear; pass status=pending to list incomplete uploads that have not passed their upload expiry window (cancel them with DELETE /api/v1/files/{fileId}). Scope the list with folderId or path (mutually exclusive); path=/ means the root folder, and omitting both lists every folder. Each file includes contentUrl, a stable authenticated API URL for opening the file content.

## Query parameters

- `folderId` string
- `path` string: A folder path such as "/invoices/2026". Segments match active folders case-insensitively; "/" means the root.
- `status` 'ready' | 'pending': File status filter. Default `ready`. Use `pending` to list incomplete uploads that have not passed their upload expiry window; cancel them with DELETE /api/v1/files/{fileId}.
- `limit` integer
- `cursor` string

## Response `200`

One page of the organization's files.

- object
  - `files` object[], required
    - `id` string, required
    - `name` string, required
    - `contentUrl` string, required: Stable authenticated API URL for opening the file content. It redirects to a short-lived inline storage URL when the file is ready.
    - `folderId` string, nullable, required: The containing folder's id, or null for the root.
    - `path` string, required: The file's full display path, including the file name. Paths change on rename/move; store ids.
    - `kind` 'archive' | 'audio' | 'document' | 'image' | 'other' | 'pdf' | 'spreadsheet' | 'video', required
    - `extension` string, nullable, required
    - `contentType` string, required
    - `sizeBytes` integer, required
    - `status` 'pending' | 'ready', required
    - `createdAt` string, required
    - `updatedAt` string, required
  - `nextCursor` string, nullable, required: Opaque cursor for the next page; null when no more results.

## Other responses

- `400`: The request was malformed or failed validation.
- `401`: Authentication is missing or invalid.
- `404`: The resource was not found.
- `429`: Too many requests; retry after the indicated delay.

---

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