Test one of the household's AI keys

POST

/api/households/current/ai/keys/{keyId}/test

curl --request POST \
  --url http://localhost:3000/api/households/current/ai/keys/example/test \
  --cookie merran.session_token=<merran.session_token>

• Your Merran

Household admins only. Asks the provider what the key can use, which costs nothing, and notes it.

Authorizations

• session

Parameters

Path Parameters

keyId

required

string

<= 64 characters

Responses

200

It works.

Media typeapplication/json

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

Example

{
  "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
}

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

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."
    }
  }
}

404

No such key.

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."
    }
  }
}

502

The provider couldn’t be reached, or answered with an error.

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."
    }
  }
}