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

# List Projects

> Get a list of all projects using API key authentication

## Use Cases

* Display available projects in your application
* Verify a project exists before creating conversations
* Check project parsing status and metadata
* Build project selection interfaces
* Monitor project creation and management

## Authentication

This endpoint requires API key authentication via the `x-api-key` header.

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

<AccordionGroup>
  <Accordion title="Request & Response">
    | Location | Field       | Type   | Required | Description                                                                |
    | -------- | ----------- | ------ | -------- | -------------------------------------------------------------------------- |
    | Response | `id`        | string | -        | Unique project identifier (UUID) - use this for conversations and searches |
    | Response | `repo_name` | string | -        | Repository name (e.g., "facebook/react")                                   |
    | Response | `status`    | string | -        | Current project status (see Project Status table below)                    |
  </Accordion>
</AccordionGroup>

## Project Status

Projects can have different statuses:

| Status       | Description                           | Actions Available            |
| ------------ | ------------------------------------- | ---------------------------- |
| `submitted`  | Parsing queued but not started        | Wait for processing          |
| `cloned`     | Repository cloned successfully        | Wait for processing          |
| `parsed`     | Code structure analyzed               | Wait for processing          |
| `processing` | Building knowledge graph              | Wait for completion          |
| `inferring`  | Generating knowledge graph inferences | Wait for completion          |
| `ready`      | Ready for use                         | All operations available     |
| `error`      | Parsing failed                        | Review errors, retry parsing |

## Error Responses

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    The endpoint requires a valid API key for authentication.

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

    **Causes:**

    * Missing `x-api-key` header
    * Invalid or expired API key
    * API key doesn't match any user account

    **Solution:** Include a valid API key in the request header:

    ```bash theme={null}
    x-api-key: YOUR_API_KEY
    ```
  </Accordion>

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

    ```json theme={null}
    {
      "detail": "<exception message>"
    }
    ```

    **Causes:**

    * Database connection failures
    * Service unavailability

    **Solution:** Retry the request after a brief delay. If the issue persists, contact support.
  </Accordion>
</AccordionGroup>

## Complete Workflow

<CodeGroup>
  ```typescript TypeScript theme={null}
  const response = await fetch(
    'http://localhost:8001/api/v2/projects/list',
    {
      headers: {
        'x-api-key': 'YOUR_API_KEY'
      }
    }
  );

  const projects = await response.json();

  console.log(`Total projects: ${projects.length}`);
  projects.forEach(project => {
    console.log(`- ${project.repo_name} - ${project.status}`);
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'http://localhost:8001/api/v2/projects/list',
      headers={'x-api-key': 'YOUR_API_KEY'}
  )

  projects = response.json()

  print(f"Total projects: {len(projects)}")
  for project in projects:
      print(f"- {project['repo_name']} - {project['status']}")
  ```

  ```bash cURL theme={null}
  # List all projects
  curl -X GET \
    'http://localhost:8001/api/v2/projects/list' \
    -H 'x-api-key: YOUR_API_KEY'

  # Pretty print with jq
  curl -X GET \
    'http://localhost:8001/api/v2/projects/list' \
    -H 'x-api-key: YOUR_API_KEY' | jq '.'
  ```
</CodeGroup>

## Building a Project Dashboard

```typescript theme={null}
// React component example
import { useEffect, useState } from 'react';

interface Project {
  id: string;
  repo_name: string;
  status: string;
}

function ProjectDashboard() {
  const [projects, setProjects] = useState<Project[]>([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function loadProjects() {
      try {
        const response = await fetch(
          'http://localhost:8001/api/v2/projects/list',
          {
            headers: {
              'x-api-key': process.env.POTPIE_API_KEY
            }
          }
        );
        const data = await response.json();
        setProjects(data);
      } catch (error) {
        console.error('Failed to load projects:', error);
      } finally {
        setLoading(false);
      }
    }

    loadProjects();
  }, []);

  if (loading) return <div>Loading projects...</div>;

  return (
    <div>
      <h2>Your Projects ({projects.length})</h2>
      <ul>
        {projects.map(project => (
          <li key={project.id}>
            <strong>{project.repo_name}</strong>
            <span className={`status ${project.status}`}>
              {project.status}
            </span>
          </li>
        ))}
      </ul>
    </div>
  );
}
```

## Filtering and Sorting

```javascript theme={null}
// Filter projects by status
const readyProjects = projects.filter(p => p.status === 'ready');
const processingProjects = projects.filter(p => p.status === 'processing');

// Sort by name alphabetically
const alphabeticalProjects = [...projects].sort((a, b) =>
  a.repo_name.localeCompare(b.repo_name)
);

// Group by status
const projectsByStatus = projects.reduce((acc, project) => {
  if (!acc[project.status]) {
    acc[project.status] = [];
  }
  acc[project.status].push(project);
  return acc;
}, {});
```

## Common Patterns

### Project Selector Component

```typescript theme={null}
function ProjectSelector({ onSelect }: { onSelect: (projectId: string) => void }) {
  const [projects, setProjects] = useState<Project[]>([]);

  useEffect(() => {
    fetchProjects().then(setProjects);
  }, []);

  const readyProjects = projects.filter(p => p.status === 'ready');

  return (
    <select onChange={(e) => onSelect(e.target.value)}>
      <option value="">Select a project...</option>
      {readyProjects.map(project => (
        <option key={project.id} value={project.id}>
          {project.repo_name}
        </option>
      ))}
    </select>
  );
}
```

### Project Validation

```typescript theme={null}
async function validateProject(projectId: string): Promise<boolean> {
  const projects = await getProjects();
  const project = projects.find(p => p.id === projectId);

  if (!project) {
    console.error(`Project ${projectId} not found`);
    return false;
  }

  if (project.status !== 'ready') {
    console.error(`Project ${projectId} is not ready (status: ${project.status})`);
    return false;
  }

  return true;
}
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Empty project list">
    **Problem:** API returns an empty array `[]`.

    **Solution:**

    * This is normal if you haven't created any projects yet
    * Use the Parse Directory endpoint to create your first project
    * Verify you're using the correct API key for your account
    * Check that projects weren't accidentally deleted
  </Accordion>

  <Accordion title="Projects missing from list">
    **Problem:** Some projects don't appear in the response.

    **Solution:**

    * Projects are user-specific - ensure you're using the correct API key
    * Check if projects were deleted or archived
    * Verify the projects completed parsing successfully
    * Contact support if projects are definitely missing
  </Accordion>

  <Accordion title="Status shows 'error'">
    **Problem:** Project status indicates parsing failure.

    **Solution:**

    * Use the Get Parsing Status endpoint to get detailed error information
    * Check if the repository is accessible
    * Verify the branch exists
    * Try re-parsing the repository with the Parse Directory endpoint
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml GET /api/v2/projects/list
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/projects/list:
    get:
      tags:
        - Projects
      summary: List Projects
      description: >-
        Retrieve a list of all projects associated with your account. Each
        project represents a parsed repository or codebase.
      operationId: listProjects
      responses:
        '200':
          description: Projects retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: Project identifier
                    repo_name:
                      type: string
                      description: Repository name
                    status:
                      type: string
                      enum:
                        - submitted
                        - cloned
                        - parsed
                        - processing
                        - inferring
                        - ready
                        - error
                      description: Project status
              example:
                - id: 123e4567-e89b-12d3-a456-426614174000
                  repo_name: my-awesome-app
                  status: ready
                - id: 123e4567-e89b-12d3-a456-426614174001
                  repo_name: backend-api
                  status: processing
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
          example:
            detail: Invalid API key
  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>

````