API overview

The Mortar API is served by the data plane: the gateway that runs the model, whether in Mortar's cloud or in yours. The chat-completions and model endpoints follow the OpenAI API; the rest are Mortar's own.

Base URL

https://api.mortar.one/v1

The health and readiness checks are the only endpoints outside /v1. With Bring Your Own Cloud, your deployment has its own base URL inside your network, and every path on this page works the same there.

Endpoints

Authentication

Send an API key as a bearer token on every endpoint marked above. Authentication covers creating and revoking keys.

Authorization: Bearer $MORTAR_API_KEY

Requests

Send request bodies as JSON with Content-Type: application/json. A body in any other format is refused with 415. Bodies are limited to 1 MiB; a larger one is refused with 413.

Successful JSON responses carry a weak ETag. Send it back in If-None-Match and Mortar answers 304 Not Modified with no body when nothing changed. JSON responses of 512 bytes or more are gzip-compressed when you send Accept-Encoding: gzip; event streams are never compressed.

Request IDs

Every response carries an X-Request-Id header. Send your own X-Request-Id and Mortar echoes it back; otherwise it generates one. Log it next to your own request: it's the fastest way to find a request when you contact support.

Errors

Errors use the same envelope as the OpenAI API, so SDK error handling works unchanged.

{
  "error": {
    "message": "The model `gpt-4o` does not exist.",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

message is written for a person. Branch on code where there is one, otherwise on the HTTP status; code is present only when there's something specific you can do about the error.

Status codes

Rate limits

Each API key may send 600 requests per minute to a data-plane replica. Requests without a key are counted by client IP address instead. The window is fixed: it starts with your first request and resets one minute later.

Over the limit, Mortar answers 429 with a Retry-After: 60 header. Wait that long before retrying.

{
  "error": {
    "message": "Too many requests. Slow down and try again shortly.",
    "type": "rate_limit"
  }
}

The cost analyser has a tighter limit of its own: 30 requests per minute, counted the same way.

When Mortar proxies to a model server that is itself rate limiting, the response is 429 with type rate_limit_error and code upstream_rate_limited, and Retry-After carries the model server's own value when it sent one.

OpenAI compatibility

Point an OpenAI SDK at the base URL above and chat completions work unchanged, with these differences:

• Streaming is the default. A request without stream gets an event stream. Pass stream: false for a single JSON response.
• Supported fields. Mortar reads model, messages, stream, stream_options.include_usage, max_tokens, user, tools, tool_choice and parallel_tool_calls, and the tool calls and tool results messages carry. Other request fields, such as temperature, are accepted and ignored.
• Text only. Message content may be a string or an array of parts; only the text parts are used.
• Default model. Leave out model and the request goes to Qwen/Qwen2.5-7B-Instruct.
• Prompt optimizer. Mortar can remove insignificant whitespace from JSON in system prompts and tool results before it processes a request. Unless your deployment turns it on, or off, it runs in shadow mode: it measures what it would remove and leaves the prompt unchanged. The X-Mortar-Optimizer response header reports what it did or would have done, and X-Mortar-Optimize: off opts a request out. See chat completions.
• Two OpenAI endpoints. Mortar implements POST /v1/chat/completions and GET /v1/models. Calls to other OpenAI endpoints, such as embeddings, return 404.