API Documentation

Quick Start for Mobile Apps

1. Authentication

The API uses Sanctum token-based authentication. To get started:

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "your-password",
  "device_name": "My iPhone"
}

Response:

{
  "data": {
    "token": "1|abc123...",
    "token_type": "Bearer",
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "[email protected]"
    }
  }
}

Use the token in subsequent requests:

Authorization: Bearer 1|abc123...

2. Check Credentials

Before using chat, verify the user has API credentials configured:

GET /api/v1/auth/me

// Check response.data.flags.has_credentials

3. Send Messages

// Create conversation
POST /api/v1/conversations
{ "title": "My Chat" }

// Send message
POST /api/v1/conversations/{id}/messages
{
  "content": "Hello, how are you?",
  "model": "openai/gpt-4o-mini"
}

API Endpoints

Authentication

Method	Endpoint	Description
POST	/api/v1/auth/login	Login and get token
POST	/api/v1/auth/logout	Revoke current token
POST	/api/v1/auth/token	Issue named token
GET	/api/v1/auth/me	Get current user profile

Preferences

Method	Endpoint	Description
GET	/api/v1/preferences	Get user preferences
PUT	/api/v1/preferences	Update preferences

Conversations

Method	Endpoint	Description
GET	/api/v1/conversations	List conversations
POST	/api/v1/conversations	Create conversation
GET	/api/v1/conversations/{id}	Get conversation with messages
PUT	/api/v1/conversations/{id}	Update conversation
DELETE	/api/v1/conversations/{id}	Delete conversation
POST	/api/v1/conversations/{id}/pin	Pin conversation
POST	/api/v1/conversations/{id}/unpin	Unpin conversation
POST	/api/v1/conversations/{id}/regenerate	Regenerate last response

Messages

Method	Endpoint	Description
GET	/api/v1/conversations/{id}/messages	List messages
POST	/api/v1/conversations/{id}/messages	Send message
GET	/api/v1/conversations/{id}/stream	Stream response (SSE)
DELETE	/api/v1/messages/{id}	Delete message

Response Format

All responses follow a consistent envelope format:

Success

{
  "data": { ... },
  "meta": {
    "pagination": { ... }
  }
}

Error

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message",
    "details": { ... }
  }
}

Error Codes

Code	HTTP	Description
INVALID_CREDENTIALS	401	Wrong email/password
UNAUTHENTICATED	401	No/invalid token
FORBIDDEN	403	Not authorized
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	422	Invalid input
CREDENTIALS_REQUIRED	428	API keys not configured

Idempotency

For POST/PUT/PATCH requests, include an Idempotency-Key header to prevent duplicate operations:

Idempotency-Key: unique-request-id-123

Rate Limiting

API requests are limited to 60 requests per minute per user. Rate limit headers are included in responses:

• X-RateLimit-Limit: Maximum requests per window
• X-RateLimit-Remaining: Remaining requests
• Retry-After: Seconds until reset (when limited)

---

Web UI Features

Voice Dictation

The web chat interface includes a voice dictation feature that uses your browser's built-in speech recognition (Web Speech API).

How to Use

1. Click the microphone icon next to the message input
2. Allow microphone access when prompted by your browser
3. Speak clearly - your speech will be transcribed in real-time
4. Click the stop button (square icon) when done
5. The transcribed text will appear in the message input, ready to send

Language Selection

Use the language dropdown next to the mic button to select your dictation language. Available options include:

• English (US) - en-US
• Spanish (Colombia) - es-CO
• Spanish (Spain) - es-ES
• Portuguese (Brazil) - pt-BR
• French - fr-FR
• German - de-DE

Your language preference is saved locally and remembered across sessions.

Troubleshooting

Issue	Solution
"Microphone access denied"	Click the lock/info icon in your browser's address bar and enable microphone permissions
"No speech detected"	Speak louder or check your microphone is working
"Network error"	Check your internet connection (speech recognition requires connectivity)
"Not supported" message	Try using Chrome or Edge browser
Button is disabled	Ensure you're accessing the site via HTTPS