Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/abdelhafid37/talkbox/llms.txt

Use this file to discover all available pages before exploring further.

The TalkBox REST API is a JSON-over-HTTP interface that powers user registration, login, profile retrieval, and message exchange. Every response body — success or error — is JSON. Authentication relies on a short-lived JWT that you obtain by calling the login endpoint and then attach to all subsequent requests via an Authorization header.

​
Base URL

All endpoints share a common prefix. During local development the server listens on port 3000: 
http://localhost:3000/api
In production the hostname changes depending on where you deploy the Node.js server, but the path structure (/api/auth/*, /api/users/*, /api/messages/*) stays the same.

​
Authentication

TalkBox uses the Bearer token scheme. After a successful login you receive a JWT. Pass it in the Authorization header of every request that requires authentication: 
Authorization: Bearer <token>
The middleware extracts and verifies the token on every protected route. If the header is missing, malformed, or the token has expired, the server responds with 401 Unauthorized.

​
Obtaining a token

Call POST /api/auth/login with valid credentials. The response body contains a single token field: 
{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }
Tokens are signed with JWT_SECRET (set via environment variable) and expire after 7 days.

​
Example authenticated request

curl -X GET http://localhost:3000/api/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Public vs. Protected Endpoints

EndpointMethodAuth Required
/api/auth/registerPOSTNo
/api/auth/loginPOSTNo
/api/users/meGETYes
/api/usersGETYes
/api/messagesPOSTYes
/api/messagesGETYes
/api/messages/:userIdGETYes

​
Error Responses

All errors follow a consistent shape with a single human-readable message field: 
{ "message": "Descriptive error string." }
Status CodeMeaning
400 Bad RequestMissing, invalid, or malformed request fields
401 UnauthorizedNo token, invalid token, or wrong credentials
404 Not FoundThe requested resource does not exist
409 ConflictA unique constraint was violated (e.g. duplicate username or email)
500 Internal Server ErrorAn unexpected server-side failure occurred
The message string in a 401 response is intentionally generic ("Unauthorized." or "Invalid email or password.") to avoid leaking information about which credential was wrong.

​
Explore the API

Auth

Register a new account or log in to obtain a JWT.

Users

Fetch your own profile or list all other users in the app.

Messages

Send messages and retrieve conversation history.

Build docs developers (and LLMs) love

Get started for freeTalk to us