Keys

Moth DocsReference

POSThttps://api.runmoth.si/v1/keys

Makes, lists, changes and revokes API keys, each with its own cap, expiry and models.

curl https://api.runmoth.si/v1/keys \
  -H "Authorization: Bearer $MOTH_SESSION" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Server", "daily_cap_usd": 20, "cap_period": "month", "models": null }'
Response
{
  "id": "key_0b6f3c1e-8d2a-4f7e-9a51-2c4d6e8f0a1b",
  "name": "Server",
  "prefix": "moth_Xq4",
  "daily_cap_usd": "20.000000",
  "cap_period": "month",
  "cap_spent_usd": "0.000000",
  "expires_at": null,
  "models": null,
  "shield": false,
  "webhook_url": null,
  "webhook_secret": null,
  "created_at": "2026-10-30T09:00:00Z",
  "last_used_at": null,
  "key": "moth_Xq4…"
}

Keys are managed with a wallet session from sign-in, never with a key, so one key can't make another. Keys and their limits explains each limit.

Body

namestring

Up to 60 characters.

daily_cap_usdnumber or null

The spend cap in dollars over cap_period, or null for none. The name is older than the periods.

cap_periodstring

day, week or month, each reset in UTC. day by default.

expires_atstring or null

An ISO time with its zone, such as 2026-12-31T00:00:00Z, up to five years ahead, or null for never.

modelsarray or null

Between 1 and 64 model IDs the key may use, or null for every model.

shieldboolean

Shield on every call of the key. Off by default.

webhook_urlstring or null

An https URL on a public address that Moth posts job events to, or null for none.

webhook_secret is the secret the key's job events are signed with. It is made the first time a URL is set and kept when the URL changes or is removed.

It answers 201 with the key, and key holds the whole secret only in this reply. Every field is optional. An empty body, or one that isn't valid JSON, makes a key with no cap, every model and no expiry, and unknown fields are ignored, so check daily_cap_usd, models and expires_at in the reply.

The other key endpoints

RequestWhat it does
GET /keysLists the account's keys, newest first, expired ones included, with cap_spent_usd for the current window
PATCH /keys/{id}Changes any of the fields above, leaving out what you don't send
DELETE /keys/{id}Revokes the key at once

Errors

400invalid_request_errorA field isn't valid, a model isn't in the catalog, or the account already holds 20 keys
401authentication_errorNo live wallet session was sent, and a key can't be used here
404not_found_errorPATCH or DELETE names no key on this account
429rate_limit_errorToo many reads from the key, so wait for retry-after