Skip to main content

​
Before you begin

Every request to the Potpie API requires an x-api-key header.

​
Step 1 : Parse a repository

Parsing builds the knowledge graph for your repository. Every subsequent API call like creating conversations, sending messages requires a project_id from this step. 
curl -X POST http://localhost:8001/api/v2/parse \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_name": "owner/repo",
    "branch_name": "main"
  }'
Request fields
​
repo_name
string
required
GitHub repository in owner/repo format. Required for cloud usage.
​
repo_path
string
Absolute path to a local repository. Only works when isDevelopmentMode=enabled. Use this instead of repo_name for local development.
​
branch_name
string
Branch to parse. If omitted, defaults to null.
​
commit_id
string
Specific commit SHA to parse. If omitted, parses the latest commit on the branch.
Response 
{ "project_id": "<your_project_id>", "status": "submitted" }
Save the project_id . You’ll use it in every request from here on.

​
Step 2 : Wait for parsing to complete

Parsing runs asynchronously. Poll the status endpoint until status is ready before creating a conversation. 
curl http://localhost:8001/api/v2/parsing-status/<your_project_id> \
  -H "x-api-key: YOUR_API_KEY"
Response 
{ "status": "ready", "latest": true }
Status progresses through the following stages in order: submitted → cloned → parsed → processing → inferring → ready If parsing fails at any stage, status becomes error.
Do not create a conversation until status is ready. Requests made before parsing completes will fail.
To manage conversations and messages as separate steps, continue to Step 3. To create a conversation and send a message in a single request, jump to create conversation and send message in one call.

​
Step 3 : Create a conversation

A conversation connects your project to an agent. Choose the agent based on what you want to do. 
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"]
  }'
Available agents
​
codebase_qna_agent
agent
Answers questions about how your codebase works like architecture, logic, dependencies.
​
code_generation_agent
agent
Generates and modifies code based on your instructions, with awareness of existing patterns in the repo.
​
spec_generation_agent
agent
Produces technical specifications from codebase context or a description of what you want to build.
​
debugging_agent
agent
Traces bugs through the codebase and suggests fixes with file paths and line references.
Response The call returns a conversation_id. Use it in all subsequent message requests.

​
Step 4 : Send a message

Send your question or instruction to the conversation. Responses stream by default. 
curl -X POST http://localhost:8001/api/v2/conversations/<your_conversation_id>/message/?stream=true \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How is authentication implemented?"
  }'
Streaming response (stream=true, default) Chunks are yielded as JSON objects as they arrive: 
{ "content": "Authentication is handled in...", "citations": ["app/auth/service.py"], "tool_calls": [] }
Non-streaming response (stream=false) The full response is returned once the agent finishes: 
{
  "content": "Authentication is implemented in...",
  "citations": ["app/auth/service.py", "app/middleware/auth.py"],
  "tool_calls": []
}

​
Create conversation and send message in one call

For quick, one-off queries you can skip managing a conversation_id entirely. This endpoint creates the conversation and sends the first message in a single request. The conversation is hidden from the UI by default. 
curl -X POST http://localhost:8001/api/v2/project/<your_project_id>/message/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How is authentication implemented?",
    "agent_id": "codebase_qna_agent"
  }'
Request fields
​
project_id
string
required
The project ID returned from parsing.
​
hidden
boolean
Whether to hide the conversation from the web UI. Defaults to true.
​
content
string
required
The message to send.
​
agent_id
string
The agent to use. Defaults to codebase_qna_agent.
​
node_ids
array
Optional array of node context objects to focus the query on specific code elements.
Response 
{
  "content": "Authentication is handled in...",
  "citations": ["app/auth/service.py"],
  "tool_calls": []
}