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

# POST /file/chat — Chat with Uploaded Documents

> Upload a document and ask questions about its content via the Verbosec API. Supports PDF, DOCX, and CSV. Returns AI-generated answers from the file.

The Nexus File Chat feature lets you have a conversation with the content of a document. You first upload your file to receive a `file_id`, then send natural-language questions referencing that `file_id`. Nexus AI reads the document, finds the relevant sections, and returns a direct answer along with source excerpts so you can trace where each answer came from.

Working with File Chat is a two-step process: upload the file, then chat with it.

<Note>
  **Supported formats:** PDF, `.docx`, and `.csv`. Maximum file size: **20 MB**.
</Note>

***

## Step 1 — Upload a file

Before you can ask questions, you must upload your document to receive a `file_id`.

**Endpoint**

```
POST https://api.verbosec.com/v1/file/upload
```

The upload request uses `multipart/form-data` rather than JSON. Include your file in the `file` field.

### Example upload request

```bash upload-file.sh theme={null}
curl -X POST https://api.verbosec.com/v1/file/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/your/document.pdf"
```

### Example upload response

```json upload-response.json theme={null}
{
  "file_id": "file_ghi101",
  "filename": "document.pdf",
  "size_bytes": 1048576,
  "created_at": "2025-01-15T10:33:00Z"
}
```

Copy the `file_id` from this response — you will need it for the chat request in Step 2.

### Upload response fields

<ResponseField name="file_id" type="string">
  A unique identifier for the uploaded file. Pass this value as `file_id` in your chat request to query the document.
</ResponseField>

<ResponseField name="filename" type="string">
  The original filename of the uploaded document, as provided in the request.
</ResponseField>

<ResponseField name="size_bytes" type="integer">
  The size of the uploaded file in bytes.
</ResponseField>

<ResponseField name="created_at" type="string">
  An ISO 8601 timestamp indicating when the file was uploaded and processed.
</ResponseField>

***

## Step 2 — Chat with the file

Once you have a `file_id`, send messages to query the document content.

**Endpoint**

```
POST https://api.verbosec.com/v1/file/chat
```

### Request parameters

<ParamField body="file_id" type="string" required>
  The unique identifier returned when you uploaded the file in Step 1. This tells the API which document to query.
</ParamField>

<ParamField body="message" type="string" required>
  Your natural-language question or instruction about the document content — for example, `"What are the key findings in this report?"`.
</ParamField>

### Example chat request

```bash chat-with-file.sh theme={null}
curl -X POST https://api.verbosec.com/v1/file/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "file_ghi101",
    "message": "What are the three key findings mentioned in this document?"
  }'
```

### Example response

```json response.json theme={null}
{
  "id": "chat_jkl202",
  "answer": "The document highlights three key findings: first, customer retention improved by 18% following the Q3 campaign; second, mobile conversion rates outpaced desktop for the first time; third, the average order value increased by $12 year-on-year.",
  "sources": [
    {
      "page": 4,
      "excerpt": "The study found a marked improvement in customer retention of 18% following the Q3 campaign..."
    },
    {
      "page": 7,
      "excerpt": "For the first time, mobile conversion rates exceeded those recorded on desktop platforms..."
    }
  ],
  "created_at": "2025-01-15T10:33:00Z"
}
```

## Response fields

<ResponseField name="id" type="string">
  A unique identifier for this chat interaction.
</ResponseField>

<ResponseField name="answer" type="string">
  The AI-generated answer to your question, derived from the content of the uploaded document.
</ResponseField>

<ResponseField name="sources" type="array">
  An array of source objects referencing the specific sections of the document the answer was drawn from.

  <Expandable title="Source object fields">
    <ResponseField name="sources[].page" type="integer">
      The page number in the document where this source excerpt was found. For CSV files, this field reflects the row range instead.
    </ResponseField>

    <ResponseField name="sources[].excerpt" type="string">
      A short excerpt from the document that supports the answer, shown in its original wording.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  An ISO 8601 timestamp indicating when the chat response was generated.
</ResponseField>

## Error responses

<Accordion title="400 Bad Request — Missing parameters">
  Returned when `file_id` or `message` is absent from the request body.

  ```json 400-response.json theme={null}
  {
    "error": {
      "code": "missing_required_field",
      "message": "The 'file_id' and 'message' fields are required."
    }
  }
  ```
</Accordion>

<Accordion title="404 Not Found — File not found">
  Returned when the `file_id` does not correspond to a file associated with your account.

  ```json 404-response.json theme={null}
  {
    "error": {
      "code": "file_not_found",
      "message": "No file with the given file_id was found on your account."
    }
  }
  ```
</Accordion>

<Accordion title="429 Too Many Requests — Rate limited">
  Returned when you exceed your plan's rate limit. Check the `Retry-After` response header and wait before retrying.

  ```json 429-response.json theme={null}
  {
    "error": {
      "code": "rate_limit_exceeded",
      "message": "You have exceeded your plan's rate limit. Please wait before retrying."
    }
  }
  ```
</Accordion>