Korely Batch API
The Batch API from Korely — 2 operation(s) for batch.
The Batch API from Korely — 2 operation(s) for batch.
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-batch-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 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