Korely Context API
The Context API from Korely — 1 operation(s) for context.
The Context API from Korely — 1 operation(s) for context.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/korely-ai:korely-ai-context-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Korely Ai Context API
version: 1.0.21
description: 'Operations tagged Context across 2 of this provider''s published API definitions: korely-ai-agent-openapi.json, korely-ai-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.korely.ai
description: EU (Helsinki)
tags:
- name: Context
paths:
/v1/context:
get:
tags:
- Context
summary: Get Context
description: 'A block for the prompt: what the store knows about the end user, and
the facts and memories most relevant to `query`, as Markdown within
`token_budget` tokens.
No text is generated: retrieval and layout, the question only embedded to
rank. `context` is
the whole block; `stable` (the same from one call to the next) and
`volatile` (this question''s part) are its two halves, for a model
provider''s prompt cache. `degraded` is true when part of it could not be
retrieved, `degraded_parts` says which, and the block then ends with a
note saying so to the model.'
operationId: get_context_v1_context_get
security:
- HTTPBearer: []
parameters:
- name: query
in: query
required: true
schema:
type: string
minLength: 1
maxLength: 2000
title: Query
- name: user_id
in: query
required: false
schema:
anyOf:
- type: string
maxLength: 255
- type: 'null'
description: End user to build context for.
title: User Id
description: End user to build context for.
- name: agent_id
in: query
required: false
schema:
anyOf:
- type: string
maxLength: 255
- type: 'null'
description: 'One agent''s namespace: its facts and its memories only, as every other read with an agent_id.'
title: Agent Id
description: 'One agent''s namespace: its facts and its memories only, as every other read with an agent_id.'
- name: token_budget
in: query
required: false
schema:
type: integer
maximum: 8000
minimum: 50
description: 'Tokens the block may take, 50 to 8000. Default 800; we recommend 4000 for an agent that answers questions about the past. A larger budget lets more facts and memories into the block (above 2000 tokens, more memories, ordered so that near duplicates do not crowd it), and is a larger prompt: keep it low where latency matters, as in a voice agent.'
default: 800
title: Token Budget
description: 'Tokens the block may take, 50 to 8000. Default 800; we recommend 4000 for an agent that answers questions about the past. A larger budget lets more facts and memories into the block (above 2000 tokens, more memories, ordered so that near duplicates do not crowd it), and is a larger prompt: keep it low where latency matters, as in a voice agent.'
- name: known_as_of
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'ISO date/datetime: the block as the store could have built it then: the facts it had learned by then, true then as it knew them, and the memories it had received by then. Rebuilt with today''s ranking; a memory edited since shows today''s text, one deleted since stays out.'
title: Known As Of
description: 'ISO date/datetime: the block as the store could have built it then: the facts it had learned by then, true then as it knew them, and the memories it had received by then. Rebuilt with today''s ranking; a memory edited since shows today''s text, one deleted since stays out.'
- name: exclude_sessions
in: query
required: false
schema:
type: boolean
description: 'Leave out the work sessions (memories written with `kind: session`, what a coding assistant''s hooks save) and the facts only they state, for a block about what was said and decided. Default false: everything.'
default: false
title: Exclude Sessions
description: 'Leave out the work sessions (memories written with `kind: session`, what a coding assistant''s hooks save) and the facts only they state, for a block about what was said and decided. Default false: everything.'
- name: reader
in: query
required: false
schema:
anyOf:
- type: string
maxLength: 255
- type: 'null'
description: 'Your agent''s own name, by the rule of `agent_id`. With it, this read keeps the ids of the facts it hands over as true, with the time, for 90 days after the last read unless the install sets READ_MARKS_RETENTION_DAYS, and the context block of this reader opens with what changed since in the facts it was handed (agent notices), each change told at most once. It filters nothing, and a read of the past (`as_of`, `known_as_of`) or of the history (`include_invalidated`) keeps nothing and tells nothing. Not authenticated: whoever holds the key can give any name.'
title: Reader
description: 'Your agent''s own name, by the rule of `agent_id`. With it, this read keeps the ids of the facts it hands over as true, with the time, for 90 days after the last read unless the install sets READ_MARKS_RETENTION_DAYS, and the context block of this reader opens with what changed since in the facts it was handed (agent notices), each change told at most once. It filters nothing, and a read of the past (`as_of`, `known_as_of`) or of the history (`include_invalidated`) keeps nothing and tells nothing. Not authenticated: whoever holds the key can give any name.'
- name: changes
in: query
required: false
schema:
anyOf:
- const: all
type: string
- type: 'null'
description: 'Which changes the block tells a `reader`. Left out: every kind in a memory with an end user, and in an agent''s memory with no end user only the explicit ones (corrected, forgotten, stated by a caller), since there the closures read from memories were mostly wrong when measured. `all`: those too.'
title: Changes
description: 'Which changes the block tells a `reader`. Left out: every kind in a memory with an end user, and in an agent''s memory with no end user only the explicit ones (corrected, forgotten, stated by a caller), since there the closures read from memories were mostly wrong when measured. `all`: those too.'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ContextResponse'
'401':
description: '`invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'403':
description: '`forbidden`: the key lacks the scope this operation needs; `message` names it.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'422':
description: '`invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` lists the first 20 fields that failed, `message` names the first and counts them all), or the endpoint refuses a value (an empty content, an unreadable timestamp, a NUL byte or a lone UTF-16 surrogate anywhere in the request, a moment that cannot be stored, which is any but from 0001-01-02 to 9999-12-30, in UTC; `detail` is a sentence or `{code, message}`).'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'429':
description: '`rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan''s minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan''s queries of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at` or a bigger plan).'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: '`internal_error`: the server failed on this request; `message` holds no detail of it.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'503':
description: 'A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry. Also `unavailable` when the request waited more than 5 s for another change to the same records (an erasure under way, for example) or its statement ran past 60 s; see `Retry-After`.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
components:
schemas:
ChangeNow:
properties:
fact_id:
type: string
title: Fact Id
description: The `fct_` id of the fact that holds now.
text:
type: string
title: Text
description: It, as the block writes a fact.
type: object
required:
- fact_id
- text
title: ChangeNow
ErrorCode:
properties:
code:
type: string
title: Code
description: Stable, machine-readable reason, e.g. `not_found`, `stale_write`, `invalid_request`, `search_unavailable`. Branch on this, never on `message`.
examples:
- not_found
message:
type: string
title: Message
description: What went wrong, for a person to read. Wording may change.
type: object
required:
- code
- message
title: ErrorCode
description: A refusal with a stable reason.
ApiError:
properties:
detail:
anyOf:
- type: string
- $ref: '#/components/schemas/ErrorCode'
- items:
$ref: '#/components/schemas/ValidationIssue'
type: array
title: Detail
description: 'As this install has always sent it: a sentence; or `{code, message}` where the endpoint names the reason; or, on a 422 from validation, the list of fields that failed.'
code:
type: string
title: Code
description: 'Stable, machine-readable reason, the same names as the hosted API: `invalid_key`, `forbidden`, `not_found`, `stale_write`, `invalid_request`, `identity_required` (a write with neither user_id nor agent_id), `rate_limit_exceeded`, `search_unavailable`, `model_unavailable`, `service_paused`, `internal_error`... When `detail` is `{code, message}` it is that code. Branch on this, never on `message`.'
examples:
- not_found
message:
type: string
title: Message
description: 'What went wrong, for a person to read: the sentence, the message of `detail`, or the first field that failed validation. Wording may change.'
current_fact_id:
anyOf:
- type: string
- type: 'null'
title: Current Fact Id
description: '`fact_not_current`: the fact in force to correct instead, null when nothing took the fact''s place. Absent on every other refusal.'
type: object
required:
- detail
- code
- message
title: ApiError
description: The body of every answer that is not a success, whatever the status.
ValidationIssue:
properties:
type:
type: string
title: Type
description: What kind of failure, e.g. `missing`, `extra_forbidden`, `string_too_long`, `invalid_namespace_id`.
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Loc
description: 'Where: `body`, `query` or `path`, then the field, e.g. ["body", "memories", 0, "user_id"].'
msg:
type: string
title: Msg
description: What is wrong with it, for a person to read.
ctx:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Ctx
description: The limit that was crossed, when there is one.
type: object
required:
- type
- loc
- msg
title: ValidationIssue
description: One field that failed validation. The value sent is never echoed back.
ContextResponse:
properties:
context:
type: string
title: Context
tokens:
type: integer
title: Tokens
sources:
items:
type: string
type: array
title: Sources
degraded:
type: boolean
title: Degraded
default: false
degraded_parts:
items:
type: string
type: array
title: Degraded Parts
stable:
type: string
title: Stable
description: 'The head of `context` that does not depend on the question: the reader note, the same text from one call to the next. Put it in your system prompt, where the model provider''s prompt cache can reuse it.'
default: ''
volatile:
type: string
title: Volatile
description: 'The rest of `context`: the facts and the memories for this question and, when part of the retrieval failed, a closing NOTE. Put it in the turn.'
default: ''
stable_hash:
type: string
title: Stable Hash
description: SHA-256 (hex) of `stable`. The same value means the same prefix, so a cached system prompt is still valid.
default: ''
changed:
anyOf:
- items:
$ref: '#/components/schemas/Change'
type: array
- type: 'null'
title: Changed
description: 'With `reader` only: the facts this reader was handed by an earlier read and that changed since, as the block''s section "Changed since you last read" shows them, newest first, at most 3. Each is told at most once.'
changed_more:
anyOf:
- type: integer
- type: 'null'
title: Changed More
description: 'With `reader` only: how many more changes wait for this reader, behind the same walls; told in the blocks that follow. Null when the changes could not be read this time (their records were locked): they wait for the next read.'
type: object
required:
- context
- tokens
- sources
title: ContextResponse
Change:
properties:
fact_id:
type: string
title: Fact Id
description: The `fct_` id of the fact the reader was handed.
was:
anyOf:
- type: string
- type: 'null'
title: Was
description: It, as the block writes a fact; null when the memory that stated it was forgotten, whose words are never told.
now:
anyOf:
- $ref: '#/components/schemas/ChangeNow'
- type: 'null'
description: 'What holds now in its place, when this key may read it; null: no longer true.'
ended_at:
anyOf:
- type: string
- type: 'null'
title: Ended At
description: When it stopped being true.
known_at:
anyOf:
- type: string
- type: 'null'
title: Known At
description: When the store learned it.
origin:
type: string
enum:
- corrected
- forgotten
- stated
- read_from_memory
title: Origin
description: 'Where the change came from: a correction, a forget, a fact a caller wrote, or the store''s reading of a memory. A label, never a score.'
source_memory_id:
anyOf:
- type: string
- type: 'null'
title: Source Memory Id
description: 'With `read_from_memory`: the memory that closed it.'
by_agent:
anyOf:
- type: string
- type: 'null'
title: By Agent
description: The agent namespace of what closed it.
type: object
required:
- fact_id
- origin
title: Change
description: 'A fact this reader was handed and that has ended since (agent
notices).'
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
bearerAuth:
type: http
scheme: bearer
description: Your kor_live_ API key.
x-refined-from:
- korely-ai-agent-openapi.json
- korely-ai-openapi.json