API Documentation — OneChatAPI

Language:

Introduction

OneChatAPI is a unified REST and WebSocket API that gives you access to 12+ AI model providers — OpenAI, Anthropic, Google Gemini, Mistral, Cohere, Replicate, Perplexity, X.AI, Qwen, ElevenLabs, and Gemini Live — through a single consistent interface.

The API handles streaming chat via Server-Sent Events, real-time bidirectional chat over WebSocket, real-time voice conversations via audio WebSocket, conversation management, user profiles, team organizations, subscriptions, and file attachments.

Base URLhttps://onechatapi.com

Streaming Chat

SSE-based streaming, OpenAI-compatible chunks

WebSocket Chat

Bidirectional real-time messaging

Realtime Audio

Low-latency voice via WebSocket

12+ Providers

One API key for every major AI model

Conversation History

Persistent storage, search, branching

File Attachments

Upload images and documents to chat

Authentication

Authenticate by obtaining a JWT token via the sign-in endpoint and including it in every request as a Bearer token. Tokens do not expire by default.

JWT Bearer Token

Pass your token in the Authorization header on every protected request:

bash

Authorization: Bearer <your_jwt_token>

POST/signin

Exchange email and password for a JWT token. The token is used in all subsequent requests.

bash

curl -X POST https://onechatapi.com/signin \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your_password"}'

Response

json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": { "id": "uuid", "email": "you@example.com" }
}

Guest Access

Publicly shared conversations can be read without a JWT token. Pass the guest token in the Authorization-Guest header instead:

bash

curl https://onechatapi.com/api/chat/{conversationID} \
  -H "Authorization-Guest: <guest_token>"

Streaming Chat (SSE)

The primary chat endpoint streams the model response as Server-Sent Events in an OpenAI-compatible chunk format. Each data: line contains a JSON object with a choices[].delta.content field. The stream ends with data: [DONE].

Send Message

POST/api/chat/events

bash

curl -N https://onechatapi.com/api/chat/events \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Explain Go channels in one paragraph",
    "model": "gpt-4o",
    "conversationID": ""
  }'

Response Format

Each event is a JSON object following the OpenAI streaming chunk format. The final chunk before [DONE] includes a usage object with token counts and cost.

SSE stream

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"Go"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" channels"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":8,"completion_tokens":42,"total_tokens":50,"cost_usd":0.00062}}

data: [DONE]

Parameters

Request body fields:

Field	Type	Required	Description
message	string	yes	User message content
model	string	yes	Model ID from /api/chat/models
conversationID	string	no	Existing conversation ID; empty string creates a new conversation
context	string	no	System-level context override
profileID	string	no	Reusable system prompt profile ID
instructions	string	no	One-off system instruction appended to context
image	string	no	Image URL for vision models
attachments	[]string	no	Array of file attachment IDs (from /api/files)
parentId	string	no	Parent message ID for branched conversations
hiddenFromBot	bool	no	Store message in history but do not send to model
code	bool	no	Hint that response should be code-focused

WebSocket Chat

For bidirectional real-time communication, connect to the WebSocket endpoint. The server sends the same streaming chunk format as SSE. Authentication uses the JWT token as a query parameter because browser WebSocket APIs do not support custom headers.

Connect

WS/chat/ws/{conversationID}

Pass the JWT via the ?token= query parameter. Use an empty GUID or new as the conversation ID to create a new conversation on first message.

bash

# Install: npm install -g wscat
wscat -c "wss://onechatapi.com/chat/ws/{conversationID}?token=$TOKEN"

Send & Receive

After connecting, send a JSON object with the message and model. The server streams back chunks in the same format as the SSE endpoint.

bash

# After connecting with wscat, type or pipe:
{"message": "Hello", "model": "claude-sonnet-4-5"}

Realtime Audio

Connect to the audio WebSocket to stream microphone input and receive synthesized speech in real time. Raw PCM16 audio bytes are sent as binary WebSocket frames; the server responds with transcript events and base64-encoded audio chunks.

Connect

WS/chat/audio/ws/{conversationID}

Pass all configuration as query parameters. Authentication uses token= (same as WebSocket chat).

bash

wscat -c "wss://onechatapi.com/chat/audio/ws/{conversationID}?model=gpt-4o-realtime-preview&voice=alloy&format=pcm16&provider=openai&token=$TOKEN"

Parameters

Query parameters for the audio WebSocket:

Param	Required	Values	Description
model	yes	gpt-4o-realtime-preview	Audio model ID
provider	yes	openai, google, elevenlabs	Audio provider
voice	no	alloy, echo, shimmer, nova, onyx, fable	TTS voice to use
format	no	pcm16, opus, g711_ulaw	Audio encoding format (default: pcm16)
token	yes	JWT	Auth token passed as query string for WS auth

Events

The server sends JSON events over the WebSocket. The type field indicates the event kind:

type	Description
transcript	Text transcription of the user's spoken input
audio	Base64-encoded audio response chunk (PCM16 by default)
done	Session or response turn has ended
error	Error message in the message field

Example events:

json

{ "type": "transcript", "text": "Hello, how can I help you?" }
{ "type": "audio", "data": "UklGRiQAAABXQVZFZm10IBAAAA..." }

Voices & Providers

Fetch the list of available voices and audio providers for the authenticated user:

GET/api/audio/voices

GET/api/audio/providers

bash

curl https://onechatapi.com/api/audio/voices \
  -H "Authorization: Bearer $TOKEN"

Sessions

Audio sessions are automatically recorded. Retrieve past sessions or check for active ones:

GET/api/audio/sessions

GET/api/audio/session/{sessionID}

GET/api/audio/sessions/active

bash

curl https://onechatapi.com/api/audio/sessions \
  -H "Authorization: Bearer $TOKEN"

Response

json

{
  "id": "uuid",
  "conversation_id": "uuid",
  "model": "gpt-4o-realtime-preview",
  "provider": "openai",
  "voice": "alloy",
  "start_time": "2025-01-01T10:00:00Z",
  "end_time": "2025-01-01T10:05:00Z",
  "duration_seconds": 300,
  "audio_input_seconds": 120,
  "audio_output_seconds": 180,
  "cost": 0.045,
  "status": "completed"
}

Models

Retrieve the models available to the authenticated user or the complete catalog with full metadata including context window size, capabilities, and pricing.

List Available

GET/api/chat/models

Returns only the models the authenticated user can access based on their subscription tier.

bash

curl https://onechatapi.com/api/chat/models \
  -H "Authorization: Bearer $TOKEN"

Full Catalog

GET/api/models/catalog

Returns all models with complete metadata. Model object schema:

bash

curl https://onechatapi.com/api/models/catalog \
  -H "Authorization: Bearer $TOKEN"

Response

json

{
  "id": "gpt-4o",
  "name": "gpt-4o",
  "display_name": "GPT-4o",
  "family": "gpt-4",
  "context_window": 128000,
  "vision_enabled": true,
  "audio_enabled": false,
  "min_subscription_level": 0,
  "cost_prompt": 0.005,
  "cost_completion": 0.015,
  "provider": { "id": "openai", "name": "OpenAI" },
  "features": {
    "streaming": true,
    "vision": true,
    "audio": false,
    "embeddings": true,
    "function_calling": true
  },
  "pricing": {
    "input_per_1k_tokens": 0.005,
    "output_per_1k_tokens": 0.015
  }
}

Providers

Capabilities by provider:

Provider	streaming	vision	audio	embeddings
OpenAI	✓	✓	✓	✓
Anthropic	✓	✓	—	✓
Google Gemini	✓	✓	✓	✓
Mistral	✓	—	—	✓
Cohere	✓	—	—	✓
Replicate (Llama)	✓	—	—	—
Perplexity	✓	—	—	—
X.AI (Grok)	✓	—	—	—
Qwen	✓	—	—	—
ElevenLabs	—	—	✓	—
Gemini Live	—	—	✓	—

Conversations

Conversations are automatically created when you send a message with an empty conversationID. They persist all messages and can be updated, archived, shared publicly, or searched.

List

GET/api/chat

Returns all conversations for the authenticated user, ordered by last activity.

bash

curl https://onechatapi.com/api/chat \
  -H "Authorization: Bearer $TOKEN"

Get with Messages

GET/api/chat/{conversationID}

Returns the conversation metadata and its full message history.

bash

curl https://onechatapi.com/api/chat/{conversationID} \
  -H "Authorization: Bearer $TOKEN"

Update

PUT/api/chat/{conversationID}

Update the title, model, or other metadata of a conversation.

bash

curl -X PUT https://onechatapi.com/api/chat/{conversationID} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "New title", "model": "claude-sonnet-4-5"}'

Delete

DELETE/api/chat/{conversationID}

Permanently delete a conversation and all its messages.

bash

curl -X DELETE https://onechatapi.com/api/chat/{conversationID} \
  -H "Authorization: Bearer $TOKEN"

Search

GET/api/chat/search/conversations?q={query}

Full-text search across all conversation titles and messages.

bash

curl "https://onechatapi.com/api/chat/search/conversations?q=golang+channels" \
  -H "Authorization: Bearer $TOKEN"

Profiles

Profiles are reusable sets of system instructions and model parameter overrides (temperature, top_p, etc.). They let you define a persona or task-specific assistant once and reuse it across many conversations.

Using Profiles

Include the profileID field in any chat request to apply that profile's system prompt and parameter overrides to the conversation:

bash

curl -N https://onechatapi.com/api/chat/events \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Review this Go code",
    "model": "gpt-4o",
    "conversationID": "",
    "profileID": "profile_abc123"
  }'

Search

GET/api/chat/search/profiles?q={query}

Search profiles by name or description.

bash

curl "https://onechatapi.com/api/chat/search/profiles?q=code+review" \
  -H "Authorization: Bearer $TOKEN"

User & Usage

Retrieve the authenticated user's account information, token usage statistics, and manage their default model.

Get Current User

GET/api/user

bash

curl https://onechatapi.com/api/user \
  -H "Authorization: Bearer $TOKEN"

Usage Statistics

GET/api/user/usage

Returns message count, total tokens consumed, total cost in USD, and a per-model breakdown.

bash

curl https://onechatapi.com/api/user/usage \
  -H "Authorization: Bearer $TOKEN"

Response

json

{
  "message_count": 1247,
  "conversation_count": 89,
  "total_tokens": 4820000,
  "total_cost_usd": 12.43,
  "by_model": [
    { "model": "gpt-4o", "messages": 820, "tokens": 3200000, "cost_usd": 9.60 },
    { "model": "claude-sonnet-4-5", "messages": 427, "tokens": 1620000, "cost_usd": 2.83 }
  ]
}

Set Default Model

PUT/api/user/default-model

Set the model that is pre-selected for new conversations in the web app.

bash

curl -X PUT https://onechatapi.com/api/user/default-model \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o"}'

Teams

Organize users into organizations with role-based access. Roles are member and admin. Admins can invite members and change roles.

Create Organization

POST/api/organization

bash

curl -X POST https://onechatapi.com/api/organization \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme AI Team"}'

Invite Member

POST/api/organization/invite

Send an invitation email to a new team member.

bash

curl -X POST https://onechatapi.com/api/organization/invite \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "colleague@acme.com", "role": "member"}'

Update Role

PUT/api/organization/user

Change a team member's role. Only admins can perform this action.

bash

curl -X PUT https://onechatapi.com/api/organization/user \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "uuid", "role": "admin"}'

Subscriptions

Plans: free · starter · pro · max · team. Models have a min_subscription_level field — higher-tier models require a paid plan.

Current Plan

GET/api/subscription/me

Returns the authenticated user's active subscription details.

bash

curl https://onechatapi.com/api/subscription/me \
  -H "Authorization: Bearer $TOKEN"

List Plans

GET/api/subscription/plans

Returns all available subscription plans and their features.

bash

curl https://onechatapi.com/api/subscription/plans \
  -H "Authorization: Bearer $TOKEN"

Checkout

POST/api/subscribe

Create a Stripe checkout session. Redirect the user to the returned URL to complete payment.

bash

curl -X POST https://onechatapi.com/api/subscribe \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan": "pro"}'

Response

json

{ "checkout_url": "https://checkout.stripe.com/pay/cs_live_..." }

File Uploads

Upload images or documents to attach to chat messages. Pass the returned file id in the attachments array of a chat request. Files are scoped to a profile.

POST/api/files/{profileID}

bash

curl -X POST https://onechatapi.com/api/files/{profileID} \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@image.png"

Response

json

{
  "id": "file_abc123",
  "filename": "image.png",
  "size": 204800,
  "content_type": "image/png"
}

Errors & Rate Limits

All errors return a JSON body with a human-readable message and a machine-readable error code:

json

{
  "error": "human readable message",
  "code": "ERROR_CODE"
}

HTTP Status Codes

Status	Meaning
200	Success
400	Invalid request body or missing required fields
401	Missing or invalid JWT token
403	Insufficient subscription tier for the requested model
404	Resource not found
429	Rate limit exceeded — back off and retry
500	Internal server error

Rate Limits

Default rate limit is 30 requests per minute per IP address on all routes. When exceeded, the API returns a 429 response:

bash

HTTP/1.1 429 Too Many Requests

{"error": "You have reached maximum request limit.", "code": "RATE_LIMIT_EXCEEDED"}

Implement exponential backoff when retrying after a 429. The Retry-After header indicates the number of seconds to wait before the next attempt.

Introduction

Authentication

JWT Bearer Token

Sign In

Guest Access

Streaming Chat (SSE)

Send Message

Response Format

Parameters

WebSocket Chat

Connect

Send & Receive

Realtime Audio

Connect

Parameters

Events

Voices & Providers

Sessions

Models

List Available

Full Catalog

Providers

Conversations

List

Get with Messages

Update

Delete

Archive

Share Publicly

Search

Profiles

Using Profiles

Search

User & Usage

Get Current User

Usage Statistics

Set Default Model

Teams

Create Organization

Invite Member

Update Role

Subscriptions

Current Plan

List Plans

Checkout

File Uploads

Errors & Rate Limits

HTTP Status Codes

Rate Limits