---
title: "Ingest Knowledge Graph"
method: POST
path: "/helixdb/etl/ingest-kg"
tags: ["HelixDB", "HelixDB ETL"]
---

# Ingest Knowledge Graph

`POST /helixdb/etl/ingest-kg`

## Request

- Base URL: `https://api.getmetacognition.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.getmetacognition.com/helixdb/etl/ingest-kg`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/metacognition/apis/tex-api/docs/helixdb/etl/ingest-kg/post.ts> (a function with typed inputs; its response is checked against the schema)

Knowledge-graph ingestion.

Optional `scope` ("<kind>:<value>") is the write stamp for the ingested
graph; must be within the caller's visible scopes (403 otherwise).
Defaults to user:<user_id>.

## Request body

- IngestKGRequest: Knowledge graph ingestion request.
  - `chunks` DocumentChunk[], required: Document chunks
    - `element_id` string, required: Unique element identifier
    - `text` string, required: Chunk text content
    - `metadata` ChunkMetadata, required: Document chunk metadata.
      - `entities` EntityMetadata, required: Entity metadata.
        - `items` EntityItem[]: Entities
          - `entity` string, required: Entity name
          - `type` string, required: Entity type
          - `aliases` string[]: Entity aliases
          - `confidence` string, required: Confidence level
          - `context` string, required: Entity context
        - `relationships` RelationshipItem[]: Relationships
          - `from` string, required: Source entity
          - `relationship` string, required: Relationship type
          - `to` string, required: Target entity
          - `confidence` string, required: Confidence level
          - `context` string, required: Relationship context
        - `inferred` string[]: Inferred statements
      - `filename` string, nullable: Source filename
      - `filetype` string, nullable: File type
      - `page_number` integer, nullable: Page number
  - `options` IngestKGOptions: Knowledge graph ingestion options.
    - `auto_create_schema` boolean: Auto-create schema
    - `generate_embeddings` boolean: Generate embeddings
    - `validate` boolean: Validate entities
    - `store_chunks` boolean: Store original chunks
  - `scope` string, nullable: Optional explicit write scope "<kind>:<value>" (kinds: user/team/org/project). Must be within the caller's visible scopes; defaults to user:<user_id>.

## Response `200`

Successful Response

- IngestKGResponse: Knowledge graph ingestion response.
  - `success` boolean, required: Whether ingestion succeeded
  - `stats` IngestStats: Knowledge graph ingestion statistics.
    - `total_chunks_processed` integer
    - `raw_entities` integer
    - `deduplicated_entities` integer
    - `entities_by_type` object
    - `entities_inserted` integer
    - `entities_merged` integer
    - `raw_relationships` integer
    - `resolved_relationships` integer
    - `relationships_inserted` integer
    - `vectors_inserted` integer
    - `inferences_count` integer
    - `inferences_attached` integer
    - `node_types_created` string[]
    - `edge_types_created` string[]
    - `schema_created` boolean
  - `errors` string[]: Error messages

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/metacognition/apis/tex-api.md) - [All operations](https://skmtc.dev/metacognition/apis/tex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/metacognition/apis/tex-api/revisions/3bef47e50f2e?raw)