> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perceptron.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Files

> Upload media once and reference it across requests

# Working with files

Upload images and video once, then reference them by id across many requests — instead of re-sending (or base64-inlining) the same media on every call. Files are stored against your organization, addressed by a `file-...` id, and the endpoints are OpenAI-compatible.

## The endpoints

<CardGroup cols={2}>
  <Card title="Upload File" icon="upload" href="/isaac-0.1/api-reference/endpoint/upload-file">
    Upload a file and get back a `file-...` id.
  </Card>

  <Card title="List Files" icon="list" href="/isaac-0.1/api-reference/endpoint/list-files">
    Page through your organization's files.
  </Card>

  <Card title="Retrieve File" icon="file" href="/isaac-0.1/api-reference/endpoint/retrieve-file">
    Fetch a file's metadata.
  </Card>

  <Card title="Retrieve File Content" icon="download" href="/isaac-0.1/api-reference/endpoint/retrieve-file-content">
    Download the raw bytes.
  </Card>

  <Card title="Delete File" icon="trash" href="/isaac-0.1/api-reference/endpoint/delete-file">
    Permanently remove a file.
  </Card>
</CardGroup>

## Referencing a file in a request

Reference an uploaded file in a chat completion by id with an `image_file_id` / `video_file_id` content part, or by passing its `/v1/files/{file_id}/content` URL as a standard `image_url` / `video_url`. All four forms are equivalent.

<CodeGroup>
  ```json Image (file_id) theme={null}
  { "type": "image_file_id", "image_file_id": { "file_id": "file-abc123" } }
  ```

  ```json Video (file_id) theme={null}
  { "type": "video_file_id", "video_file_id": { "file_id": "file-abc123" } }
  ```

  ```json Image (URL) theme={null}
  { "type": "image_url",
    "image_url": { "url": "https://api.perceptron.inc/v1/files/file-abc123/content" } }
  ```

  ```json Video (URL) theme={null}
  { "type": "video_url",
    "video_url": { "url": "https://api.perceptron.inc/v1/files/file-abc123/content" } }
  ```
</CodeGroup>

## Limits

Files are capped at **128 MiB** each, with **100 GiB** of total storage per organization. Per-endpoint rate limits are listed on each API reference page.

Need higher limits? [Contact us](mailto:support@perceptron.inc).