Skip to content

API Reference

Potpie exposes a REST API for programmatic access to parsing, conversations, and agent management.

Info

The API server runs at http://localhost:8001 for local/self-hosted installations.

Core endpoints

Endpoint Method Description
Parse Directory POST Parse a GitHub repository or local directory to create a knowledge graph
Get Parsing Status GET Check current parsing status of a repository
Create Conversation POST Start a new AI conversation session with a specific agent and project
Post Message POST Send a message to an existing conversation
Create Conversation And Message POST Create conversation and send first message in one call
List Projects GET Retrieve all parsed projects associated with your account
List Agents GET Get all available AI agents with their capabilities
Save Integration POST Save configuration for third-party integrations

Authentication

All API requests require an API key passed via the x-api-key header:

curl -X GET http://localhost:8001/api/v2/projects/ \
  -H "x-api-key: YOUR_API_KEY"

To generate an API key, see your account settings at app.potpie.ai.

Quick example

Create a conversation with the debug agent and send a message:

# Create 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": ["proj_abc123"],
    "agent_ids": ["debugging_agent"]
  }'

# Send a message (use the conversation_id from above)
curl -X POST http://localhost:8001/api/v2/conversations/CONV_ID/message/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Why is the /api/users endpoint returning 500?"
  }'

OpenAPI specification

The full OpenAPI spec is available at:

  • JSON: http://localhost:8001/openapi.json
  • Interactive docs: http://localhost:8001/docs