Batch & status

Batch import

Bulk-import up to 500 memories in one async call. Korely enqueues the job and returns a job id immediately; each item is imported later through the same pipeline as a single add. On the Hobby plan a batch can hold fewer items than that (see Notes).

Use this when you're backfilling history or seeding a namespace and don't want to fire hundreds of individual POST /v1/memories calls. The request returns 202 Accepted with a job id; a background worker imports each item, computing its embedding, extracting its facts (extraction) and checking them for contradictions, exactly as a single add would. Poll GET /v1/batch/{job_id} for progress.

Authentication

HTTP header, required: Authorization: Bearer kor_live_..., your API key. The key must carry the memories:write scope.

Request body

Each BatchMemory element has these fields:

Example request

curl -X POST https://api.korely.ai/v1/batch \
  -H "Authorization: Bearer kor_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "memories": [
      {
        "content": "User prefers email follow-ups, not phone",
        "user_id": "customer-giulia-4812",
        "agent_id": "support-bot"
      },
      {
        "content": "Account is on the EU data region",
        "user_id": "customer-giulia-4812",
        "agent_id": "support-bot"
      },
      {
        "content": "Renewal date is 2026-09-01",
        "user_id": "customer-giulia-4812",
        "agent_id": "support-bot",
        "metadata": { "source": "crm" }
      }
    ]
  }'

import requests

resp = requests.post(
    "https://api.korely.ai/v1/batch",
    headers={"Authorization": "Bearer kor_live_..."},
    json={
        "memories": [
            {
                "content": "User prefers email follow-ups, not phone",
                "user_id": "customer-giulia-4812",
                "agent_id": "support-bot",
            },
            {
                "content": "Account is on the EU data region",
                "user_id": "customer-giulia-4812",
                "agent_id": "support-bot",
            },
            {
                "content": "Renewal date is 2026-09-01",
                "user_id": "customer-giulia-4812",
                "agent_id": "support-bot",
                "metadata": {"source": "crm"},
            },
        ]
    },
)

job = resp.json()
print(job["id"])        # "job_8f2c1a..."
print(job["received"])  # 3

const resp = await fetch("https://api.korely.ai/v1/batch", {
  method: "POST",
  headers: {
    Authorization: "Bearer kor_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    memories: [
      {
        content: "User prefers email follow-ups, not phone",
        user_id: "customer-giulia-4812",
        agent_id: "support-bot",
      },
      {
        content: "Account is on the EU data region",
        user_id: "customer-giulia-4812",
        agent_id: "support-bot",
      },
      {
        content: "Renewal date is 2026-09-01",
        user_id: "customer-giulia-4812",
        agent_id: "support-bot",
        metadata: { source: "crm" },
      },
    ],
  }),
});

const job = await resp.json();
console.log(job.id);        // "job_8f2c1a..."
console.log(job.received);  // 3

Work sessions in a batch

from korely_memory import Korely

korely = Korely()  # reads KORELY_API_KEY
job = korely.batch([
    {"content": "Session: added retries to the invoice sender.", "user_id": "dev-team", "kind": "session"},
    {"content": "Invoices go out on the first working day.", "user_id": "dev-team"},
])
print(job.received)  # 2

import { Korely } from "korely-memory";

const korely = new Korely(); // reads KORELY_API_KEY
const job = await korely.batch([
  { content: "Session: added retries to the invoice sender.", user_id: "dev-team", kind: "session" },
  { content: "Invoices go out on the first working day.", user_id: "dev-team" },
]);
console.log(job.received); // 2

An item without kind is a note. Each item is imported with its own kind, so a migration can bring session logs and decisions in one batch. Python 0.1.27 and Node 0.1.17 or later.

Response

202 Accepted. The job has been enqueued; nothing is imported yet. Poll GET /v1/batch/{job_id} to track progress.

{
  "id": "job_8f2c1aab4d7e4f0c9a1b2c3d4e5f6a7b",
  "status": "pending",
  "received": 3
}

Errors

Notes

• It's asynchronous. The POST only enqueues the job and returns immediately (202). A background worker imports each item later through the same steps as POST /v1/memories: the memory is stored, then its facts are extracted.
• Each item counts its writes. One write per 6,000 characters of its text, as an add: an item up to 6,000 characters is one write.
• Counted once, at POST time. The batch's writes and its new agent names are counted when the job is queued; a batch that does not fit the writes left this month, or would pass the agent cap, is refused whole (429) and nothing is stored. The worker does not count the items again.
• Paused, not lost. When Korely has stopped calling language models for the day to cap its spending, the import still stores the memories and the facts are extracted after the pause.
• Webhooks. The worker emits a memory.created webhook for each successful import. A quota.warning webhook fires when the POST's admission crosses 80% of the month's writes.
• Crash-safe and idempotent. The worker claims jobs atomically (SELECT ... FOR UPDATE SKIP LOCKED), uses bounded attempts with exponential backoff, and resumes from the imported + failed offset after a crash, so a restart never double-imports.
• Hard ceiling. A single batch accepts at most 500 items.
• Hobby fits fewer. A batch is counted whole against the month's writes. Hobby has 250 writes a month, 275 with the 10% allowance, so a batch that needs more than 275 writes is always refused there, and 500 items never fit. From Developer upward a 500-item batch fits when the month has room. (Read from the code; not tried on a Hobby account.)

Related

• Batch status, poll GET /v1/batch/{job_id} for progress and per-item errors.
• Add a memory, the single-item write each batch item runs through.
• SDK, the typed client surface.