trustgraph/specs/api/paths/import-core.yaml

post:
  tags:
    - Import/Export
  summary: Import Core - bulk import triples and embeddings
  description: |
    Import knowledge cores in bulk using streaming MessagePack format.

    ## Import Core Overview

    Bulk data import for knowledge graph:
    - **Format**: MessagePack streaming
    - **Content**: Triples and/or graph embeddings
    - **Target**: Global knowledge storage
    - **Use**: Backup restoration, data migration, bulk loading

    ## MessagePack Protocol

    Request body is MessagePack stream with message tuples:

    ### Triple Message
    ```
    ("t", {
      "m": {              // Metadata
        "i": "core-id",   // Knowledge core ID
        "m": [...],       // Metadata triples array
        "u": "user",      // User
        "c": "collection" // Collection
      },
      "t": [...]          // Triples array
    })
    ```

    ### Graph Embeddings Message
    ```
    ("ge", {
      "m": {              // Metadata
        "i": "core-id",
        "m": [...],
        "u": "user",
        "c": "collection"
      },
      "e": [              // Entities array
        {
          "e": {"v": "uri", "e": true},  // Entity RdfValue
          "v": [0.1, 0.2, ...]             // Vectors
        }
      ]
    })
    ```

    ## Query Parameters

    - **id**: Knowledge core ID
    - **user**: User identifier

    ## Streaming

    Multiple messages can be sent in stream.
    Each message processed as received.
    No response body - returns 202 Accepted.

    ## Use Cases

    - **Backup restoration**: Restore from export
    - **Data migration**: Move data between systems
    - **Bulk loading**: Initial knowledge base population
    - **Replication**: Copy knowledge cores

  operationId: importCore
  security:
    - bearerAuth: []
  parameters:
    - name: id
      in: query
      required: true
      schema:
        type: string
      description: Knowledge core ID to import
      example: core-123
    - name: user
      in: query
      required: true
      schema:
        type: string
      description: User identifier
      example: alice
  requestBody:
    required: true
    content:
      application/msgpack:
        schema:
          type: string
          format: binary
          description: MessagePack stream of knowledge data
  responses:
    '202':
      description: Import accepted and processing
      content:
        application/json:
          schema:
            type: object
            properties: {}
    '401':
      $ref: '../components/responses/Unauthorized.yaml'
    '500':
      $ref: '../components/responses/Error.yaml'