---
title: "Ingest Batch"
method: POST
path: "/api/v1/resources/{resource_id}/events/batch"
tags: ["resource-ingest"]
---

# Ingest Batch

`POST /api/v1/resources/{resource_id}/events/batch`

## Request

- Base URL: `https://memory.kagura-ai.com` (the document declares no server; this is the origin it was published from)
- URL: `https://memory.kagura-ai.com/api/v1/resources/{resource_id}/events/batch`
- Auth: none declared

Ingest multiple resource events in a single request.

Issue #238: Batch ingestion for efficiency (up to 100 events).

Security:
    - Same as single event ingestion
    - Quota checked for entire batch

Request:
    POST /api/v1/resources/{resource_id}/events/batch
    Headers:
        X-Resource-API-Key: kagura_resource_...
    Body:
        {
            "events": [
                {"op": "upsert", "doc_id": "PROD-1", "version": 1, "payload": {...}},
                {"op": "delete", "doc_id": "PROD-999", "version": 5}
            ]
        }

Response:
    {
        "status": "success",
        "created_count": 2,
        "failed_count": 0,
        "event_ids": [12345, 12346],
        "errors": []
    }

Errors:
    - 401: Invalid/revoked token
    - 403: Cross-tenant ingest blocked (Issue #322)
    - 404: Resource not bound to an active Context
    - 422: Validation error (max 100 events)
    - 429: Quota exceeded

## Path parameters

- `resource_id` string, required

## Headers

- `X-Resource-API-Key` string, nullable

## Request body

- ResourceEventBatchRequest: Request schema for batch resource event ingestion. Issue #238: Batch upsert/delete for efficiency. Example: { "events": [ {"op": "upsert", "doc_id": "PROD-1", "version": 1, "payload": {...}}, {"op": "upsert", "doc_id": "PROD-2", "version": 1, "payload": {...}}, {"op": "delete", "doc_id": "PROD-999", "version": 5} ] }
  - `events` ResourceEventRequest[], required: Events (max 100)
    - `op` string, required: Operation: 'upsert' or 'delete'
    - `doc_id` string, required: Document ID (stable across versions)
    - `version` integer, nullable: Document version (NULL for delete-all-versions, >=1 for specific version)
    - `payload` object, nullable: Document payload (NULL for delete)
    - `idempotency_key` string, nullable: Optional idempotency key for deduplication
    - `event_metadata` object: Additional metadata (source, tenant, etc.)
    - `importance` number, nullable: Memory importance score (0.0-1.0, default 0.6)

## Response `201`

Successful Response

- ResourceEventBatchResponse: Response schema for batch resource event ingestion.
  - `status` string
  - `created_count` integer, required: Number of events created
  - `failed_count` integer: Number of events that failed
  - `event_ids` integer[]: Created event IDs
  - `errors` object[]: Error details for failed events

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud.md) · [All operations](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/llms.txt) · [OpenAPI document](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/revisions/09f17f5ada29?raw)