POST /file/chat — Chat with Uploaded Documents

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.

Supported formats: PDF, .docx, and .csv. Maximum file size: 20 MB.

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

upload-file.sh

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

upload-response.json

{
  "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

string

A unique identifier for the uploaded file. Pass this value as file_id in your chat request to query the document.

string

The original filename of the uploaded document, as provided in the request.

integer

The size of the uploaded file in bytes.

string

An ISO 8601 timestamp indicating when the file was uploaded and processed.

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

string

required

The unique identifier returned when you uploaded the file in Step 1. This tells the API which document to query.

string

required

Your natural-language question or instruction about the document content — for example, "What are the key findings in this report?".

Example chat request

chat-with-file.sh

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

response.json

{
  "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

string

A unique identifier for this chat interaction.

string

The AI-generated answer to your question, derived from the content of the uploaded document.

array

An array of source objects referencing the specific sections of the document the answer was drawn from.

Show Source object fields

integer

The page number in the document where this source excerpt was found. For CSV files, this field reflects the row range instead.

string

A short excerpt from the document that supports the answer, shown in its original wording.

string

An ISO 8601 timestamp indicating when the chat response was generated.

Error responses

400 Bad Request — Missing parameters

Returned when file_id or message is absent from the request body.

400-response.json

{
  "error": {
    "code": "missing_required_field",
    "message": "The 'file_id' and 'message' fields are required."
  }
}

404 Not Found — File not found

Returned when the file_id does not correspond to a file associated with your account.

404-response.json

{
  "error": {
    "code": "file_not_found",
    "message": "No file with the given file_id was found on your account."
  }
}

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.

429-response.json

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You have exceeded your plan's rate limit. Please wait before retrying."
  }
}

Overview

Nexus AI API

Starhost API

POST /file/chat — Chat with Uploaded Documents

Step 1 — Upload a file

Example upload request

Example upload response

Upload response fields

Step 2 — Chat with the file

Request parameters

Example chat request

Example response

Response fields

Error responses

​Step 1 — Upload a file

​Example upload request

​Example upload response

​Upload response fields

​Step 2 — Chat with the file

​Request parameters

​Example chat request

​Example response

​Response fields

​Error responses

Step 1 — Upload a file

Example upload request

Example upload response

Upload response fields

Step 2 — Chat with the file

Request parameters

Example chat request

Example response

Response fields

Error responses