Batch & status

Ping

A minimal liveness probe: prove a freshly minted kor_live_ key authenticates, and read back its tier, the install's region label, its processing region, and its scopes.

GET /v1/ping

The first call to make after minting a key. It confirms the bearer token resolves to a live key, surfaces the tier and granted scopes you'll use to reason about access, and says where the model that writes your facts runs (processing_region, the region of the key's project). region is a label the operator of the install sets: on the Cloud it is eu-hel1, the Helsinki server that stores your data.

Authentication

HTTP header, required: Authorization: Bearer kor_live_....

Query parameters

None. /v1/ping takes no query parameters, no path parameters, and no request body, just the Authorization header.

Example request

curl https://api.korely.ai/v1/ping \
  -H "Authorization: Bearer kor_live_..."

from korely_memory import Korely

korely = Korely()  # reads KORELY_API_KEY
p = korely.ping()
print(p.ok, p.tier, p.region, p.scopes)
# True hobby eu-hel1 ['memories:read', 'memories:write']

import { Korely } from "korely-memory";

const korely = new Korely(); // reads KORELY_API_KEY
console.log(await korely.ping());
// { ok: true, tier: "hobby", region: "eu-hel1", processing_region: "global", scopes: [...] }

korely ping
# ok  tier hobby  region eu-hel1  processing global  scopes memories:read, memories:write

Response

200 OK. Confirmation that the key authenticated, plus its tier, the install's region label, its processing region, and its granted scopes.

{
  "ok": true,
  "tier": "hobby",
  "region": "eu-hel1",
  "processing_region": "global",
  "scopes": ["memories:read", "memories:write"]
}

Field	Type	Description
`ok`	boolean	Always `true` on success, confirms the key authenticated.
`tier`	string	The API key's billing tier, e.g. `hobby`.
`region`	string	A label the operator of the install sets, the same for every key and every project. The service does not check it, so it is not a measurement of where the data is. On the Cloud it is `eu-hel1`: Korely sets it to its Helsinki server, which stores the data of every project. On Self-hosted it is the `REGION` value in `.env`, `eu` when it is not set; set it to where your machine and database are.
`processing_region`	string	Where the language model that writes the key's project's facts runs: `global` or `eu`. On the Cloud, `global` is Google Gemini (the default for a new account) and `eu` is Scaleway in Paris; on Self-hosted, each region's model is the one its operator chose. Chosen per project; see Regions. `null` when that region has no model to write with.
`scopes`	array[string]	The scopes granted to the key; an empty list if the key has no scopes.

Errors

Status	Code	Cause
`401`	`invalid_key`	The `Authorization` header is missing or empty, or the bearer token does not resolve to a live key. The body is the standard error envelope, e.g. `{"code": "invalid_key", "message": "Invalid or missing API key: no live key matches it (a revoked key stops at once); your keys are at https://agent.korely.ai/keys"}`, with a `WWW-Authenticate: Bearer` header. Branch on `code`: the message differs for some keys.
`429`	`rate_limit_exceeded`	The account's request ceiling (on the Cloud, the plan's minute, hour or day window), counted as for every other call. Comes back with a `Retry-After` header.
`500`	`internal_error`	The request failed on our side.
`503`	`unavailable`	The database did not answer while the key was checked. Nothing was done; retry after the `Retry-After` header.

Notes

No scope needed. Ping depends only on a valid key, so it never returns 403. It counts against the request limit like every other call, and each ping is one row in the audit log.
Source of each field. tier and scopes come from the key itself; region is read from the install's configuration, not the key; processing_region from the project the key belongs to. scopes defaults to an empty list [] when the key has none.
In the SDKs. ping() in Python and Node, korely ping (or korely auth) in the CLI. Node returns the JSON as the server sends it. All of them expose processing_region; the CLI prints it when the server answers it.
Side effect. Resolving the key stamps its last_used_at, so a ping also serves as a heartbeat for the key.
Use it in CI. A green ping is the fastest signal that your key and endpoint are wired correctly before you touch the memory endpoints under /v1/memories/{memory_id}.

Add a memory, the first real write once ping is green.
Get context, read back the assembled recall block.
SDK, the typed client, with ping().