Skip to main content
The API server must be running at http://localhost:8001 before proceeding. All requests require an x-api-key header with a valid API key.
1

Parse a repository

Submit a repository for parsing. Potpie builds a knowledge graph of every component and relationship across the codebase.
curl -X POST 'http://localhost:8001/api/v2/parse' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"repo_name": "your-org/your-repo", "branch_name": "main"}'
The response returns a project_id for subsequent steps.
2

Check parsing status

Poll this endpoint until status is ready before starting a conversation.
curl 'http://localhost:8001/api/v2/parsing-status/{project_id}' \
  -H 'x-api-key: YOUR_API_KEY'
Possible status values: submitted, processing, ready, failed.
3

List available agents

curl 'http://localhost:8001/api/v2/list-available-agents' \
  -H 'x-api-key: YOUR_API_KEY'
Each agent has an id (e.g. codebase_qna_agent, debugging_agent) for use when creating a conversation.
4

Create a conversation

curl -X POST 'http://localhost:8001/api/v2/conversations/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "project_ids": ["your_project_id"],
    "agent_ids": ["codebase_qna_agent"]
  }'
The response returns a conversation_id for sending messages.
5

Send a message

The endpoint returns a streaming response by default.
curl -X POST 'http://localhost:8001/api/v2/conversations/{conversation_id}/message/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"content": "How does the authentication system work?"}'