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:

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.

3. Ask questions (search)

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

• Explore the API Reference for a complete list of endpoints.
• Learn about Search Types to tailor retrieval behaviour.
• Follow the SDK Quickstart for an end-to-end walkthrough.