Skip to content
merran
GitHubInstall

Merran documentation API & integrations

Pick the household's AI models

PUT
/api/households/current/ai
curl --request PUT \
  --url http://localhost:3000/api/households/current/ai \
  --header 'Content-Type: application/json' \
  --cookie merran.session_token=<merran.session_token> \
  --data '{ "large": null, "small": null, "tasks": {}, "monthlyLimit": 10, "autoTidy": false }'

Household admins only. Its models for big and small tasks, and for any task of its own; null goes by its keys, or the server’s. And a monthly limit on its own keys.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
large
required

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

string | null
<= 300 characters

Example 

anthropic:claude-opus-5-5
small
required

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

string | null
<= 300 characters

Example 

anthropic:claude-opus-5-5
tasks
required

A model for a task of its own.

object
assistant

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

string
<= 300 characters

Example 

anthropic:claude-opus-5-5
import

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

string
<= 300 characters

Example 

anthropic:claude-opus-5-5
tidy

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

string
<= 300 characters

Example 

anthropic:claude-opus-5-5
notes

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

string
<= 300 characters

Example 

anthropic:claude-opus-5-5
swaps

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

string
<= 300 characters

Example 

anthropic:claude-opus-5-5
nutrition

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

string
<= 300 characters

Example 

anthropic:claude-opus-5-5
shopping

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

string
<= 300 characters

Example 

anthropic:claude-opus-5-5
receipts

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

string
<= 300 characters

Example 

anthropic:claude-opus-5-5
discover

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

string
<= 300 characters

Example 

anthropic:claude-opus-5-5
reminders

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

string
<= 300 characters

Example 

anthropic:claude-opus-5-5
monthlyLimit
required

A monthly limit on its own keys, in US dollars; null for none.

number | null
<= 100000
autoTidy

Tidy up each recipe it imports, in the background, with the suggestions left in the Review queue.

boolean

Example 

{
  "large": null,
  "small": null,
  "tasks": {},
  "monthlyLimit": 10,
  "autoTidy": false
}

Responses

Section titled “Responses”

200

Section titled “200”

Saved.

Media typeapplication/json
object
status
required
object
available
required
boolean
tasks
required

For each task, the model and whose key, or why none.

object
assistant
Any of:
object
ok
required
boolean
ref
required
string
source
required
string
Allowed values: server household
import
Any of:
object
ok
required
boolean
ref
required
string
source
required
string
Allowed values: server household
tidy
Any of:
object
ok
required
boolean
ref
required
string
source
required
string
Allowed values: server household
notes
Any of:
object
ok
required
boolean
ref
required
string
source
required
string
Allowed values: server household
swaps
Any of:
object
ok
required
boolean
ref
required
string
source
required
string
Allowed values: server household
nutrition
Any of:
object
ok
required
boolean
ref
required
string
source
required
string
Allowed values: server household
shopping
Any of:
object
ok
required
boolean
ref
required
string
source
required
string
Allowed values: server household
receipts
Any of:
object
ok
required
boolean
ref
required
string
source
required
string
Allowed values: server household
discover
Any of:
object
ok
required
boolean
ref
required
string
source
required
string
Allowed values: server household
reminders
Any of:
object
ok
required
boolean
ref
required
string
source
required
string
Allowed values: server household
month
required
string
server
required
object
covers
required
boolean
hasKeys
required
boolean
limit
required

In US dollars.

number | null
spent
required

In US dollars.

number
near
required
boolean
own
required
object
limit
required

In US dollars.

number | null
spent
required

In US dollars.

number
near
required
boolean
mayAddKeys
required
boolean
mayAddAddresses
required
boolean
keyAlerts
required

The keys it relies on, its own and the server’s, that are out of credit or running low.

Array<object>
object
id
required
string
source
required
string
Allowed values: server household
provider
required
string
Allowed values: anthropic openai google openai-compatible
name
required
string | null
outOfCredit
required
boolean
left
required

About what’s left, when credit was entered.

number | null
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
settings
required
object
large
required

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

string | null
<= 300 characters
small
required

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

string | null
<= 300 characters
tasks
required

A model for a task of its own.

object
assistant

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

string
<= 300 characters
import

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

string
<= 300 characters
tidy

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

string
<= 300 characters
notes

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

string
<= 300 characters
swaps

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

string
<= 300 characters
nutrition

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

string
<= 300 characters
shopping

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

string
<= 300 characters
receipts

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

string
<= 300 characters
discover

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

string
<= 300 characters
reminders

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

string
<= 300 characters
monthlyLimit
required

A monthly limit on its own keys, in US dollars; null for none.

number | null
<= 100000
autoTidy

Tidy up each recipe it imports, in the background, with the suggestions left in the Review queue.

boolean
models
required
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
usage
required
object
months
required
Array<object>
object
month
required
string
server
required

In US dollars.

number
household
required

In US dollars.

number
calls
required
number
tasks
required
Array<object>
object
task
required
string
cost
required

In US dollars.

number
calls
required
number
people
required
Array<object>
object
userId
required
string | null
name
required
string | null
cost
required

In US dollars.

number
calls
required
number

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
      }
    ]
  }
}

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.