Cognee Responses API Reference

Overview

The Cognee Responses API is an OpenAI-compatible interface that lets you interact with Cognee’s knowledge-graph pipeline using familiar chat.completions-style calls. It provides two function tools:
FunctionPurpose
cognifyConvert raw content into a knowledge graph
searchQuery the knowledge graph with natural-language questions
Because the interface follows the OpenAI schema you can keep using the official openai Python SDK—just point base_url at your Cognee backend and use client.responses.* methods.
Note: All examples assume a local backend running at http://localhost:8000 and an API key of sk-local.

Prerequisites

  • Docker installed on your system
  • Cognee backend running locally and accessible at http://localhost:8000
  • An LLM API key (OpenAI, OpenRouter, or other provider)
  • Basic familiarity with HTTP APIs and cURL
  • Understanding of function calling concepts

Using the API in Your Applications

Start Cognee API Service

Pull and run the Cognee Docker container with the Responses API enabled:
# Pull the latest Cognee image
docker pull cognee/cognee:main

# Start the service with your environment file
docker run -d -p 8000:8000 --name cognee_responses \\
  -v $(pwd)/.env:/app/.env \\
  cognee/cognee:main

This starts Cognee with both the standard API and the OpenAI-compatible Responses API available. Verify the service is running:
curl <http://localhost:8000/health>


1. Add content

import httpx

BASE_URL = "http://localhost:8000"

text = (
    "Alan Turing was a pioneering computer scientist. "
    "He worked at Bletchley Park and proposed the Turing Test."
)

payload = {"data": text}
resp = httpx.post(f"{BASE_URL}/api/v1/add", json=payload, timeout=30, follow_redirects=True)
resp.raise_for_status()
print(resp.json())

2. Build the graph (cognify)

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/api/v1", api_key="sk-local")

cognify_call = client.responses.create(
    model="cognee-v1",
    input="Please build a graph from the new text.",
    tool_choice={"type": "function", "name": "cognify"},
    temperature=0.0,   # deterministic
)
print(cognify_call.tool_calls[0].output)
The call invokes the cognify tool on the backend and returns the pipeline status in tool_calls[0].output.
search_call = client.responses.create(
    model="cognee-v1",
    input="Who proposed the Turing Test?",
    tool_choice={"type": "function", "name": "search"},
    temperature=0.0,
)
print(search_call.tool_calls[0].output)
The backend executes the search tool and returns structured results.

Next Steps