API Reference

API Reference

The full HTTP surface camelid serve exposes on 127.0.0.1:8181: OpenAI-compatible generation, the Responses API, embeddings and reranking, model and catalog management, runtime controls, Workspace, a partial llama-server compatibility layer, Prometheus metrics, and the routes that still fail closed. Routes are extracted from src/api/. Base URL below is http://127.0.0.1:8181.

Contents

• Health & discovery
• OpenAI-compatible generation
• Responses & Conversations
• Embeddings & reranking
• Model management
• Model catalog
• Runtime & telemetry
• Workspace & agent
• llama-server compatibility
• Fail-closed routes
• Authentication

Note

Camelid exposes a narrow but real OpenAI-compatible subset. Unsupported fields and routes return typed errors rather than fake output. /api/capabilities mirrors the Compatibility & Evidence row for row and is the machine-readable answer to what this build supports right now.

Health & discovery

Method	Path	Purpose
GET	/health	Liveness probe.
GET	/v1/health	OpenAI-style health probe; reports loaded_now, generation_ready, and vision_ready.
GET	/v1/models	List loaded model(s), with llama-server-style public meta and no local paths.
GET	/v1/models/:model	Metadata for one loaded model.
GET	/api/capabilities	Typed capability + model_compatibility rows; the machine-readable mirror of the support ledger.
GET	/api/execution-plan, /execution-plan	The live execution plan — selected_backend, prefill_path, decode_path.

curl -s http://127.0.0.1:8181/v1/health
curl -s http://127.0.0.1:8181/v1/models
curl -s http://127.0.0.1:8181/api/capabilities
curl -s http://127.0.0.1:8181/api/execution-plan

Frontend chat readiness requires both exact-row support in /api/capabilities and /v1/health reporting loaded_now=true generation_ready=true. Route presence alone never unlocks readiness.

OpenAI-compatible generation

Method	Path	Purpose
POST	/v1/chat/completions	Chat completion; "stream": true for SSE. Greedy with "temperature": 0.
POST	/v1/completions	Text completion; supports "stream": true.

curl -s http://127.0.0.1:8181/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Llama 3.2 3B Instruct",
    "messages": [{"role": "user", "content": "Say hello in one sentence."}],
    "max_tokens": 64,
    "temperature": 0
  }'

Supported on these routes:

• SSE streaming. stream_options.include_usage appends one terminal chunk (choices: []) carrying a usage object whose token counts equal the non-streaming response for the same request.
• Structured output. response_format, json_schema, and grammar compile through LLGuidance against the loaded tokenizer's exact byte vocabulary. Unsupported schemas fail closed before generation. Streaming constrained generation and raw-completion constraints remain unsupported.
• Multi-choice. 1–8 independent, reproducibly seeded choices. Not with streaming, receipts, or logprobs.
• Logprobs. OpenAI-shaped logprobs/top_logprobs on chat; the parallel-array shape on legacy completions. Non-streaming, single choice.
• Local function tools, on rows marked tool_capable in the ledger.
• Vision. The hash-pinned Bonsai 27B Q1/Q2 rows accept one local PNG/JPEG image_url data part when /v1/health reports vision_ready=true. Remote URLs, multiple images, and audio/video are typed-unsupported.

Note

Parity receipts: add "camelid_receipt": true to a greedy request to emit a sealed, independently re-verifiable record of the run (camelid verify-receipt). Sampled runs are stamped reproducible: false. A receipt verifies one request — it never changes the support ledger. See RECEIPTS.md.

Responses & Conversations

The OpenAI Responses API is supported as a stateless subset, mapped onto the same evidence-gated generation core.

Method	Path	Purpose
POST	/v1/responses	Create a response. String/message input, instructions, local function tools, typed SSE events, usage, cancellation, text/JSON formats.
GET · DELETE	/v1/responses/:id	Fetch or delete a stored response.
POST	/v1/conversations	Create a conversation.
GET · POST · DELETE	/v1/conversations/:id	Fetch, update, or delete a conversation.
GET · POST	/v1/conversations/:id/items	List or append conversation items.
GET · DELETE	/v1/conversations/:id/items/:item_id	Fetch or delete one item.

Manual function_call / function_call_output continuation items are supported. previous_response_id, server-side conversation threading into generation, store: true, background mode, hosted built-in tools, and multimodal input remain typed-unsupported. Optional local SQLite storage backs the stored objects.

Embeddings & reranking

Supported for the exact Nomic v1.5 Q8_0 row.

Method	Path	Purpose
POST	/v1/embeddings, /embeddings, /embedding	One string or a bounded batch → OpenAI-compatible float embeddings plus exact tokenizer usage.
POST	/v1/rerank, /v1/reranking, /rerank, /reranking	Stable cosine-similarity ranking with Nomic query/document prefixes.

Base64/token-id inputs, generic encoders, cross-encoder classifier ranking, GPU execution, and family-wide compatibility are typed-unsupported. Contract: docs/architecture/EMBEDDINGS.md.

Model management

Method	Path	Purpose
POST	/api/models/load	Load a GGUF by path; fails closed if the row is unsupported.
POST	/api/models/unload	Unload the current model.
POST	/api/models/inspect	Inspect a GGUF without loading it.
GET	/api/models/current	Currently loaded model + readiness.
GET	/api/models/metadata	Parsed GGUF metadata for the loaded model.
GET · POST	/api/models/verify	Verification status / verify the current model.
GET · POST	/api/models/default	Read or set the default model.
GET	/api/models/local	Scan the models directory for local GGUFs.
POST	/api/models/local/delete	Delete a local model file.
GET	/api/models/tokenizer	Loaded tokenizer info.
POST	/api/models/tokenizer/encode	Encode text → token ids.
POST	/api/models/tokenizer/decode	Decode token ids → text.
GET	/api/models/runnable-receipt	The runnable-lane receipt for the loaded row.
POST	/api/models/runnable-smoke	Run the runnable-lane smoke check.

curl -s http://127.0.0.1:8181/api/models/load \
  -H "Content-Type: application/json" \
  -d '{"path": "models/Llama-3.2-3B-Instruct-Q8_0.gguf"}'

curl -s http://127.0.0.1:8181/api/models/current
curl -s http://127.0.0.1:8181/api/models/tokenizer/encode \
  -H "Content-Type: application/json" -d '{"text": "hello"}'
curl -s -X POST http://127.0.0.1:8181/api/models/unload

Relative paths resolve against the models directory; absolute paths are used as given. See Installation & Platforms.

Model catalog

These back the desktop and web Models page.

Method	Path	Purpose
GET	/api/models/catalog	The curated catalog (Model Catalog).
POST	/api/models/catalog/fit	Ask whether a row fits this host — a capacity signal, never a support claim.
POST	/api/models/catalog/install	Start a catalog download.
GET	/api/models/catalog/downloads	In-flight download progress.
POST	/api/models/catalog/cancel	Cancel a download.
POST	/api/models/catalog/ack	Acknowledge a completed download.

Runtime & telemetry

Method	Path	Purpose
GET · POST	/api/runtime/gpu	Read or set GPU acceleration state live.
GET	/api/runtime/memory	Runtime memory analytics.
POST	/api/runtime/kv-cache/purge	Purge the KV cache.
GET	/api/telemetry/stream	SSE live inference telemetry; drives the UI's Inference Observatory.
GET · POST	/api/generation/sessions	List or create generation sessions.
POST	/api/generation/preflight	Validate a generation request before running it.
GET	/metrics	Prometheus text: HTTP/generation latency, failure counters, prompt/decode token totals, cache outcomes, queue/slot gauges, process RSS, CUDA VRAM.

/metrics carries no model, prompt, path, secret, or user labels, and is API-key protected when server authentication is on. It is Camelid operational telemetry — not llama-server metric-name parity, and not a throughput claim. Telemetry event schema: docs/TELEMETRY.md.

Workspace & agent

Read-only Workspace sessions over a local folder, used by the web UI's Workspace surface.

Method	Path	Purpose
GET	/api/agent/workspace/models	Models compatible with Workspace (tool_capable rows).
GET	/api/agent/workspace/browse	Browse the workspace tree.
GET	/api/agent/workspace/threads	List threads.
GET · DELETE	/api/agent/workspace/threads/:id	Fetch or delete a thread.
POST · DELETE	/api/agent/workspace/threads/:id/compact	Compact a thread, or undo compaction.
POST	/api/agent/workspace/sessions	Create a session.
GET · DELETE	/api/agent/workspace/sessions/:id	Session status, or cancel.
GET	/api/agent/workspace/sessions/:id/events	Stream session events.
POST	/api/agent/workspace/sessions/:id/messages	Send a message.
POST	/api/agent/workspace/sessions/:id/decisions	Answer an approval prompt.

Contract: docs/architecture/WORKSPACE_CLI.md. Behavior and boundaries: Interfaces.

llama-server compatibility

These mirror llama-server's shape for client expectations only. Read-only discovery is support-contract-aware, and local paths are redacted. Camelid does not copy source or claim full parity.

Method	Path	Purpose / boundary
GET	/props	Read-only server props: default generation settings, slot count, chat-template metadata. POST is unsupported.
GET	/slots	One read-only entry per admissible streaming slot, with fail_on_no_slot=1 handling. Per-slot task identity and progress are engine-wide values repeated on busy entries. POST is unsupported.
GET	/models	Partial: currently loaded Camelid models only, paths redacted.
POST	/models/load	Narrow local-path alias over /api/models/load.
POST	/tokenize	Loaded supported tokenizer only; with_pieces=true returns bounded id/piece objects.
POST	/detokenize	Loaded supported tokenizer only.
POST	/apply-template	Loaded supported template only; no-inference utility returning a prompt string.
POST	/completion	Partial non-streaming generation: maps prompt (text or token-id array) + n_predict/max_tokens + supported sampler fields + stop sequences onto Camelid's generation path. stream=true is not supported here — use /v1/completions.

curl -s http://127.0.0.1:8181/props
curl -s http://127.0.0.1:8181/tokenize -H "Content-Type: application/json" \
  -d '{"content": "hello", "with_pieces": true}'
curl -s http://127.0.0.1:8181/completion -H "Content-Type: application/json" \
  -d '{"prompt": "hello", "n_predict": 16}'

Slot lifecycle, save/restore/erase, prompt-cache visibility, cancellation metadata, router-mode cache listing, and native POST /models/unload remain unsupported.

Fail-closed routes

Registered for client compatibility but typed-unsupported — each returns a stable JSON error envelope rather than output.

Method	Path(s)	Error
POST	/v1/messages	unsupported_messages (Anthropic Messages API)
POST	/infill	unsupported_llama_server_infill
POST	/models/unload	unsupported_llama_server_models_unload
POST	/props, /slots	Unsupported — these are GET-only

Multimodal chat content outside the supported Bonsai 27B single-image path is rejected with unsupported_multimodal_content.

Important

Changed since the previous wiki: /v1/embeddings, /v1/rerank, /v1/responses, and /metrics were previously documented as fail-closed. All four are now implemented — see the sections above.

Authentication

Anonymous loopback serving is the default. A non-loopback address is refused unless you configure a key or explicitly acknowledge an externally protected deployment:

camelid serve --addr 0.0.0.0:8181 --api-key-file ./camelid-api.key

Clients send either Authorization: Bearer <key> or X-API-Key: <key>. Health and embedded same-origin UI assets stay public; API routes including /metrics require the key. The bundled browser UI does not persist or inject the server key — use an API client or an authenticating reverse proxy for authenticated remote deployments.

Full detail, plus TLS, CORS, and request limits: Configuration & Deployment.

---

Next: Interfaces · Configuration & Deployment · Reproducing Parity Audits