API Docs — LlamaChat

LlamaChat API

REST API for integrating LlamaChat conversations into external clients.

Authentication

All API endpoints require an X-Api-Key header. Keys are configured per consumer in appsettings.secrets.json under Consumer:ApiKeys.

X-Api-Key: your-api-key

Requests with a missing or unrecognised key receive 401 Unauthorized.

Error responses

All error responses return JSON with an error field:

{ "error": "Description of what went wrong." }

Status	Meaning
`400`	Bad request — invalid or missing fields
`401`	Missing or invalid API key
`404`	Conversation not found
`502`	LLM backend error

Endpoints

POST /api/conversations

Creates a new conversation. Conversations are scoped to the consumer identified by the API key — each consumer only has access to their own conversations.

No request body required.

Response 200 OK

{
  "id":    "64f1a2b3c4d5e6f7a8b9c0d1",
  "title": "New Conversation"
}

Field	Type	Description
id	string	Conversation ID — use in subsequent message requests
title	string	Auto-generated title; updated after the first message

Example

curl -X POST https://your-host/api/conversations \
     -H "X-Api-Key: your-api-key"

POST /api/conversations/{id}/messages

Sends a user message to a conversation and returns the assistant reply. The full conversation history is maintained and sent to the LLM on every request.

Request body

{
  "content": "What is the capital of France?"
}

Field	Type	Constraints
content	string	Required. 1–2000 characters.

Response 200 OK

{
  "role":    "assistant",
  "content": "The capital of France is Paris."
}

Example

curl -X POST https://your-host/api/conversations/64f1a2b3c4d5e6f7a8b9c0d1/messages \
     -H "X-Api-Key: your-api-key" \
     -H "Content-Type: application/json" \
     -d '{"content": "What is the capital of France?"}'

POST /api/transcription

Transcribes an audio file to text using the whisper.cpp backend. Accepts any common audio format — converted to 16 kHz mono WAV via ffmpeg before sending to whisper.

Request

Multipart form data — max 100 MB.

Field	Type	Description
audio	file	Audio file to transcribe. Supported formats: WAV, MP3, OGG, WEBM, M4A, FLAC.

Response 200 OK

{
  "text": "Hola, ¿cómo estás?"
}

Example

curl -X POST https://your-host/api/transcription \
     -H "X-Api-Key: your-api-key" \
     -F "audio=@recording.wav"

Full integration example

# 1. Create a conversation
CONV=$(curl -s -X POST https://your-host/api/conversations \
     -H "X-Api-Key: your-api-key" | jq -r '.id')

# 2. Send messages
curl -s -X POST https://your-host/api/conversations/$CONV/messages \
     -H "X-Api-Key: your-api-key" \
     -H "Content-Type: application/json" \
     -d '{"content": "Hola, ¿cómo estás?"}'

Adding a consumer key

Edit appsettings.secrets.json on the server and add an entry under Consumer:ApiKeys. The key name is an identifier for the client; the value is the secret sent in the header.

"Consumer": {
  "ApiKeys": {
    "mobile-app": "abc123...",
    "zapier":     "def456..."
  }
}

Restart the app after editing the secrets file for changes to take effect.