Skip to content
merran
GitHubInstall

Merran documentation API & integrations

The server's AI

GET
/api/settings/server/ai
curl --request GET \
  --url http://localhost:3000/api/settings/server/ai \
  --cookie merran.session_token=<merran.session_token>

Server admins only. The server’s AI keys and addresses (never the keys themselves, only their last four characters), who may use them and how much, the models they can run, every household’s spend on them this month, and the last months’.

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”

The server’s AI.

Media typeapplication/json
object
keys
required
Array<object>
object
id
required

Its id; “env:anthropic” and the like for a key set in the server’s environment.

string
provider
required
string
Allowed values: anthropic openai google openai-compatible
name
required

An address’s name.

string | null
baseUrl
required

An OpenAI-compatible address.

string | null
hint
required

The key’s last four characters. The key itself is never sent.

string | null
models
required

What it can use, from its last test.

Array<string> | null
testedAt
required
string | null format: date-time
fromEnvironment
required

Set in the server’s environment, so it can’t be changed here.

boolean
unreadable
required

Sealed with a master key the server no longer has: take it off and add it again.

boolean
credit
required

The providers don’t tell a key how much credit it has left, so it’s what someone entered, less what Merran’s spent on it since. None until entered.

object
amount
required

The credit entered, in US dollars.

number
since
required

When it was entered.

string format: date-time
spent
required

What Merran has spent on the key since.

number
left
required

About what’s left. Use of the key outside Merran isn’t counted.

number
outOfCreditAt
required

When its provider last said it’s out of credit. It’s passed over for an hour, then tried again; it clears once it works.

string | null format: date-time
lowOnCredit
required

About a fifth or less of its entered credit left.

boolean
creditCheck

Only from adding or testing a key: whether one tiny call on its cheapest model found credit (ok), none (out), or couldn’t tell (failed, with the provider’s words). Addresses aren’t checked.

object
result
required
string
Allowed values: ok out failed
message
required
string | null
policy
required

Who may use the server’s keys: serverKeysFor is admins, chosen, all, none (the server admins’ households, the chosen households, every household, or none). monthlyLimit is each household’s in US dollars on the server’s keys (null for none), and limits a household’s own instead. tasks and models are what the server’s keys cover (no models means any). householdKeys and householdAddresses say whether households may add their own keys and addresses. large and small are the models households use when they haven’t picked.

object
serverKeysFor
required
string
Allowed values: admins chosen all none
households
required
Array<string>
<= 1000 items
monthlyLimit
required
number | null
<= 100000
limits
required
object
key
additional properties
number
<= 100000
tasks
required
Array<string>
<= 10 items
Allowed values: assistant import tidy notes swaps nutrition shopping receipts discover reminders
models
required
Array<string>
<= 100 items
householdKeys
required
boolean
householdAddresses
required
boolean
large
required
string | null
<= 300 characters
small
required
string | null
<= 300 characters
models
required

The models the server’s keys can run.

Array<object>
object
ref
required

A model: “anthropic:claude-opus-5-5”, or on an address, “endpoint::llama3.1”.

string
<= 300 characters
name
required
string
size
required
string | null
Allowed values: large small
price
required

US dollars per million tokens, in and out; null when unknown, or free on an address.

array | null
source
required

Whose key runs it.

string
Allowed values: server household
providers
required
Array<string>
Allowed values: anthropic openai google
households
required

Every household, and its spend on the server’s keys.

Array<object>
object
id
required
string
name
required
string
covered
required
boolean
serverAdmin
required

A server admin is in it.

boolean
limit
required

In US dollars.

number | null
spent
required

This month, on the server’s keys.

number
near
required
boolean
usage
required
object
months
required
Array<object>
object
month
required
string
cost
required

In US dollars.

number
calls
required
number
models
required
Array<object>
object
provider
required
string
Allowed values: anthropic openai google openai-compatible
model
required
string
cost
required

In US dollars.

number
calls
required
number

Example 

{
  "keys": [
    {
      "id": "0199e8b0-5a10-7a01-8b00-000000000028",
      "provider": "anthropic",
      "name": null,
      "baseUrl": null,
      "hint": "7xQa",
      "models": [
        "claude-haiku-5-5",
        "claude-opus-5-5"
      ],
      "testedAt": "2026-10-16T17:00:00.000Z",
      "fromEnvironment": false,
      "unreadable": false,
      "credit": {
        "amount": 20,
        "since": "2026-10-01T17:00:00.000Z",
        "spent": 16.6,
        "left": 3.4
      },
      "outOfCreditAt": null,
      "lowOnCredit": true
    }
  ],
  "policy": {
    "serverKeysFor": "admins",
    "households": [],
    "monthlyLimit": null,
    "limits": {},
    "tasks": [
      "assistant",
      "import",
      "tidy",
      "notes",
      "swaps",
      "nutrition",
      "shopping",
      "receipts",
      "discover",
      "reminders"
    ],
    "models": [],
    "householdKeys": true,
    "householdAddresses": false,
    "large": null,
    "small": null
  },
  "models": [
    {
      "ref": "anthropic:claude-opus-5-5",
      "name": "Claude Opus 5.5",
      "size": "large",
      "price": [
        4,
        20
      ],
      "source": "server"
    }
  ],
  "providers": [
    "anthropic",
    "openai",
    "google"
  ],
  "households": [
    {
      "id": "0199e8b0-5a10-7a01-8b00-000000000003",
      "name": "The Johnsons",
      "covered": true,
      "serverAdmin": true,
      "limit": null,
      "spent": 1.24,
      "near": false
    }
  ],
  "usage": {
    "months": [
      {
        "month": "2026-10",
        "cost": 1.24,
        "calls": 31
      }
    ],
    "models": [
      {
        "provider": "anthropic",
        "model": "claude-opus-5-5",
        "cost": 1.24,
        "calls": 31
      }
    ]
  }
}

401

Section titled “401”

Not signed in.

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
fields
object
key
additional properties
string

Example 

{
  "error": {
    "code": "not_found",
    "message": "There's nothing here.",
    "fields": {
      "name": "Give it a name."
    }
  }
}

403

Section titled “403”

Not allowed.

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
fields
object
key
additional properties
string

Example 

{
  "error": {
    "code": "not_found",
    "message": "There's nothing here.",
    "fields": {
      "name": "Give it a name."
    }
  }
}

© 2026 Kyle Johnson. Documentation: CC BY 4.0. Merran: AGPL-3.0-or-later.