Korely Users API

The Users API from Korely — 3 operation(s) for users.

GitHub OpenAPI

Operations 3

DELETE /v1/users/{end_user}/memories Delete User Memories #
GET /v1/users List Users #
POST /v1/users/{end_user}/names Declare Name #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/korely-ai:korely-ai-users-api"
All apis
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.

Get an API 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 Specification

korely-ai-users-api-openapi.yml Raw ↑
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