List Projects

Get a list of all projects using API key authentication

GET /api/v2/projects/list

List Projects

cURL

curl --request GET \
  --url http://localhost:8001/api/v2/projects/list \
  --header 'x-api-key: <api-key>'

200

[
  {
    "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"
  }
]

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

TypeScript

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

200

application/json

Projects retrieved successfully

id · string

Project identifier

repo_name · string

Repository name

status · enum<string>

Project status

Available options: submitted, cloned, parsed, processing, inferring, ready, error