Skip to main content
POST
/
api
/
chat
Chat API
curl --request POST \
  --url https://api.example.com/api/chat \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "<string>",
  "conversationId": "<string>",
  "files": [
    null
  ]
}
'
{
  "400": {},
  "401": {},
  "403": {},
  "404": {},
  "429": {},
  "500": {},
  "text": "<string>",
  "userId": "<string>",
  "jobId": "<string>",
  "messageId": "<string>",
  "conversationId": "<string>",
  "status": "<string>",
  "pollUrl": "<string>",
  "result": {
    "text": "<string>",
    "userId": "<string>"
  },
  "progress": {
    "stage": "<string>",
    "percent": 123
  },
  "error": "<string>",
  "attemptsMade": 123,
  "ok": true,
  "message": "<string>",
  "previousAttempts": 123
}

​
Overview

The Chat API provides conversational AI capabilities with integrated literature search, hypothesis generation, and data analysis. It supports both synchronous and asynchronous execution modes.

​
Authentication

All chat endpoints require authentication via JWT token or API key.
​
Authorization
string
required
Bearer token for JWT authentication
​
X-API-Key
string
Alternative API key authentication

​
Execution Modes

The API operates in two modes based on the USE_JOB_QUEUE environment variable:
  • In-Process Mode (USE_JOB_QUEUE=false): Executes synchronously and returns results directly
  • Queue Mode (USE_JOB_QUEUE=true): Enqueues job to BullMQ and returns job ID for polling

​
POST /api/chat

Send a message to the AI agent for processing.

​
Request Body

​
message
string
required
The user’s question or message to process
​
conversationId
string
Optional conversation ID for multi-turn conversations. Auto-generated if not provided.
​
files
File[]
Optional array of files to upload and analyze (supports CSV, PDF, images)

​
Response (In-Process Mode)

Returns 200 OK with the AI’s response.
​
text
string
The AI-generated response text
​
userId
string
User ID for tracking (included for x402 payment users)

​
Response (Queue Mode)

Returns 202 Accepted with job information.
​
jobId
string
BullMQ job ID for status polling
​
messageId
string
Database message ID for tracking
​
conversationId
string
Conversation ID for multi-turn context
​
userId
string
User ID for ownership verification
​
status
string
Job status: queued
​
pollUrl
string
URL to check job status

​
Example: Basic Chat

curl -X POST https://api.bioagents.xyz/api/chat \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the key pathways involved in autophagy?"
  }'

​
Example Response (In-Process)

{
  "text": "Autophagy involves several key pathways:\n\n1. **mTOR Pathway**: The master regulator that inhibits autophagy when nutrients are abundant...\n\n2. **ULK1 Complex**: Initiates autophagosome formation...",
  "userId": "usr_abc123"
}

​
Example: Multi-Turn Conversation

curl -X POST https://api.bioagents.xyz/api/chat \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What about the role of AMPK in this process?",
    "conversationId": "conv_xyz789"
  }'

​
Example: Chat with File Upload

curl -X POST https://api.bioagents.xyz/api/chat \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "message=Analyze this gene expression dataset" \
  -F "files=@expression_data.csv"

​
GET /api/chat/status/:jobId

Check the status of a queued chat job (only available when USE_JOB_QUEUE=true).

​
Path Parameters

​
jobId
string
required
The job ID returned from POST /api/chat

​
Response Fields

​
status
string
Job status: queued, active, completed, failed, or not_found
​
result
object
Chat result (only present when status is completed)
​
progress
object
Progress information (present during active execution)
​
error
string
Error message (only present when status is failed)
​
attemptsMade
number
Number of retry attempts made

​
Example: Check Job Status

curl https://api.bioagents.xyz/api/chat/status/msg_abc123

​
Example Response: Completed

{
  "status": "completed",
  "result": {
    "text": "Based on the literature search, autophagy is regulated by...",
    "userId": "usr_abc123"
  }
}

​
Example Response: Processing

{
  "status": "active",
  "progress": {
    "stage": "literature_search",
    "percent": 45
  },
  "attemptsMade": 0
}

​
POST /api/chat/retry/:jobId

Manually retry a failed chat job.

​
Authentication Required

Must be the owner of the job being retried.

​
Path Parameters

​
jobId
string
required
The job ID to retry

​
Response Fields

​
ok
boolean
Whether retry was successful
​
jobId
string
The job ID being retried
​
status
string
New status: retrying
​
message
string
Human-readable status message
​
previousAttempts
number
Number of previous retry attempts

​
Example: Retry Failed Job

curl -X POST https://api.bioagents.xyz/api/chat/retry/msg_abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Example Response

{
  "ok": true,
  "jobId": "msg_abc123",
  "status": "retrying",
  "message": "Job has been queued for retry",
  "previousAttempts": 1
}

​
Error Codes

​
400
Bad Request
Missing required field (message) or invalid request format
​
401
Unauthorized
Missing or invalid authentication credentials
​
403
Forbidden
Attempting to access another user’s job
​
404
Not Found
Job not found or queue mode not enabled
​
429
Rate Limited
Too many requests - rate limit exceeded
​
500
Internal Server Error
Server error during processing

​
Features

The Chat API automatically:
  • Literature Search: Queries OpenScholar, BioLit, and knowledge bases
  • Hypothesis Generation: Creates testable hypotheses when appropriate
  • File Processing: Extracts data from CSV, PDF, and image files
  • Context Retention: Maintains conversation history across messages
  • Token Usage Tracking: Monitors LLM token consumption per message

​
Rate Limits

Rate limits are configurable per authentication method:
  • JWT Users: Default 60 requests/minute
  • API Key Users: Custom limits based on tier
  • Anonymous Users: 10 requests/minute (if enabled)

Build docs developers (and LLMs) love

Get started for freeTalk to us