---
title: "Create Batch"
method: POST
path: "/v1/batch"
tags: ["v1"]
---

# Create Batch

`POST /v1/batch`

## Request

- Base URL: `https://api.korely.ai`
- URL: `https://api.korely.ai/v1/batch`
- Auth: HTTP bearer

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. 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.

## Headers

- `X-Korely-Client` string, nullable: The tool importing: kept on every imported memory as `client`.

## Request body

- BatchBody
  - `memories` BatchMemory[], required
    - `content` string, required
    - `user_id` string, nullable: The end user this memory belongs to. 1 to 255 characters, no '/', no control characters, 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` string, nullable: Agent namespace. 1 to 255 characters, no '/', no control characters, 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` string, nullable
    - `metadata` object, nullable
    - `kind` 'note' | 'session': 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`).
    - `timestamp` string, nullable: 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.

## Response `202`

Successful Response

- BatchAccepted
  - `id` string, required
  - `status` 'pending' | 'processing' | 'completed' | 'failed', required: 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` integer, required

## Other responses

- `401`: `invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.
- `403`: `forbidden`: the key lacks the scope this operation needs; `message` names it.
- `408`: `request_timeout`: a body past 2,097,152 bytes did not arrive whole within 120 s of being let in. Nothing was done; send it again.
- `413`: `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.
- `422`: `invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).
- `429`: `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). And `agent_cap_exceeded`: a new `agent_id` past the plan's named agents (`limit`, `used`).
- `500`: `internal_error`: the server failed on this request; `message` holds no detail of it.
- `503`: 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.

---

[API](https://skmtc.dev/korely/apis/korely-agents-api.md) · [All operations](https://skmtc.dev/korely/apis/korely-agents-api/llms.txt) · [OpenAPI document](https://skmtc.dev/korely/apis/korely-agents-api/revisions/8a40bf09eca1?raw)