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

# Files API

> Upload and manage files for your AI applications. Supports PDF, DOCX, TXT, CSV, JSON, and images.

## Supported Formats

| Type      | Extensions                                      | Max Size |
| --------- | ----------------------------------------------- | -------- |
| Documents | `.pdf`, `.docx`, `.txt`, `.csv`, `.json`, `.md` | 50 MB    |
| Images    | `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`        | 20 MB    |

***

## Quick Start

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.cuadra.ai/v1/files \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Idempotency-Key: upload-001" \
    -F "file=@document.pdf"
  ```

  ```python Python theme={null}
  import httpx

  with open("document.pdf", "rb") as f:
      response = httpx.post(
          "https://api.cuadra.ai/v1/files",
          headers={
              "Authorization": "Bearer YOUR_TOKEN",
              "Idempotency-Key": "upload-001"
          },
          files={"file": f}
      )
  print(response.json())
  ```

  ```typescript Node.js theme={null}
  import fs from 'fs';
  import FormData from 'form-data';

  const form = new FormData();
  form.append('file', fs.createReadStream('document.pdf'));

  const response = await fetch('https://api.cuadra.ai/v1/files', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Idempotency-Key': 'upload-001'
    },
    body: form
  });
  console.log(await response.json());
  ```
</CodeGroup>

***

## Processing Status

Files are processed asynchronously after upload:

| Status       | Description            |
| ------------ | ---------------------- |
| `processing` | File is being analyzed |
| `ready`      | File is ready for use  |
| `failed`     | Processing failed      |

<Tip>
  Poll `GET /v1/files/{file_id}` to check processing status, or use webhooks for async notification.
</Tip>

***

## Associating with Datasets

After upload, associate files with a dataset to make them searchable:

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.cuadra.ai/v1/files/file_abc123/associations \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"datasetId": "ds_xyz789"}'
  ```

  ```python Python theme={null}
  import httpx

  response = httpx.post(
      "https://api.cuadra.ai/v1/files/file_abc123/associations",
      headers={"Authorization": "Bearer YOUR_TOKEN"},
      json={"datasetId": "ds_xyz789"}
  )
  print("File associated with dataset")
  ```

  ```typescript Node.js theme={null}
  await fetch('https://api.cuadra.ai/v1/files/file_abc123/associations', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ datasetId: 'ds_xyz789' })
  });
  console.log('File associated with dataset');
  ```
</CodeGroup>

***

## Storage Limits

Storage limits depend on your plan. See [cuadra.ai/pricing](https://cuadra.ai/pricing) for details.

<Warning>
  Files referenced by datasets cannot be deleted until removed from all datasets.
</Warning>

***

## Related

<CardGroup cols={2}>
  <Card title="Datasets" icon="database" href="/api-reference/datasets">
    Add files to datasets
  </Card>

  <Card title="Billing" icon="credit-card" href="/billing/credits">
    Storage limits and pricing
  </Card>
</CardGroup>