Merran documentation API & integrations
Change who may use the server's AI keys
const url = 'http://localhost:3000/api/settings/server/ai/policy';const options = { method: 'PUT', headers: { cookie: 'merran.session_token=<merran.session_token>', 'Content-Type': 'application/json' }, body: '{"serverKeysFor":"admins","households":[],"monthlyLimit":5,"limits":{},"tasks":["assistant","import","tidy","notes","swaps","nutrition","shopping","receipts","discover","reminders"],"models":[],"householdKeys":true,"householdAddresses":false,"large":null,"small":null}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url http://localhost:3000/api/settings/server/ai/policy \ --header 'Content-Type: application/json' \ --cookie merran.session_token=<merran.session_token> \ --data '{ "serverKeysFor": "admins", "households": [], "monthlyLimit": 5, "limits": {}, "tasks": [ "assistant", "import", "tidy", "notes", "swaps", "nutrition", "shopping", "receipts", "discover", "reminders" ], "models": [], "householdKeys": true, "householdAddresses": false, "large": null, "small": null }'Server admins only. Which households the server’s keys cover, each one’s monthly limit on them, the tasks and models they cover, and whether households may add keys and addresses of their own. Households that are gone are dropped.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”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
object
Example
{ "serverKeysFor": "admins", "households": [], "monthlyLimit": 5, "limits": {}, "tasks": [ "assistant", "import", "tidy", "notes", "swaps", "nutrition", "shopping", "receipts", "discover", "reminders" ], "models": [], "householdKeys": true, "householdAddresses": false, "large": null, "small": null}Responses
Section titled “Responses”Saved.
object
object
Its id; “env:anthropic” and the like for a key set in the server’s environment.
An address’s name.
An OpenAI-compatible address.
The key’s last four characters. The key itself is never sent.
What it can use, from its last test.
Set in the server’s environment, so it can’t be changed here.
Sealed with a master key the server no longer has: take it off and add it again.
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
The credit entered, in US dollars.
When it was entered.
What Merran has spent on the key since.
About what’s left. Use of the key outside Merran isn’t counted.
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.
About a fifth or less of its entered credit left.
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
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
object
The models the server’s keys can run.
object
A model: “anthropic:claude-opus-5-5”, or on an address, “endpoint:
US dollars per million tokens, in and out; null when unknown, or free on an address.
Whose key runs it.
Every household, and its spend on the server’s keys.
object
A server admin is in it.
In US dollars.
This month, on the server’s keys.
object
object
In US dollars.
object
In US dollars.
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 } ] }}Not signed in.
object
object
object
Example
{ "error": { "code": "not_found", "message": "There's nothing here.", "fields": { "name": "Give it a name." } }}Not allowed.
object
object
object
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.