openapi: 3.0.3
info:
  title: Cognee REST agents cognify API
  description: 'The Cognee REST API provides endpoints for the complete AI memory lifecycle, including data ingestion, knowledge graph construction, and semantic retrieval. Core endpoints cover adding raw text or documents, triggering the cognify pipeline that extracts entities and relationships via LLM, executing multi-mode search queries, managing datasets, and creating agent identities. The API uses X-Api-Key header authentication for cloud deployments and Bearer token auth for self-hosted instances.

    '
  version: 1.0.0
  contact:
    name: Cognee Support
    url: https://docs.cognee.ai/api-reference/introduction
  license:
    name: Apache 2.0
    url: https://github.com/topoteretes/cognee/blob/main/LICENSE
servers:
- url: https://api.cognee.ai
  description: Cognee Cloud (managed)
- url: http://localhost:8000
  description: Self-hosted (Docker / local)
security:
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: cognify
  description: Knowledge graph construction pipeline
paths:
  /api/v1/cognify:
    post:
      operationId: cognifyDatasets
      summary: Transform datasets into knowledge graphs
      description: 'Core intelligence endpoint that converts raw data into semantic knowledge graphs. Performs document classification, text chunking, entity extraction via LLM, relationship detection, vector embedding generation, and content summarization.

        '
      tags:
      - cognify
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CognifyPayload'
            example:
              datasets:
              - research_papers
              run_in_background: false
              custom_prompt: 'Extract entities focusing on technical concepts and their relationships.

                '
              ontology_key:
              - medical_ontology_v1
      responses:
        '200':
          description: 'Blocking: complete pipeline run info with entity counts and duration. Background: pipeline run metadata including pipeline_run_id.

            '
          content:
            application/json:
              schema:
                type: object
        '400':
          description: No datasets or dataset_ids provided, or datasets not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Pipeline failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/cognify/subscribe/{pipeline_run_id}:
    get:
      operationId: subscribeToCognifyProgress
      summary: Subscribe to cognify pipeline progress via WebSocket
      description: 'WebSocket endpoint to receive real-time pipeline run events. Sends JSON messages with pipeline_run_id, status, and graph payload until the run completes or the client disconnects.

        '
      tags:
      - cognify
      parameters:
      - name: pipeline_run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: UUID of the pipeline run to subscribe to
      responses:
        '101':
          description: WebSocket connection established
        '403':
          description: Authentication required (cookie-based JWT)
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Short error message
        detail:
          type: string
          nullable: true
          description: Detailed error description
      required:
      - error
    CognifyPayload:
      type: object
      properties:
        datasets:
          type: array
          items:
            type: string
          nullable: true
          description: Dataset names to process (resolved to datasets owned by caller)
        dataset_ids:
          type: array
          items:
            type: string
            format: uuid
          nullable: true
          description: Dataset UUIDs to process
          example: []
        run_in_background:
          type: boolean
          description: Execute pipeline asynchronously
          default: false
        graph_model:
          type: object
          nullable: true
          description: Custom graph model schema for entity extraction
          example: {}
        custom_prompt:
          type: string
          nullable: true
          description: Custom prompt for entity extraction and graph generation
          default: ''
        chunk_size:
          type: integer
          nullable: true
          description: Maximum tokens per chunk (auto-sized if omitted)
          example: 4096
        ontology_key:
          type: array
          items:
            type: string
          nullable: true
          description: Keys of previously uploaded ontology files to use
          example: []
        chunks_per_batch:
          type: integer
          nullable: true
          description: Number of chunks to process per task batch
          example: 36
        data_per_batch:
          type: integer
          nullable: true
          description: Maximum data items to process concurrently within a dataset
          default: 20
          example: 20
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token authentication for self-hosted instances
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key authentication for Cognee Cloud deployments
externalDocs:
  description: Cognee API Reference
  url: https://docs.cognee.ai/api-reference/introduction