List Projects - Potpie

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.

x-api-key: YOUR_API_KEY

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)

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

401 Unauthorized

The endpoint requires a valid API key for authentication.

{
  "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:

x-api-key: YOUR_API_KEY

500 Internal Server Error

The endpoint returns this error when unexpected exceptions occur.

{
  "detail": "<exception message>"
}

Causes:

Database connection failures
Service unavailability

Solution: Retry the request after a brief delay. If the issue persists, contact support.

Complete Workflow

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}`);
});

Building a Project Dashboard

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

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

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

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

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

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

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

Authorizations

x-api-key

string

header

required

API key authentication. Get your key from potpie settings page

Response

Projects retrieved successfully

string

Project identifier

repo_name

string

Repository name

status

enum<string>

Project status

Available options:

submitted,

cloned,

parsed,

processing,

inferring,

ready,

error

​Use Cases

​Authentication

​Project Status

​Error Responses

​Complete Workflow

​Building a Project Dashboard

​Filtering and Sorting

​Common Patterns

​Project Selector Component

​Project Validation

​Troubleshooting

Authorizations

Response

Use Cases

Authentication

Project Status

Error Responses

Complete Workflow

Building a Project Dashboard

Filtering and Sorting

Common Patterns

Project Selector Component

Project Validation

Troubleshooting