Merran documentation API & integrations
The household's AI
const url = 'http://localhost:3000/api/households/current/ai';const options = { method: 'GET', headers: {cookie: 'merran.session_token=<merran.session_token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url http://localhost:3000/api/households/current/ai \ --cookie merran.session_token=<merran.session_token>Anyone in the household. For each AI task, the model and whose key pays, the household’s or the server’s, or why there’s none; this month’s spend against the limits; its own keys and addresses (only their last four characters); the models it can pick; and what it’s spent by month, task and person.
Authorizations
Section titled “Authorizations”Responses
Section titled “Responses”The household’s AI.
object
object
For each task, the model and whose key, or why none.
object
object
In US dollars.
In US dollars.
object
In US dollars.
In US dollars.
The keys it relies on, its own and the server’s, that are out of credit or running low.
object
About what’s left, when credit was entered.
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
object
A model: “anthropic:claude-opus-5-5”, or on an address, “endpoint:
A model: “anthropic:claude-opus-5-5”, or on an address, “endpoint:
A model for a task of its own.
object
A model: “anthropic:claude-opus-5-5”, or on an address, “endpoint:
A model: “anthropic:claude-opus-5-5”, or on an address, “endpoint:
A model: “anthropic:claude-opus-5-5”, or on an address, “endpoint:
A model: “anthropic:claude-opus-5-5”, or on an address, “endpoint:
A model: “anthropic:claude-opus-5-5”, or on an address, “endpoint:
A model: “anthropic:claude-opus-5-5”, or on an address, “endpoint:
A model: “anthropic:claude-opus-5-5”, or on an address, “endpoint:
A model: “anthropic:claude-opus-5-5”, or on an address, “endpoint:
A model: “anthropic:claude-opus-5-5”, or on an address, “endpoint:
A model: “anthropic:claude-opus-5-5”, or on an address, “endpoint:
A monthly limit on its own keys, in US dollars; null for none.
Tidy up each recipe it imports, in the background, with the suggestions left in the Review queue.
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.
object
object
In US dollars.
In US dollars.
object
In US dollars.
object
In US dollars.
Example
{ "status": { "available": true, "tasks": { "assistant": { "ok": true, "ref": "anthropic:claude-opus-5-5", "source": "server" }, "import": { "ok": true, "ref": "anthropic:claude-opus-5-5", "source": "server" }, "tidy": { "ok": true, "ref": "anthropic:claude-opus-5-5", "source": "server" }, "notes": { "ok": true, "ref": "anthropic:claude-opus-5-5", "source": "server" }, "swaps": { "ok": true, "ref": "anthropic:claude-opus-5-5", "source": "server" }, "nutrition": { "ok": true, "ref": "anthropic:claude-opus-5-5", "source": "server" }, "shopping": { "ok": true, "ref": "anthropic:claude-opus-5-5", "source": "server" }, "receipts": { "ok": true, "ref": "anthropic:claude-opus-5-5", "source": "server" }, "discover": { "ok": true, "ref": "anthropic:claude-opus-5-5", "source": "server" }, "reminders": { "ok": true, "ref": "anthropic:claude-opus-5-5", "source": "server" } }, "month": "2026-10", "server": { "covers": true, "hasKeys": true, "limit": 5, "spent": 1.24, "near": false }, "own": { "limit": null, "spent": 0, "near": false }, "mayAddKeys": true, "mayAddAddresses": false, "keyAlerts": [] }, "keys": [], "settings": { "large": null, "small": null, "tasks": {}, "monthlyLimit": null }, "models": [], "usage": { "months": [ { "month": "2026-10", "server": 1.24, "household": 0, "calls": 31 } ], "tasks": [ { "task": "import", "cost": 1.24, "calls": 31 } ], "people": [ { "userId": "0199e8b0-5a10-7a01-8b00-000000000001", "name": "Sam", "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.