Skip to main content
POST
/
api
/
v2
/
parse
curl --request POST \
  --url http://localhost:8001/api/v2/parse \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "repo_path": "/path/to/local/repo",
  "branch_name": "main"
}
'
{
  "project_id": "proj_123",
  "status": "submitted"
}

​
Use Cases

  • Initiate repository parsing to build knowledge graph
  • Parse specific branches for version-specific analysis
  • Index local repositories during development
  • Parse remote public or private GitHub repositories
  • Build semantic understanding of codebase structure

​
Request

​
repo_name
string
Repository name in owner/repo format (e.g., "facebook/react")
​
repo_path
string
Local filesystem path to repository (development mode only)
​
branch_name
string
Branch to parse (e.g., "main")
​
commit_id
string
Specific commit SHA to parse
Either repo_name or repo_path must be provided. In development mode, when both are provided, repo_path takes precedence. In production, repo_path is not accepted.

​
Response

​
project_id
string
Unique identifier to check parsing status
​
status
string
Current parsing state: submitted (queued for parsing), processing (parsing in progress), inferring (knowledge graph inference in progress), ready (fully parsed), or error (parse failed)

​
Complete Workflow

import requests
import time

# 1. Start parsing
response = requests.post(
    'http://localhost:8001/api/v2/parse',
    headers={'x-api-key': 'YOUR_API_KEY'},
    json={
        'repo_name': 'facebook/react',
        'branch_name': 'main'
    }
)

# Response: {"project_id": "proj_123", "status": "submitted"}
project_id = response.json()['project_id']

# 2. Monitor status until complete
while True:
    status = requests.get(
        f'http://localhost:8001/api/v2/parsing-status/{project_id}',
        headers={'x-api-key': 'YOUR_API_KEY'}
    ).json()

    print(f"{status['status']}")

    if status['status'] in ['ready', 'error']:
        break

    time.sleep(10)

# 3. Use the parsed project
if status['status'] == 'ready':
    print(f"Project {project_id} is ready!")

​
Error Responses

Local Repository in ProductionThe endpoint rejects local repository paths when the application runs in production mode. Local parsing is restricted to development environments for security.
{
  "detail": "Parsing local repositories is only supported in development mode"
}
How to fix: Use repo_name to parse remote repositories in production. For local development, enable development mode in your environment configuration.
Missing API KeyThe endpoint requires API key authentication for all requests. The request fails when no x-api-key header is provided.
{
  "detail": "API key is required"
}
How to fix: Include a valid API key in the request header:
x-api-key: YOUR_API_KEY
Invalid API KeyThe endpoint validates all API keys. The request fails when the API key is invalid or has expired.
{
  "detail": "Invalid API key"
}
Common causes:
  • API key has expired
  • API key is malformed or corrupted
  • API key has been revoked
  • API key does not belong to your account
How to fix: Generate a new API key from your account settings and update your application configuration.
The endpoint returns this error when unexpected exceptions occur during parsing operations.
{
  "detail": "Internal server error"
}
Common causes:
  • Database connection failures
  • File system errors during parsing
  • Memory errors with very large repositories
  • Network failures when cloning remote repositories
  • Third-party service unavailability
How to fix: Retry the request with exponential backoff. If the issue persists, contact support with your project_id for debugging assistance.

​
Troubleshooting

Problem: Parser cannot access the repository.Solution:
  • Verify the repository name uses owner/repo format (e.g., "facebook/react")
  • Ensure the repository is public or you have access
  • Check if the repository exists and hasn’t been deleted or moved
  • For private repositories, ensure proper authentication
Problem: The specified branch cannot be found.Solution:
  • Verify the branch name is correct (case-sensitive)
  • Check that the branch exists in the repository
  • Use the default branch name (usually “main” or “master”) if unsure
  • List available branches in your repository to confirm the name
Problem: Parsing doesn’t complete within expected time.Solution:
  • Large repositories naturally take longer (10-30 minutes)
  • Check parsing status regularly to monitor progress
  • Very large monorepos may timeout — consider parsing specific directories
  • Contact support if parsing exceeds 1 hour
Problem: Using repo_path for local repositories fails.Solution:
  • Local repository parsing only works in development mode
  • Production environments must use repo_name for remote repositories
  • Use repo_name with owner/repo format for production deployments

Authorizations

​
x-api-key
string
header
required

API key authentication. Get your key from potpie settings page

Body

application/json
​
repo_name
string

Repository name in owner/repo format (optional if repo_path is provided)

Example:

"facebook/react"

​
repo_path
string

Local filesystem path to repository (development mode only, optional if repo_name is provided)

Example:

"/path/to/local/repo"

​
branch_name
string

Branch to parse (optional)

Example:

"main"

​
commit_id
string

Specific commit SHA to parse (optional)

Example:

"2c3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e"

Response

Parsing initiated successfully

​
project_id
string

Unique project identifier

​
status
enum<string>

Current parsing state

Available options:
submitted,
inferring,
ready