Kagura AI Resource Ingest API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Resource Ingest API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: resource-ingest
  description: External data ingestion API
paths:
  /api/v1/resources/{resource_id}/events:
    post:
      tags:
      - resource-ingest
      summary: Ingest Event
      description: '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'
      operationId: ingest_event_api_v1_resources__resource_id__events_post
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          title: Resource Id
      - name: X-Resource-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Resource-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResourceEventRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceEventResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/resources/{resource_id}/events/batch:
    post:
      tags:
      - resource-ingest
      summary: Ingest Batch
      description: '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'
      operationId: ingest_batch_api_v1_resources__resource_id__events_batch_post
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          title: Resource Id
      - name: X-Resource-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Resource-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResourceEventBatchRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceEventBatchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ResourceEventBatchResponse:
      properties:
        status:
          type: string
          title: Status
          default: success
        created_count:
          type: integer
          title: Created Count
          description: Number of events created
        failed_count:
          type: integer
          title: Failed Count
          description: Number of events that failed
          default: 0
        event_ids:
          items:
            type: integer
          type: array
          title: Event Ids
          description: Created event IDs
        errors:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Errors
          description: Error details for failed events
      type: object
      required:
      - created_count
      title: ResourceEventBatchResponse
      description: Response schema for batch resource event ingestion.
    ResourceEventBatchRequest:
      properties:
        events:
          items:
            $ref: '#/components/schemas/ResourceEventRequest'
          type: array
          maxItems: 100
          minItems: 1
          title: Events
          description: Events (max 100)
      type: object
      required:
      - events
      title: ResourceEventBatchRequest
      description: "Request schema for batch resource event ingestion.\n\nIssue #238: Batch upsert/delete for efficiency.\n\nExample:\n    {\n        \"events\": [\n            {\"op\": \"upsert\", \"doc_id\": \"PROD-1\", \"version\": 1, \"payload\": {...}},\n            {\"op\": \"upsert\", \"doc_id\": \"PROD-2\", \"version\": 1, \"payload\": {...}},\n            {\"op\": \"delete\", \"doc_id\": \"PROD-999\", \"version\": 5}\n        ]\n    }"
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ResourceEventRequest:
      properties:
        op:
          type: string
          pattern: ^(upsert|delete)$
          title: Op
          description: 'Operation: ''upsert'' or ''delete'''
        doc_id:
          type: string
          maxLength: 255
          minLength: 1
          title: Doc Id
          description: Document ID (stable across versions)
        version:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Version
          description: Document version (NULL for delete-all-versions, >=1 for specific version)
        payload:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Payload
          description: Document payload (NULL for delete)
        idempotency_key:
          anyOf:
          - type: string
            maxLength: 255
            minLength: 1
          - type: 'null'
          title: Idempotency Key
          description: Optional idempotency key for deduplication
        event_metadata:
          additionalProperties: true
          type: object
          title: Event Metadata
          description: Additional metadata (source, tenant, etc.)
        importance:
          anyOf:
          - type: number
            maximum: 1.0
            minimum: 0.0
          - type: 'null'
          title: Importance
          description: Memory importance score (0.0-1.0, default 0.6)
      type: object
      required:
      - op
      - doc_id
      title: ResourceEventRequest
      description: "Request schema for resource event ingestion.\n\nIssue #238: Resource-driven incremental indexing.\n\nExample:\n    {\n        \"op\": \"upsert\",\n        \"doc_id\": \"PROD-12345\",\n        \"version\": 3,\n        \"payload\": {\n            \"product_name\": \"ワイヤレスイヤホン\",\n            \"price\": 5980,\n            \"category\": \"オーディオ\"\n        },\n        \"idempotency_key\": \"unique-client-key-123\"\n    }"
    ResourceEventResponse:
      properties:
        status:
          type: string
          title: Status
          default: success
        event_id:
          type: integer
          title: Event Id
          description: Created event ID
        queued:
          type: boolean
          title: Queued
          description: Whether indexing is queued
          default: true
        estimated_indexing_time_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          title: Estimated Indexing Time Seconds
          description: Estimated time until indexed (seconds, None if unknown)
      type: object
      required:
      - event_id
      title: ResourceEventResponse
      description: Response schema for resource event ingestion.