Quavern · Marl

Marl API

An OpenAI-compatible chat endpoint. Point an official OpenAI SDK at api.quavern.ai/v1 and it works: streaming, tool calling, reasoning effort, live web search.

Authentication

Every request carries a bearer token. Create one at my.quavern.com/account/tokens: personal API tokens need a plan with API access (Pro and above); organisation service tokens are issued by a Team or Enterprise administrator.

Tokens are shown once, stored hashed, scoped, and revocable at any time from the same page.

Works with the OpenAI SDKs

# Python — pip install openai
from openai import OpenAI

client = OpenAI(
    base_url="https://api.quavern.ai/v1",
    api_key="qv_…",
)
reply = client.chat.completions.create(
    model="marl",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)

// JavaScript — npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.quavern.ai/v1",
  apiKey: "qv_…",
});

Endpoints

Route	What it does
`POST /v1/chat/completions`	Chat completions, streamed or not. Supports `tools` (function calling), `reasoning_effort`, and `web_search`.
`GET /v1/models`	The model aliases your token can request. The canonical id is `marl`.
`GET /v1/usage`	Your two rolling credit windows (5 hours and one week): used, limit, remaining, reset time.

Reasoning effort

Send reasoning_effort as low, medium, high or max. The service clamps it to your plan's ceiling instead of failing, so the same request works on every plan. Higher effort costs more credits.

Live web search

Send web_search as off, auto or on (paid plans). With auto, the model searches only when the question needs it.

Pages the model consulted come back as a top-level citations array of URLs — on the response object, and on a dedicated chunk when streaming. Each search source used is billed as additional usage credits, reported in usage.num_sources_used.

Limits

Usage is measured in credits over two rolling windows (5 hours and one week), shared with your Marl chat and Marl Code use. When a window is exhausted the API answers 429 with code insufficient_quota; GET /v1/usage tells you when it resets. Exact remaining amounts are always visible at my.quavern.com/account/usage.

Errors

Developer endpoints answer with the OpenAI error shape: {"error": {"message", "type", "code", "param"}}. Other Quavern endpoints use a structured error with a stable support code (APIE1-1001 style); quote that code when writing to support.

Headless and CI

Marl Code runs non-interactively with marl exec --json "…": one prompt in, one JSON document out (result, usage, citations, error), with stable exit codes. The Marl Code GitHub Action wraps this for pull-request review and triage jobs.