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.

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, running embeddings, typed-fact extraction, and contradiction checking, exactly as a single add would. Poll GET /v1/batch/{job_id} for progress.

Authentication

HTTP header, required: Authorization: Bearer kor_live_.... 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

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

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 pipeline as POST /v1/memories, engine.add plus best-effort typed-fact extraction.
• 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. While the service's daily model budget is spent, the import continues 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.

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.