Chat API

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)

Show result properties

text

string

The AI-generated response

userId

string

User ID for tracking

progress

object

Progress information (present during active execution)

Show progress properties

stage

string

Current execution stage

percent

number

Completion percentage (0-100)

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

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)

Deep Research API - Multi-iteration autonomous research
Status API - Check deep research job progress

Core Endpoints

File Management

Paper Generation

Payment Endpoints

Admin

Overview

Authentication

Execution Modes

POST /api/chat

Request Body

Response (In-Process Mode)

Response (Queue Mode)

Example: Basic Chat

Example Response (In-Process)

Example: Multi-Turn Conversation

Example: Chat with File Upload

GET /api/chat/status/:jobId

Path Parameters

Response Fields

Example: Check Job Status

Example Response: Completed

Example Response: Processing

POST /api/chat/retry/:jobId

Authentication Required

Path Parameters

Response Fields

Example: Retry Failed Job

Example Response

Error Codes

Features

Rate Limits

Build docs developers (and LLMs) love

Core Endpoints

File Management

Paper Generation

Payment Endpoints

Admin

​Overview

​Authentication

​Execution Modes

​POST /api/chat

​Request Body

​Response (In-Process Mode)

​Response (Queue Mode)

​Example: Basic Chat

​Example Response (In-Process)

​Example: Multi-Turn Conversation

​Example: Chat with File Upload

​GET /api/chat/status/:jobId

​Path Parameters

​Response Fields

​Example: Check Job Status

​Example Response: Completed

​Example Response: Processing

​POST /api/chat/retry/:jobId

​Authentication Required

​Path Parameters

​Response Fields

​Example: Retry Failed Job

​Example Response

​Error Codes

​Features

​Rate Limits

​Related Endpoints

Build docs developers (and LLMs) love

Overview

Authentication

Execution Modes

POST /api/chat

Request Body

Response (In-Process Mode)

Response (Queue Mode)

Example: Basic Chat

Example Response (In-Process)

Example: Multi-Turn Conversation

Example: Chat with File Upload

GET /api/chat/status/:jobId

Path Parameters

Response Fields

Example: Check Job Status

Example Response: Completed

Example Response: Processing

POST /api/chat/retry/:jobId

Authentication Required

Path Parameters

Response Fields

Example: Retry Failed Job

Example Response

Error Codes

Features

Rate Limits

Related Endpoints