Account API

The Account API is your own Kaer account, reachable from outside the app. Create a personal API key, send it as a bearer token, and you can ask your agent something from a terminal, a script, a server, or a scheduled cron job — the same agent, the same account, the same usage.

Keys are prefixed kaer_sk_, and they carry your identity: a key never grants more than you have in the app.

Create an API key

Open Customise → API access, choose a Key name — something that says where it will live, like laptop or deploy-script — pick its scopes, and select Create key.

The full key is shown once, at creation. Copy it then. Afterwards the list shows only the prefix, enough to recognise a key but not to use it. If you lose a key, revoke it and create another; there is no way to see it again.

You can hold up to 10 active keys at a time. Revoked keys do not count against that.

Scopes

Each key carries a scope set, chosen when you create it. A key can only reach the endpoints its scopes cover.

GET /api/v1/me works with any valid key regardless of scope — it is the introspection endpoint, so it needs nothing.

search carries one extra condition the others do not: the account must also have extra usage switched on, because search bills $0.005 per query with no included allowance. The scope alone is not enough — see Web Search API.

Give a key the narrowest scope set that covers its job. A cron job that only geocodes addresses needs maps and nothing else, and a key like that is a much smaller problem if it ever leaks.

Authenticating

Send the key in either header. They are equivalent — pick whichever your client makes easier.

Authorization: Bearer kaer_sk_your_key

X-Kaer-Api-Key: kaer_sk_your_key

Ask your agent: POST /api/v1/agent

The same contract as the in-app chat. One message in, the agent's answer out.

curl https://app.kaer.ai/api/v1/agent \
  --header 'Authorization: Bearer kaer_sk_your_key' \
  --header 'Content-Type: application/json' \
  --data '{"message":"Summarise my unread mail from this week"}'

Request body

Response

{
  "text": "Three unread threads matter this week: …"
}

With stream: true the response is text/plain; charset=utf-8 and arrives as tokens — read it as a stream rather than waiting for a complete body.

Everything the agent can do for you in the app, it can do here: your connectors, your workflows, and your own entries from Customise all apply, because the call runs as you.

Check a key: GET /api/v1/me

The cheapest possible probe of a key — is it alive, what can it do, what has it spent. Make this the first call in any script you write.

curl https://app.kaer.ai/api/v1/me \
  --header 'Authorization: Bearer kaer_sk_your_key'

{
  "key": {
    "name": "deploy-script",
    "prefix": "kaer_sk_9f2c",
    "scopes": ["agent", "maps"],
    "requests": 412,
    "spent_microcents": 41250,
    "created_at": 1753900000000,
    "last_used_at": 1753986400000
  },
  "account": {
    "user_id": "usr_…"
  }
}

requests counts every call made with this key. spent_microcents is what has been billed directly to it, in millionths of a cent — Maps calls land here. Agent calls meter into your account's normal usage instead of being charged to the key, so they raise the request count without raising this number.

Maps: GET /api/v1/maps

The full Maps API through your account key, using the same query contract as the standalone Maps endpoint.

curl --get 'https://app.kaer.ai/api/v1/maps' \
  --header 'Authorization: Bearer kaer_sk_your_key' \
  --data-urlencode 'action=geocode' \
  --data-urlencode 'query=London'

Actions, inputs, response fields, attribution requirements and data-quality caveats are the same as the Maps API surface documented in Settings → Developer. The only difference is which key you send: an account key with the maps scope covers this and your agent calls at once, while a dedicated kmaps_ key does maps and nothing else.

Errors

Errors come back as JSON with an error field explaining what went wrong. A 401 after a period of working almost always means the key was revoked — check Customise → API access.

Billing

Calls through the Account API are metered exactly as the same work would be in the app. Nothing here is free, and nothing here is priced differently for being an API call.

• Agent calls meter into your normal usage, run by run, on what the work actually used. They appear in Activity alongside everything else, and your hard limits apply — a key cannot spend past the cap you set in Settings.
• Maps calls are billed per request at the standard Maps rate, the same price as a dedicated Maps key. Maps has two rate bands: map tiles and static map images are billed at the low tile rate, and everything that computes an answer — geocoding, routing, places, transit, traffic, weather — at the standard rate. Tiles are the cheaper band because they are the highest-volume thing you will call and the cheapest for us to serve; there is no reason to make you pay routing prices for them.

The live rates for your account are shown in Settings → Developer, and spent_microcents on /api/v1/me tells you exactly what a key has spent so far. Billing is prepaid from your wallet — there is no monthly minimum and no seat fee for API access.

Sustained API use needs a paid plan; see Plans and Pricing and Billing and Usage.

Handling keys safely

A key is a live credential for your whole account. Treat it as one.

• Copy it once, store it properly. Put the key straight into a secret manager or your platform's environment configuration. Not a chat message, not a code comment, not a committed .env.
• One key per machine or purpose. Separate keys for your laptop, your CI runner and your cron box mean a single revocation is a single machine, not a morning of re-plumbing. Names like laptop and deploy-script make that list readable a year later.
• Never ship one to a browser. Anything in a public client bundle is public. Call the API from your server or another protected runtime.
• Revoke rather than share. If someone else needs access, they create their own key on their own account. Passing a key around means you can no longer tell whose call spent what.
• Revoke the moment a key is in doubt. Revocation is immediate, other keys are unaffected, and creating a replacement takes seconds. There is no reason to wait and see.

Call Kaer from your terminal

The whole point of a key is that Kaer stops being somewhere you have to open a tab to reach. A one-line shell function is usually all you need:

kaer() {
  curl -s https://app.kaer.ai/api/v1/agent \
    -H "Authorization: Bearer $KAER_API_KEY" \
    -H 'Content-Type: application/json' \
    -d "$(jq -n --arg m "$*" '{message:$m}')" | jq -r .text
}

kaer "what changed in the deploy log in the last hour?"

The same call works from a cron job, a CI step, a server process, or anything else that can make an HTTPS request — a nightly script can ask for a summary and mail it to you, a deploy step can ask for release notes. Nothing about the runtime matters, only the key.

Good to know

• Which key do I use for what? One account key with both scopes covers agent calls and maps. A maps-only kmaps_ key, created in Settings → Developer, is the narrower option when a system only ever needs maps.
• Do keys expire? No. They stay valid until you revoke them.
• Can I change a key's scopes? Create a new key with the scopes you want and revoke the old one — a fresh key is safer than a widened one.
• Is there a separate API plan? No. API usage draws on the same credits as your in-app work; see Billing and Usage.
• What else lives in Customise? Custom tools, MCP servers and skills — see Customise.