Korely Batch API

The Batch API from Korely — 2 operation(s) for batch.

GitHub OpenAPI

Operations 2

POST /v1/batch Create Batch #
GET /v1/batch/{job_id} Get Batch #

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-batch-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-batch-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Korely Ai Batch API
  version: 1.0.21
  description: 'Operations tagged Batch 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: Batch
paths:
  /v1/batch:
    post:
      tags:
      - Batch
      summary: Create Batch
      description: 'Import up to 500 memories in one call.


        Every row is checked as a single write is (its content, metadata,

        `timestamp`, `user_id`, `agent_id` and `run_id`) before anything is queued: a bad row is refused

        with its index in the message, and nothing is imported. Every row needs a `user_id` or an

        `agent_id` (422 `identity_required`, since 1.0.19). Then the job is queued and the

        call answers 202 with its `job_` id. The worker writes the rows, which get

        their facts as any write does; `GET /v1/batch/{job_id}` says how far it is.

        If the key is revoked, expires or is moved to another project before the

        worker is done, the rows not yet imported are not: each is a failed row

        with its reason in `errors`, and the job completes.'
      operationId: create_batch_v1_batch_post
      security:
      - HTTPBearer: []
      parameters:
      - name: X-Korely-Client
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'The tool importing: kept on every imported memory as `client`.'
          title: X-Korely-Client
        description: 'The tool importing: kept on every imported memory as `client`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchBody'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchAccepted'
        '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. And `agent_cap_exceeded`: a new `agent_id` past the plan''s named agents (`limit`, `used`).'
          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'
        '413':
          description: '`payload_too_large`: the body is larger than 78,245,152 bytes, the most this route takes with a key that may write (2,097,152 without one). Refused before it is read; nothing was done. Also a body under 78,245,152 bytes that holds more JSON strings (1,382,024), values (2,747,524) or characters (13,119,024) than the most items can, or whose text decodes to more than it weighs and more than 78,245,152 bytes: read whole, 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. A body past 2,097,152 bytes has 120 s from being let in. 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'
  /v1/batch/{job_id}:
    get:
      tags:
      - Batch
      summary: Get Batch
      description: 'Where an import stands: its `status`, how many rows were `received`,

        `imported` and `failed`, and the `errors` of the rows that failed. A job

        of another project is a 404, and so, for a key confined to some end

        users, is a job another key queued.'
      operationId: get_batch_v1_batch__job_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatus'
        '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'
        '404':
          description: '`not_found`: nothing with that id is reachable with this key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    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.
    BatchStatus:
      properties:
        id:
          type: string
          title: Id
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
          title: Status
          description: 'pending (queued, no worker on it yet), processing (being imported now), completed (every item tried: `imported` and `failed` are final) or failed (stopped on an error of the worker, tried again from where it stopped until its attempts are used, so it may still become completed). The POST answers the stored value, as the GET does.'
        received:
          type: integer
          title: Received
        imported:
          type: integer
          title: Imported
        failed:
          type: integer
          title: Failed
        errors:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Errors
      type: object
      required:
      - id
      - status
      - received
      - imported
      - failed
      - errors
      title: BatchStatus
    BatchMemory:
      properties:
        content:
          type: string
          maxLength: 16000
          minLength: 1
          title: Content
        user_id:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: User Id
          description: 'The end user this memory belongs to. One of user_id and agent_id is required: with neither (or only ids made of spaces, format characters or marks) the write is a 422 `identity_required`; run_id alone is not enough. 1 to 255 characters, no ''/'', no control character or other line break, and not ''.'' or ''..'': the id names a namespace that DELETE /v1/users/<user_id>/memories and DELETE /v1/agents/<agent_id> address as one URL path segment.'
        agent_id:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Agent Id
          description: 'Agent namespace: the agent writing. One of user_id and agent_id is required: with neither (or only ids made of spaces, format characters or marks) the write is a 422 `identity_required`; run_id alone is not enough. 1 to 255 characters, no ''/'', no control character or other line break, and not ''.'' or ''..'': the id names a namespace that DELETE /v1/users/<user_id>/memories and DELETE /v1/agents/<agent_id> address as one URL path segment.'
        run_id:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Run Id
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
        kind:
          type: string
          enum:
          - note
          - session
          title: Kind
          description: 'What the text is: `note` (the default), what somebody said or decided; `session`, the log of a work session (what a coding assistant''s hooks save). A read may leave the sessions out, their facts with them (`exclude_sessions`).'
          default: note
        timestamp:
          anyOf:
          - type: string
          - type: 'null'
          title: Timestamp
          description: ISO date/datetime the memory's events occurred (defaults to the time the item is imported). Facts extracted inherit it as valid_from, exactly as on POST /v1/memories, and an unreadable one refuses the batch (422) rather than being replaced by the import time, as does one outside the moments that can be stored (from 0001-01-02 to 9999-12-30, in UTC).
      additionalProperties: false
      type: object
      required:
      - content
      title: BatchMemory
    BatchAccepted:
      properties:
        id:
          type: string
          title: Id
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
          title: Status
          description: 'pending (queued, no worker on it yet), processing (being imported now), completed (every item tried: `imported` and `failed` are final) or failed (stopped on an error of the worker, tried again from where it stopped until its attempts are used, so it may still become completed). The POST answers the stored value, as the GET does.'
        received:
          type: integer
          title: Received
      type: object
      required:
      - id
      - status
      - received
      title: BatchAccepted
    BatchBody:
      properties:
        memories:
          items:
            $ref: '#/components/schemas/BatchMemory'
          type: array
          maxItems: 500
          minItems: 1
          title: Memories
      additionalProperties: false
      type: object
      required:
      - memories
      title: BatchBody
    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.
  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