Skip to main content
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

​
file_id
string
A unique identifier for the uploaded file. Pass this value as file_id in your chat request to query the document.
​
filename
string
The original filename of the uploaded document, as provided in the request.
​
size_bytes
integer
The size of the uploaded file in bytes.
​
created_at
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

​
file_id
string
required
The unique identifier returned when you uploaded the file in Step 1. This tells the API which document to query.
​
message
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

​
id
string
A unique identifier for this chat interaction.
​
answer
string
The AI-generated answer to your question, derived from the content of the uploaded document.
​
sources
array
An array of source objects referencing the specific sections of the document the answer was drawn from.
​
created_at
string
An ISO 8601 timestamp indicating when the chat response was generated.

​
Error responses

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."
  }
}
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."
  }
}
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."
  }
}