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

# Files

> Stage documents for quotes by direct upload or URL

The files API stages documents ahead of quote creation. Upload once, then
reference the file `id` in `document_ids` when creating a quote.

## Direct upload

Send the file as multipart form data. Processing is synchronous — the response
returns status `ready`:

```bash theme={null}
curl https://api.fortiseval.com/v1/files \
  -H "Authorization: Bearer sk-your-secret-key" \
  -F "file=@/path/to/transcript.pdf"
```

```json theme={null}
{
  "message": "File uploaded successfully.",
  "data": {
    "id": "upload_abc123...",
    "status": "ready",
    "source": "direct_upload",
    "file_name": "transcript.pdf",
    "mime_type": "application/pdf",
    "size": 182044
  }
}
```

## Ingest by URL

Send a JSON body with a `url` and we download it in the background. The response
is `202` with status `pending`:

```bash theme={null}
curl https://api.fortiseval.com/v1/files \
  -H "Authorization: Bearer sk-your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/documents/diploma.pdf" }'
```

Track completion either way:

* **Webhooks** — subscribe to `file.ready` / `file.failed` (recommended).
* **Polling** — `GET /v1/files/{id}` until `status` is `ready` or `failed`
  (`failure_message` explains failures).

## File states

| Status       | Meaning                                  |
| ------------ | ---------------------------------------- |
| `pending`    | URL ingestion queued                     |
| `processing` | Download/processing in progress          |
| `ready`      | Usable in `document_ids`                 |
| `failed`     | Ingestion failed — see `failure_message` |

## Rules

* **Supported types**: PDFs, images (JPEG/PNG/HEIC/TIFF), Microsoft Office
  documents, text, RTF, and ZIP archives. Maximum size 150 MB.
* **Single use**: attaching a file to a quote consumes it. To use the same
  document on another quote, upload it again.
* Files must be `ready` and unconsumed when referenced in `document_ids`,
  otherwise quote creation returns a `422` validation error for that entry.
* You can also skip the files API entirely and pass `document_urls` directly
  when creating a quote.