API reference

Quickstart

You need a ZeroLog account. The token belongs to that account; every request you make with it is billed to your balance.

1. Get your token.

   Sign in at zerolog.ch, then open /api/cli/token in the same browser. Copy the value of token. If you use ZeroLog Code, zerolog login fetches it for you.

   Your token, in the shell

   export ZEROLOG_TOKEN="mhc-1042-REPLACE_WITH_YOUR_TOKEN"

2. Check that it works.

   A 200 with a model list means the token is valid. A 401 means it is not.

   List models

   curl -sS https://zerolog.ch/api/cli/v1/models \
     -H "Authorization: Bearer $ZEROLOG_TOKEN"

3. Send a request.

   Any model your account may use works here. Without model, the catalogue default is used.

   Ask a model

   curl -sS https://zerolog.ch/api/cli/v1/chat/completions \
     -H "Authorization: Bearer $ZEROLOG_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"model":"featherless/google/gemma-4-31b-it","messages":[{"role":"user","content":"Write a haiku about Swiss trains."}]}'

The endpoint speaks the OpenAI wire format, so OpenAI client libraries work if you set the base URL:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://zerolog.ch/api/cli/v1",
    api_key=os.environ["ZEROLOG_TOKEN"],
)
reply = client.chat.completions.create(
    model="featherless/google/gemma-4-31b-it",
    messages=[{"role": "user", "content": "Write a haiku about Swiss trains."}],
)
print(reply.choices[0].message.content)

Authentication

Model endpoints take your client token in one of two headers:

• Authorization: Bearer mhc-…, which most clients send;
• x-api-key: mhc-…, for clients that send keys this way. If both are present, x-api-key wins.

The token has the form mhc-<account>-<secret>. It is derived from your account, does not expire, and stops working when the account is disabled. Treat it like a password: anyone holding it can spend your balance. You cannot revoke it on your own in the app yet. If it leaks, write to info@zerolog.ch and we revoke it.

Webhooks carry their own token in the URL (mhw_… or mhin_…). It is shown once when you create the webhook, stored only as a hash, and revoked by deleting the webhook. See Webhooks.

Errors

Model endpoints answer errors in the OpenAI form: {"error": {"message": "…", "type": "…", "code": "…"}}. code is set when there is a machine-readable reason. A missing or wrong token gets {"type": "error", "error": {"type": "authentication_error", …}}. Webhooks answer {"error": "…", "code": "…"}.

A provider's 401 or 403 concerns ZeroLog's key, not yours, so you get 503 instead and your client keeps its token. When a provider answered, its status is in error.upstream_status and in the X-ZeroLog-Upstream-Status header.

Fallback instead of failure. If the model you asked for fails, ZeroLog may answer with another one. You can tell from the X-ZeroLog-Served-Model, X-ZeroLog-Rerouted-From and X-ZeroLog-Model-Notice headers, and from a one-line notice at the start of the answer. Send X-ZeroLog-Reroute: off when you would rather get the error.

Rate limits and sizes

• Model endpoints have no fixed request rate. What limits you is your balance (402) and the provider's own rate limits (429 with Retry-After when the provider sends it). Request bodies may be up to 32 MB.
• Goal webhooks: 1 to 60 triggers per minute (default 6) and 1 to 1000 per day (default 100), set per webhook. Bodies up to 32 kB.
• Inject webhooks: 1 to 120 events per minute (default 60), set per webhook. Bodies up to 256 kB.

Webhook limits answer 429 with retry_after_s in the body. Back off for that long.

Pagination

None of the public endpoints page their results. GET /api/cli/v1/models returns its whole list in one response.

Streaming

Send "stream": true to receive the answer as text/event-stream. Each data: line is one chunk in OpenAI form; the stream ends with data: [DONE]. ZeroLog asks the provider for a final chunk with usage. If you close the connection early, ZeroLog stops the provider request and bills what was produced up to then.

data: {"id":"chatcmpl-example-2","object":"chat.completion.chunk","model":"featherless/google/gemma-4-31b-it","choices":[{"index":0,"delta":{"content":"Lake Geneva"},"finish_reason":null}]}

data: {"id":"chatcmpl-example-2","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":21,"completion_tokens":9,"total_tokens":30}}

data: [DONE]

Webhooks and WebSockets

ZeroLog does not call your servers. The two webhooks are inbound: you give their URL to GitHub, Stripe, Zapier or your own service, and they call ZeroLog. A goal webhook starts the goal run it was created for. An inject webhook writes each event as a JSON line into /work/.webhooks/incoming.jsonl in its container, where an agent can read it. Both accept only POST; any other method gets 405, so a link opened in a browser starts nothing. Before an event is stored, Authorization, Cookie and other credential headers are replaced by ‹redacted›.

There are no public WebSocket endpoints. Terminals, the browser extension and the desktop link use WebSockets inside the signed-in app; they are not part of this API.

Endpoints

Every endpoint below is also in /openapi.json, so you can load it into Postman, Insomnia or a code generator. The examples use invented data.

curl -sS "https://zerolog.ch/api/cli/v1/models" \
  -H "Authorization: Bearer $ZEROLOG_TOKEN"

// Node 18+ as an ES module (example.mjs), or a browser console
const res = await fetch(`https://zerolog.ch/api/cli/v1/models`, {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.ZEROLOG_TOKEN}` },
});
console.log(res.status, await res.json());

import os, requests

res = requests.get(
    f"https://zerolog.ch/api/cli/v1/models",
    headers={"Authorization": f"Bearer {os.environ['ZEROLOG_TOKEN']}"},
)
print(res.status_code, res.json())

{
  "object": "list",
  "data": [
    {
      "id": "featherless/google/gemma-4-31b-it",
      "object": "model",
      "created": 0,
      "owned_by": "zerolog"
    }
  ]
}

curl -sS -X POST "https://zerolog.ch/api/cli/v1/chat/completions" \
  -H "Authorization: Bearer $ZEROLOG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"featherless/google/gemma-4-31b-it","messages":[{"role":"user","content":"Write a haiku about Swiss trains."}]}'

// Node 18+ as an ES module (example.mjs), or a browser console
const res = await fetch(`https://zerolog.ch/api/cli/v1/chat/completions`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.ZEROLOG_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "model": "featherless/google/gemma-4-31b-it",
    "messages": [
      {
        "role": "user",
        "content": "Write a haiku about Swiss trains."
      }
    ]
  }),
});
console.log(res.status, await res.json());

import os, requests

res = requests.post(
    f"https://zerolog.ch/api/cli/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['ZEROLOG_TOKEN']}"},
    json={
      "model": "featherless/google/gemma-4-31b-it",
      "messages": [
        {
          "role": "user",
          "content": "Write a haiku about Swiss trains."
        }
      ]
    },
)
print(res.status_code, res.json())

{
  "id": "chatcmpl-example-1",
  "object": "chat.completion",
  "created": 1793700000,
  "model": "featherless/google/gemma-4-31b-it",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Rails through the pass\nsnow on the windows, warm tea\nthe clock is on time"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 16,
    "completion_tokens": 19,
    "total_tokens": 35
  }
}

{
  "token": "mhc-1042-REPLACE_WITH_YOUR_TOKEN",
  "base_url": "https://zerolog.ch/api/cli/v1",
  "note": "Bearer token for the zerocode terminal client. Pick the model in zerocode; it is sent as body.model."
}

curl -sS -X POST "https://zerolog.ch/api/hook/$ZEROLOG_HOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Deploy finished for commit 3f2a91c. Check the release notes."}'

// Node 18+ as an ES module (example.mjs), or a browser console
const res = await fetch(`https://zerolog.ch/api/hook/${process.env.ZEROLOG_HOOK_TOKEN}`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "prompt": "Deploy finished for commit 3f2a91c. Check the release notes."
  }),
});
console.log(res.status, await res.json());

import os, requests

res = requests.post(
    f"https://zerolog.ch/api/hook/{os.environ['ZEROLOG_HOOK_TOKEN']}",
    json={
      "prompt": "Deploy finished for commit 3f2a91c. Check the release notes."
    },
)
print(res.status_code, res.json())

{
  "job_id": 5821,
  "status_url": "/api/jobs/5821"
}

curl -sS -X POST "https://zerolog.ch/api/inject/$ZEROLOG_INJECT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ref":"refs/heads/main","after":"3f2a91c","repository":{"full_name":"example-org/example-repo"}}'

// Node 18+ as an ES module (example.mjs), or a browser console
const res = await fetch(`https://zerolog.ch/api/inject/${process.env.ZEROLOG_INJECT_TOKEN}`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "ref": "refs/heads/main",
    "after": "3f2a91c",
    "repository": {
      "full_name": "example-org/example-repo"
    }
  }),
});
console.log(res.status, await res.json());

import os, requests

res = requests.post(
    f"https://zerolog.ch/api/inject/{os.environ['ZEROLOG_INJECT_TOKEN']}",
    json={
      "ref": "refs/heads/main",
      "after": "3f2a91c",
      "repository": {
        "full_name": "example-org/example-repo"
      }
    },
)
print(res.status_code, res.json())

{
  "ok": true,
  "status": "stored",
  "path": "/work/.webhooks/incoming.jsonl"
}

No endpoint matches. Clear the filter to see all 5.

Trying requests

This page has no "Try it" button. A live test would need a real token, and every call is billed, so a button in a public page would either spend someone's balance or need a sandbox account that does not exist yet. Copy the examples instead and run them with your own token.

What this API does not cover

The rest of /api/ belongs to the ZeroLog web app. It needs a browser session, changes without notice and is not meant for scripts. If you need something from there as a stable endpoint, tell us at info@zerolog.ch. The Monitoring API is a separate public API with its own specification; both are listed in /.well-known/api-catalog.

The specification is checked against the server code on every deploy: a public endpoint that changes without its documentation stops the deploy.

Something missing or wrong here? Say so. The documentation is part of the product, not an afterthought. All topics · Security · Status · X · Legal & privacy · Home