Skip to main content
The Potpie API follows REST conventions. Authenticate with an API key in the x-api-key header. Parse a repository, open a conversation with an agent, and retrieve structured answers with exact file and line citations.

​
Generating an API Key

1

Sign in to the dashboard

Open Potpie and sign in.Potpie Dashboard
2

Open Settings

Click the account menu in the bottom-left corner and select Settings.Username menu
3

Generate an API key

In the API Key section, click + Generate API Key.API Key Management
4

Copy the key

The key appears once. Copy and store it securely.Generated API Key

​
API Workflow

All API interactions follow a four-stage sequence. Each stage requires the previous to succeed.
The /api/v2 endpoints use API key authentication.
1

Parse the repository

Submit a parse request to index the repository and build the knowledge graph. The response returns a project_id used in all subsequent requests.Endpoint: POST /api/v2/parseHeaders:
x-api-key: your_api_key_here
Request:
{
  "repo_name": "potpie-ai/potpie",
  "branch_name": "main"
}
Response: Returns a project_id for use in subsequent requests.
2

Check parsing status

Poll the status endpoint before proceeding. Conversation creation fails if parsing has not completed. The inferring status indicates inference is still running.Endpoint: GET /api/v2/parsing-status/{project_id}Headers:
x-api-key: your_api_key_here
Proceed once the response contains "status": "ready".
3

Create a conversation

Initialize a conversation by specifying the project and agent. The response returns a conversation_id for subsequent messages.Endpoint: POST /api/v2/conversations/Headers:
x-api-key: your_api_key_here
Request:
{
  "project_ids": ["your_project_id"],
  "agent_ids": ["codebase_qna_agent"]
}
Each conversation supports exactly one project ID and one agent ID.
4

Send a message

Submit a message to the conversation. The agent processes the query and returns a structured response with citations.Endpoint: POST /api/v2/conversations/{conversation_id}/message/Headers:
x-api-key: your_api_key_here
Request:
{
  "content": "Where is authentication implemented?"
}
Query Parameters:
  • stream (boolean, default: true): Set to false to receive the full response as a single JSON object.
Response:
{
  "message": "Markdown-formatted answer with citations",
  "tool_calls": [],
  "citations": ["app/auth/service.py", "app/middleware/auth.py"]
}