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

# Ingest Event

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

## 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`
- Auth: none declared

Ingest a single resource event (upsert or delete).

Issue #238: Append-only event log for incremental indexing.

The ``resource_id`` URL path parameter accepts the human-readable slug
(e.g. ``my-github-repo``). Internally, token verification resolves the
request context from that identifier (see ``verify_resource_token`` and
``_resolve_authoritative_context``), and workspace access is enforced as
a separate validation step. The authoritative resource record used for
writes is then taken from the verified token record
(``token_record.resource_pk``), so external callers never need to know or
supply UUIDs.

Security:
    - Requires X-Resource-API-Key header
    - Token must be scoped to this resource_id
    - Rate limited by quota_events_per_hour

Request:
    POST /api/v1/resources/{resource_id}/events
    Headers:
        X-Resource-API-Key: kagura_resource_...
    Body:
        {
            "op": "upsert",
            "doc_id": "PROD-12345",
            "version": 3,
            "payload": {"product_name": "...", "price": 5980},
            "idempotency_key": "optional-key"
        }

Response:
    {
        "status": "success",
        "event_id": 12345,
        "queued": true,
        "estimated_indexing_time_seconds": 600
    }

Errors:
    - 401: Invalid/revoked token
    - 409: Duplicate version (resource_id, doc_id, version already exists)
    - 413: Payload too large (>100KB)
    - 422: Validation error (e.g., missing payload for upsert)
    - 429: Quota exceeded

## Path parameters

- `resource_id` string, required

## Headers

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

## Request body

- ResourceEventRequest: Request schema for resource event ingestion. Issue #238: Resource-driven incremental indexing. Example: { "op": "upsert", "doc_id": "PROD-12345", "version": 3, "payload": { "product_name": "ワイヤレスイヤホン", "price": 5980, "category": "オーディオ" }, "idempotency_key": "unique-client-key-123" }
  - `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

- ResourceEventResponse: Response schema for resource event ingestion.
  - `status` string
  - `event_id` integer, required: Created event ID
  - `queued` boolean: Whether indexing is queued
  - `estimated_indexing_time_seconds` integer, nullable: Estimated time until indexed (seconds, None if unknown)

## 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)