AFM is OpenAI-compatible where that buys client interoperability, and explicit where local runtimes behave differently. This reference separates compatible fields, AFM extensions, Apple-native routes, and backend-conditional behavior.
Connection contract
| Concern | Behavior |
|---|---|
| Default base URL | http://127.0.0.1:9999 |
| Request bodies | JSON unless the endpoint explicitly accepts files; UTF-8 is assumed. |
| Authentication | No application-level authentication is added to ordinary local endpoints. Loopback is the default trust boundary; network exposure is an operator decision. |
| Correlation | Send X-Request-ID or OpenAI-Request-ID. AFM echoes both, or mints req_<uuid12>. |
| Streaming | text/event-stream; each event uses data: <json> and the stream closes with data: [DONE]. |
| Payload ceilings | Chat and batch collection allow 100 MB; narrower Apple and tokenizer endpoints enforce smaller route-specific limits. |
Contract guides
Chat completions
Every accepted field, precedence rule, response extension, and a complete request.
Streaming
SSE event order, tool deltas, usage, cancellation, and profiling events.
Operations
Discovery, token budgeting, batch jobs, health, metrics, and runtime schemas.
Errors
Correlation IDs, status codes, retry rules, and backend availability.
Route matrix
Availability describes route registration and backend requirements, not a remote service guarantee. Apple framework availability and model capabilities are still checked at request time.
| Method | Path | Contract | Availability | Purpose |
|---|---|---|---|---|
| POST | /v1/chat/completions | OpenAI-compatible | Every AFM server | Chat, SSE, tools, reasoning, structured output, and logprobs |
| GET | /v1/models | OpenAI-compatible | Every AFM server | Loaded chat model, gateway models, and Apple embedding catalog |
| POST | /v1/embeddings | OpenAI-compatible | Every AFM server | Apple NaturalLanguage embeddings, loaded lazily |
| POST | /v1/vision/ocr | AFM Apple-native | Supported macOS releases | OCR, document tables, barcodes, PDFs, and recognized subjects |
| POST | /v1/audio/transcriptions | OpenAI-shaped | macOS 13+ | On-device speech recognition |
| POST | /v1/audio/speech | OpenAI-shaped | macOS 13+ | Speech synthesis using installed Apple voices |
| GET | /v1/audio/voices | AFM Apple-native | macOS 13+ | Discover installed synthesis voices |
| POST | /v1/tokenize | vLLM-compatible | MLX tokenizer loaded | Token IDs, count, and known context limit |
| POST | /v1/count_tokens | Anthropic-shaped | MLX tokenizer loaded | Input token count |
| POST | /v1/batch/completions | AFM extension | MLX batch service | Multiplex up to 64 completions over one SSE connection |
| POST | /v1/chat/completions/{id}/cancel | AFM extension | Every AFM server | Cooperatively cancel an in-flight generation |
| GET | /metrics | Prometheus | Every AFM server | Queue, token, throughput, timing, and connection metrics |
| GET | /health | AFM operations | Every AFM server | Liveness and build response |
| GET | /openapi.json | OpenAPI 3.1 | Every AFM server | The running binary's compact API description |
| GET | /docs | Scalar UI | Every AFM server | Interactive reference served by the running process |
MLX-only file and batch routes
When AFM owns the concrete MLX batch service, it also registers POST /v1/files, GET /v1/files/{file_id}, GET /v1/files/{file_id}/content, DELETE /v1/files/{file_id}, POST /v1/batches, GET /v1/batches, GET /v1/batches/{batch_id}, and POST /v1/batches/{batch_id}/cancel. These jobs accept JSONL lines targeting /v1/chat/completions.
How to read this contract
- Use
GET /v1/modelsto discover what the process advertises now. - Use the hosted OpenAPI document for client generation and planning.
- Use the human pages for precedence, conditional behavior, and operational caveats that schemas cannot express well.
- Use the running process's
/openapi.jsonto confirm the bundled contract for that binary.