API Reference

Overview

Call Korely over HTTP: one key in a header, JSON in and out. This page lists the routes and what they share.

Base URL: https://api.korely.ai. Memories and facts are stored on Korely's servers in Helsinki. The project's region decides which model reads their text to write the facts: global (the default) uses a model from Google, outside the EU; eu uses Scaleway in Paris (see Data governance).

Quick start

You need an API key: Quickstart: get a free API key shows how. Replace kor_live_... with yours. The call changes none of your data.

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

A working key answers 200:

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

tier is the name of your plan: hobby, developer, team or scale. scopes is the list of the key's permissions (the API calls them scopes).

No 200? A 401 means the key is missing or wrong: copy it again. Any other status is listed in Errors.

Terms

The Glossary defines the words used across the docs. These are the ones this page relies on: Cloud and Self-hosted, SDK, confined key, end user, agent_id, run_id, write, read, rate limit and webhook. This page adds these:

• Route: one HTTP method and path, such as GET /v1/ping.
• region and processing_region: in the ping answer, region names the server that answered (eu-hel1, in Helsinki). processing_region is the region of the key's project, eu or global, which decides the model provider that receives your text: Scaleway in Paris for eu, Google (outside the EU) for global.
• Batch: one POST /v1/batch call with up to 500 memories. Korely queues it, answers 202, and stores the memories in the background.
• Event: a write's processing state (processing, ready or error), as List events returns it.
• expected_updated_at: an optional field of a memory PATCH: the updated_at you last read. If the memory changed since, the edit is refused.
• degraded: true: a GET /v1/context answer with a part missing, such as the memories. degraded_parts names the part.

Reference

Address and keys

All customer routes are under /v1. The dashboard, the web app for your account, has its own administration API (/admin/*), not part of this API.

Every /v1 request carries Authorization: Bearer kor_live_..., except POST /v1/agents/init, which creates an account and its first key (see Sign up as an agent). Create more keys in the dashboard.

Keep the key on your server. A full key (memories:read and memories:write) reads and writes all memory in its project; a read-only key (memories:read) reads it all. A confined key reaches only its end users.

Routes

The route pages below are still to be reviewed. Until then, check details against the Core operations guides, which are more recent: Add, Search, Get context, Update, Delete and Forget a user.

The interactive playground shows each route's request and response. It reads the OpenAPI file published on this site, which can lag behind the latest release.

Scoping

Three strings that you choose scope a memory. Filters combine with AND. A write needs a user_id or an agent_id (Every write says whose memory it is); run_id is always optional.

On writes, user_id and agent_id:

• take 1 to 255 characters;
• contain no / and no control characters;
• are not . or ..;
• do not start with erased:, which Korely uses to mark erased end users.

run_id takes 1 to 255 characters. In paths, {end_user} is the user_id.

Errors

An error returns its HTTP status and a JSON body with three fields. Branch on code. message is a sentence for people; its wording may change. detail holds the same sentence, except on a 422, where it lists the fields that failed.

{
  "detail": "Memory not found",
  "code": "not_found",
  "message": "Memory not found"
}

The Retry-After header:

• is sent with rate_limit_exceeded, unavailable (5 seconds), search_unavailable (5 seconds) and service_paused (3600 seconds);
• is not sent with quota_exceeded, agent_cap_exceeded or model_unavailable.

Rate limits and quotas

The rate limit caps requests per minute, hour and day for your whole account: all keys, REST and MCP share it. Past it you get 429 rate_limit_exceeded; Retry-After says when that window resets. A request the limit refuses is not counted. Every other call counts, GET /v1/ping included.

The monthly quota caps writes and reads, by plan. You can go 10% over the monthly figure; past that, 429 quota_exceeded: wait for resets_at. A quota.warning webhook fires when the month's writes cross 80%.

An add or a PATCH of a memory counts one write per 6,000 characters of text. POST /v1/facts, a PATCH of a fact and declaring a name count one each. A batch counts whole when Korely queues it. If it does not fit in the writes left this month, it is refused.

Hobby allows 60 requests per minute, 1,000 per hour and 10,000 per day; Pricing has every plan.

No response has X-RateLimit-* headers or says how many calls are left.

Versioning

Korely is versioned by release number: the changelog shows the current release and what each one changes.

From 1.0, nothing published is removed without a 2.0: an endpoint, a field or an error code of a 1.x release stays in every 1.x release.

Details

• No idempotency. A retried write can store the memory twice and count two writes. An Idempotency-Key header is ignored.
• Pages of results. Lists of memories, facts, users and agents take limit (default 50, at most 200) and offset, and answer total.
• Slow bodies. A body has 30 seconds to arrive, or 120 for a batch over 2 MiB. Later, 408 request_timeout.
• Size limits. On the Cloud, a body over 1 MB (80 MB for a batch) gets a 413 with no JSON body, so check the status, not the body. Self-hosted and smaller bodies meet the API's own limit: 413 payload_too_large over 2,097,152 bytes (78,245,152 for a batch), or when the body holds too many separate text values.
• Waits. A request waits up to 5 seconds for locked data before 503 unavailable; forgetting a user or deleting an agent waits up to 60.
• Self-hosted. Quotas, the agent cap, quota.warning, sign-up limits, service_paused, POST /v1/agents/init and DELETE /v1/account exist only on the Cloud. The rate limit is off by default.