> ## Documentation Index
> Fetch the complete documentation index at: https://docs.potpie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Parse Directory

> Initiate parsing of a repository or directory to build Potpie's knowledge graph. This analyzes your codebase structure, relationships, and creates the foundational data that enables AI agents to understand and work with your code.

## 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

<ParamField body="repo_name" type="string">
  Repository name in `owner/repo` format (e.g., `"facebook/react"`)
</ParamField>

<ParamField body="repo_path" type="string">
  Local filesystem path to repository (development mode only)
</ParamField>

<ParamField body="branch_name" type="string">
  Branch to parse (e.g., `"main"`)
</ParamField>

<ParamField body="commit_id" type="string">
  Specific commit SHA to parse
</ParamField>

<Note>
  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.
</Note>

#### Response

<ResponseField name="project_id" type="string">
  Unique identifier to check parsing status
</ResponseField>

<ResponseField name="status" type="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)
</ResponseField>

## Complete Workflow

<CodeGroup>
  ```python Python theme={null}
  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!")
  ```

  ```typescript TypeScript theme={null}
  // 1. Start parsing
  const response = await fetch(
    'http://localhost:8001/api/v2/parse',
    {
      method: 'POST',
      headers: {
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        repo_name: 'facebook/react',
        branch_name: 'main'
      })
    }
  );

  // Response: {"project_id": "proj_123", "status": "submitted"}
  const { project_id } = await response.json();

  // 2. Monitor status until complete
  while (true) {
    const statusRes = await fetch(
      `http://localhost:8001/api/v2/parsing-status/${project_id}`,
      {
        headers: { 'x-api-key': 'YOUR_API_KEY' }
      }
    );

    const status = await statusRes.json();
    console.log(`${status.status}`);

    if (['ready', 'error'].includes(status.status)) {
      break;
    }

    await new Promise(resolve => setTimeout(resolve, 10000));
  }

  // 3. Use the parsed project
  console.log(`Project ${project_id} is ready!`);
  ```

  ```bash cURL theme={null}
  # 1. Start parsing
  curl -X POST \
    'http://localhost:8001/api/v2/parse' \
    -H 'x-api-key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "repo_name": "facebook/react",
      "branch_name": "main"
    }'

  # Response: {"project_id": "proj_123", "status": "submitted"}

  # 2. Monitor status
  curl -X GET \
    'http://localhost:8001/api/v2/parsing-status/proj_123' \
    -H 'x-api-key: YOUR_API_KEY'

  # Response: {"status": "ready", "latest": true}
  ```
</CodeGroup>

## Error Responses

<AccordionGroup>
  <Accordion title="400 Bad Request">
    **Local Repository in Production**

    The endpoint rejects local repository paths when the application runs in production mode. Local parsing is restricted to development environments for security.

    ```json theme={null}
    {
      "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.
  </Accordion>

  <Accordion title="401 Unauthorized">
    **Missing API Key**

    The endpoint requires API key authentication for all requests. The request fails when no `x-api-key` header is provided.

    ```json theme={null}
    {
      "detail": "API key is required"
    }
    ```

    **How to fix:** Include a valid API key in the request header:

    ```bash theme={null}
    x-api-key: YOUR_API_KEY
    ```

    ***

    **Invalid API Key**

    The endpoint validates all API keys. The request fails when the API key is invalid or has expired.

    ```json theme={null}
    {
      "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.
  </Accordion>

  <Accordion title="500 Internal Server Error">
    The endpoint returns this error when unexpected exceptions occur during parsing operations.

    ```json theme={null}
    {
      "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.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Repository not accessible">
    **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
  </Accordion>

  <Accordion title="Branch doesn't exist">
    **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
  </Accordion>

  <Accordion title="Parsing takes too long">
    **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
  </Accordion>

  <Accordion title="Local path not working">
    **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
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml POST /api/v2/parse
openapi: 3.1.0
info:
  title: Potpie API
  version: 2.0.0
  description: >-
    AI-powered codebase intelligence API. Build powerful integrations with
    Potpie's parsing, conversation, search, and agent capabilities.
  contact:
    name: Potpie Support
    email: hi@potpie.ai
    url: https://potpie.ai
  license:
    name: Proprietary
    url: https://potpie.ai/terms
servers:
  - url: http://localhost:8001
    description: Local server
security:
  - ApiKeyAuth: []
tags:
  - name: Parsing
    description: Repository parsing and status management
  - name: Projects
    description: Project management and listing
  - name: Conversations
    description: AI conversation management
  - name: Agents
    description: AI agent information and selection
  - name: Search
    description: Codebase semantic search
  - name: Integrations
    description: External service integrations
paths:
  /api/v2/parse:
    post:
      tags:
        - Parsing
      summary: Parse Directory
      description: >-
        Initiate parsing of a repository or directory to build Potpie's
        knowledge graph. This analyzes your codebase structure, relationships,
        and creates the foundational data that enables AI agents to understand
        and work with your code.
      operationId: parseDirectory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParsingRequest'
            examples:
              local_repo:
                summary: Parse local repository
                value:
                  repo_path: /path/to/local/repo
                  branch_name: main
              remote_repo:
                summary: Parse remote repository
                value:
                  repo_name: facebook/react
                  branch_name: main
                  commit_id: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
      responses:
        '200':
          description: Parsing initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParsingResponse'
              example:
                project_id: proj_123
                status: submitted
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    ParsingRequest:
      type: object
      properties:
        repo_name:
          type: string
          description: >-
            Repository name in owner/repo format (optional if repo_path is
            provided)
          example: facebook/react
        repo_path:
          type: string
          description: >-
            Local filesystem path to repository (development mode only, optional
            if repo_name is provided)
          example: /path/to/local/repo
        branch_name:
          type: string
          description: Branch to parse (optional)
          example: main
        commit_id:
          type: string
          description: Specific commit SHA to parse (optional)
          example: 2c3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e
    ParsingResponse:
      type: object
      properties:
        project_id:
          type: string
          description: Unique project identifier
        status:
          type: string
          enum:
            - submitted
            - inferring
            - ready
          description: Current parsing state
  responses:
    BadRequest:
      description: Bad request - Invalid parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
          example:
            detail: Either repo_name or repo_path must be provided
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
          example:
            detail: Invalid API key
    Forbidden:
      description: Forbidden - Development mode required for this operation
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
          example:
            detail: Development mode is not enabled, cannot parse local repository.
    ValidationError:
      description: Validation error - Invalid request body
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: array
                items:
                  type: object
                  properties:
                    loc:
                      type: array
                      items:
                        type: string
                    msg:
                      type: string
                    type:
                      type: string
          example:
            detail:
              - loc:
                  - body
                  - project_id
                msg: field required
                type: value_error.missing
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key authentication. Get your key from <a
        href="https://app.potpie.ai/settings" style="color: #60a5fa;
        font-weight: bold; text-decoration: none !important;">potpie settings
        page</a>

````