Add an AI key or address for the server

POST

/api/settings/server/ai/keys

curl --request POST \
  --url http://localhost:3000/api/settings/server/ai/keys \
  --header 'Content-Type: application/json' \
  --cookie merran.session_token=<merran.session_token> \
  --data '{ "provider": "anthropic", "key": "sk-ant-api03-...7xQa" }'

• Your Merran

Server admins only. A provider’s key replaces the server’s one before it; there can be several addresses, which may be on the home network (an Ollama, say). It’s tested against the provider first, at no cost, and kept sealed.

Authorizations

• session

Request Body^required

Media typeapplication/json

One of:

object

object

provider

required

string

Allowed values: anthropic openai google

key

required

string

>= 10 characters <= 500 characters

object

object

provider

required

string

Allowed values: openai-compatible

name

required

string

>= 1 characters <= 60 characters

baseUrl

required

string

>= 1 characters <= 500 characters

key

string | null

<= 500 characters

Responses

201

Tested and kept.

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

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