API Reference

Overview

One bearer header, JSON in and out, EU-hosted. Every endpoint maps one-to-one onto the Python and Node SDKs, the same call, three ways in.

Base URL: https://api.korely.ai. Every endpoint is under /v1. Requests and responses are JSON; data is stored in the EU. Prefer not to call HTTP directly? The Python and Node SDKs mirror this surface method-for-method, and there's an interactive playground generated from the live spec.

Authentication

Every request carries an Authorization header with your secret key: Authorization: Bearer kor_live_.... Keys are issued when you sign up as an agent. Keep the key server-side, it can read and write all memory in your workspace.

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

from korely_memory import Korely

korely = Korely(api_key="kor_live_...", region="eu")

import { Korely } from "korely-memory";

const korely = new Korely({ apiKey: "kor_live_..." });

Scoping

Three optional, free-form strings scope every memory. You choose the values; filters are additive (AND).

Field	Identifies	Example
`user_id`	Your end user. Unlimited on every tier.	`"customer-giulia-4812"`
`agent_id`	Your application's namespace.	`"support-bot"`
`run_id`	One session or conversation.	`"chat-2026-06-17-a"`

Errors

Errors return the matching HTTP status and a JSON envelope with a stable code and a human message, always those two keys, never error or detail.

{
  "code": "invalid_key",
  "message": "Invalid or missing API key"
}

Status	Code	When
`401`	`invalid_key`	The `Authorization` header is missing, malformed, or the key is revoked.
`403`	`forbidden`	The key lacks the scope the endpoint requires (e.g. `memories:write`).
`403`	`agent_cap_exceeded`	A new `agent_id` would exceed your tier's agent cap. The write is not applied.
`404`	`not_found`	No such resource in this workspace (also returned instead of `403`, so membership isn't leaked).
`405`	`method_not_allowed`	The HTTP method is not supported for this path.
`409`	`stale_write`	`expected_updated_at` on an update doesn't match the current record, another write landed first.
`422`	`invalid_request`	Request validation failed, a missing field or a malformed value.
`429`	`quota_exceeded`	Monthly write quota reached. Carries no `Retry-After`; it resets at the next billing cycle.
`429`	`rate_limit_exceeded`	Too many requests per second. This one does carry `Retry-After`.
`503`	`search_unavailable`	The vector search backend is temporarily unavailable; retry shortly. Other read paths are unaffected.

Rate limits & quotas

Two limits, two meanings. A short-term rate limit (requests per second) returns 429 rate_limit_exceeded with a Retry-After header, back off and retry. A monthly quota (memories written and queries per month, by tier) returns 429 quota_exceeded with no Retry-After: we email you at 80%, and past a +10% soft cap you get a clean error rather than a surprise invoice. Reads are far more generous than writes, because reads are retrieval, not generation. See pricing for the per-tier numbers.

The endpoints

Grouped in the sidebar: Core memory operations (add, search, list, get, update, delete, history), Context & facts (the typed bi-temporal layer, get context, get and write facts, get profile), Users & agents, and Batch & status. Start with Add a memory.