resource-ingest

Ingest Event

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

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

Path parameters

resource_idstring required

Headers

X-Resource-API-Keystring nullable

Request body

opstring required

Operation: 'upsert' or 'delete'

doc_idstring required

Document ID (stable across versions)

versioninteger nullable

Document version (NULL for delete-all-versions, >=1 for specific version)

payloadobject nullable

Document payload (NULL for delete)

idempotency_keystring nullable

Optional idempotency key for deduplication

event_metadataobject

Additional metadata (source, tenant, etc.)

importancenumber nullable

Memory importance score (0.0-1.0, default 0.6)

Response

Successful Response

statusstring
event_idinteger required

Created event ID

queuedboolean

Whether indexing is queued

estimated_indexing_time_secondsinteger nullable

Estimated time until indexed (seconds, None if unknown)

Changes

No recorded changes to this operation across all 2 revisions of this API.