Korely Users API
The Users API from Korely — 3 operation(s) for users.
The Users API from Korely — 3 operation(s) for users.
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-users-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 Users API
version: 1.0.21
description: 'Operations tagged Users 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: Users
paths:
/v1/users/{end_user}/memories:
delete:
tags:
- Users
summary: Delete User Memories
description: 'ERASE everything about one end user in one call: every memory and fact.
Physical deletion, not a flag: after this call the content is gone from the
database and cannot be read back by any parameter, `include_invalidated`
included. Unrecoverable by design, because that is what erasure means.
`end_user` is the `user_id` exactly as written, percent-encoded as one path
segment (`acme/42` is `acme%2F42`). Any stored id is accepted here,
including one written before new ids were required to be a single segment.
The response counts rows physically deleted: `memories_deleted` and
`facts_deleted` (until 0.1.42 also under their first names,
`memories_forgotten` and `facts_invalidated`, removed in 0.2.0).
The audit row survives, carrying counts and a keyed pseudonym of your
`end_user_id`, none of the erased content, so you can evidence the erasure
to your own regulator: `GET /v1/audit?user_id=` finds it. The
rest of the access trail takes the pseudonym too, a webhook already
delivered takes the pseudonym, and the cost rows of the model calls never
name an end user.
Within the key''s project: the same id in another project of the account
stays there (it may be another customer''s person). To erase it in every
project at once, the account''s administrator calls
`DELETE /admin/users/{end_user}/memories`.
For a single memory, `DELETE /v1/memories/{memory_id}` forgets it (out of
every read, the row kept, and no call brings it back) or, with
`erase=true`, erases it.'
operationId: delete_user_memories_v1_users__end_user__memories_delete
security:
- HTTPBearer: []
parameters:
- name: end_user
in: path
required: true
schema:
type: string
title: End User
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/UserErasureResponse'
'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.'
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'
/v1/users:
get:
tags:
- Users
summary: List Users
description: 'List the developer''s end users (the distinct ``user_id`` namespaces that
hold memories or facts), with per-user memory + fact counts and last-active
time. Both stores are read (memories AND direct fact writes), so a
fact-only end user is still visible. The default (null) namespace is omitted.'
operationId: list_users_v1_users_get
security:
- HTTPBearer: []
parameters:
- name: agent_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter to one agent namespace.
title: Agent Id
description: Filter to one agent namespace.
- name: limit
in: query
required: false
schema:
type: integer
maximum: 200
minimum: 1
default: 50
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
maximum: 9223372036854775807
minimum: 0
default: 0
title: Offset
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/UsersResponse'
'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'
/v1/users/{end_user}/names:
post:
tags:
- Users
summary: Declare Name
description: 'Declare that this end user is also called `name`.
The store never merges two names of a person by itself: two people can
share a name, and a merge it guessed wrong would close one person''s facts
with another''s. This is the declaration that does it. From now on a fact
written about `name` in this end user''s memory is a fact about the end
user, and the facts already written about `name` are read so at once
(their written words stay as they were). It is the alias the dashboard
makes (`POST /admin/aliases`), for the key''s project and this end user.
`end_user` is the `user_id` exactly as written, percent-encoded as one
path segment. Declaring the same name again answers the same. 409 when
`name` is already declared for somebody else in this memory, 422 when it
is not a name.
There is no undo here: `DELETE /admin/aliases/{id}` removes the alias,
and the facts take back the names their words give; two open facts it
merged stay one, and a plan it closed stays closed.'
operationId: declare_name_v1_users__end_user__names_post
security:
- HTTPBearer: []
parameters:
- name: end_user
in: path
required: true
schema:
type: string
title: End User
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NameBody'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/NameResponse'
'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 writes of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at`, a top-up or a bigger plan). On an account made by `POST /v1/agents/init` and not adopted yet, the trial''s writes in all are spent, `resets_at` is null and a retry fails until the account is adopted (one made before the trial existed has its plan''s writes of the month instead); and `rate_limit_exceeded` with `Retry-After` past the trial''s writes a minute, the wait growing with each such burst of the last hour.'
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`. Or `unavailable`: the server holds as many request bodies as it reads at once; retry after `Retry-After` (5 s). Nothing was done.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'409':
description: '`conflict`: the name is already declared for somebody else in this end user''s memory (the same name declared again for the same end user answers 201, as the first time); `too_many_names`: the account has declared the most names it may have.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'413':
description: '`payload_too_large`: the body is larger than 2,097,152 bytes, the most this route takes. Refused before it is read; nothing was done. Also a body that holds more JSON strings (36,930), values (72,433) or characters (342,092) than lawful items of its size can, whose text decodes to more than it weighs and more than 4,077,000 bytes, or that would take more than 8,388,608 bytes once decoded: refused before it is decoded; nothing was done.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'408':
description: '`request_timeout`: the body did not arrive whole within 30 s. Nothing was done; send it again.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'400':
description: '`bad_request`: the body is not well formed. A JSON body not in UTF-8 (RFC 8259) is refused before it is decoded.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
components:
schemas:
UsersResponse:
properties:
users:
items:
$ref: '#/components/schemas/UserScope'
type: array
title: Users
total:
type: integer
title: Total
type: object
required:
- users
- total
title: UsersResponse
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.
UserErasureResponse:
properties:
user_id:
type: string
title: User Id
description: The end user that was erased.
memories_deleted:
type: integer
title: Memories Deleted
description: Memories physically deleted.
facts_deleted:
type: integer
title: Facts Deleted
description: Facts physically deleted.
erasure:
type: string
title: Erasure
description: Always `permanent`.
audit_id:
type: string
title: Audit Id
description: The `aud_` id of the audit row, which keeps the counts and a keyed pseudonym of your end user id, never the erased content.
type: object
required:
- user_id
- memories_deleted
- facts_deleted
- erasure
- audit_id
title: UserErasureResponse
description: 'DELETE /v1/users/{end_user}/memories: what was physically deleted.
Field order is the order on the wire.'
NameBody:
properties:
name:
type: string
maxLength: 200
minLength: 1
title: Name
description: 'Another name of the end user, as the memories write it: a full name ("Maria Rossi") for the id `maria`.'
agent_id:
anyOf:
- type: string
- type: 'null'
title: Agent Id
description: The agent namespace whose memory the name is declared in; none for the end user's own memory.
additionalProperties: false
type: object
required:
- name
title: NameBody
NameResponse:
properties:
user_id:
type: string
title: User Id
name:
type: string
title: Name
agent_id:
anyOf:
- type: string
- type: 'null'
title: Agent Id
since:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Since
type: object
required:
- user_id
- name
title: NameResponse
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.
UserScope:
properties:
user_id:
type: string
title: User Id
memories:
type: integer
title: Memories
facts:
type: integer
title: Facts
last_active:
anyOf:
- type: string
- type: 'null'
title: Last Active
type: object
required:
- user_id
- memories
- facts
- last_active
title: UserScope
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