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

# bilt_list_projects

> List all projects for the authenticated user

## Overview

Retrieves a list of all projects owned by the authenticated user. Use this tool when you need to discover existing projects or find a specific project by name.

<Info>
  Returns both public and private projects owned by the current API token's user.
</Info>

## Parameters

This tool takes **no parameters**. Simply invoke it to get the full project list.

## Response

<ResponseField name="projects" type="array" required>
  Array of project objects

  <Expandable title="Project Object">
    <ResponseField name="id" type="string" required>
      Unique project identifier (UUID format)
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Project name
    </ResponseField>

    <ResponseField name="description" type="string">
      Project description (null if not set)
    </ResponseField>

    <ResponseField name="visibility" type="string" required>
      `"public"` or `"private"`
    </ResponseField>

    <ResponseField name="createdAt" type="string" required>
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      ISO 8601 timestamp of last update
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Usage

<CodeGroup>
  ```text Agent Prompt theme={null}
  "Show me all my Bilt projects"
  ```

  ```json Response theme={null}
  {
    "projects": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "todo-app",
        "description": "A simple todo list application",
        "visibility": "public",
        "createdAt": "2026-02-10T10:30:00.000Z",
        "updatedAt": "2026-02-10T14:20:00.000Z"
      },
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "name": "landing-page",
        "description": null,
        "visibility": "private",
        "createdAt": "2026-02-09T15:45:00.000Z",
        "updatedAt": "2026-02-09T15:45:00.000Z"
      }
    ]
  }
  ```
</CodeGroup>

## Common Use Cases

### 1. Find Project by Name

```text theme={null}
User: "Show me my todo-app project"

Agent workflow:
1. Call bilt_list_projects()
2. Filter results: project.name === "todo-app"
3. Return matching project or "not found"
```

### 2. List Recent Projects

```text theme={null}
User: "What projects have I created today?"

Agent workflow:
1. Call bilt_list_projects()
2. Filter by createdAt date
3. Sort by newest first
4. Display results
```

### 3. Check if Project Exists

```text theme={null}
Before creating a project, check if name is taken:

Agent workflow:
1. Call bilt_list_projects()
2. Check if any project.name matches desired name
3. If exists, suggest alternative name
4. If not, proceed with creation
```

## Response Scenarios

### Empty Project List

```json theme={null}
{
  "projects": []
}
```

This means the user has no projects yet. Suggest creating one with [bilt\_create\_project](/docs/api-reference/bilt_create_project).

### Single Project

```json theme={null}
{
  "projects": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "name": "first-app",
      "description": "My first Bilt app",
      "visibility": "public",
      "createdAt": "2026-02-10T15:00:00.000Z",
      "updatedAt": "2026-02-10T15:00:00.000Z"
    }
  ]
}
```

### Multiple Projects

When users have many projects, the array will contain all of them. There's no automatic pagination - the tool returns everything.

## Best Practices

<AccordionGroup>
  <Accordion title="Cache the results">
    If you need project data multiple times in a conversation, store the results instead of calling repeatedly.

    ```typescript theme={null}
    // Pseudo-code
    let projectCache = null;

    async function getProjects() {
      if (!projectCache) {
        projectCache = await bilt_list_projects();
      }
      return projectCache;
    }
    ```
  </Accordion>

  <Accordion title="Filter client-side">
    The API returns all projects. Do filtering/sorting on the client:

    ```typescript theme={null}
    const projects = await bilt_list_projects();

    // Find by name
    const todoApp = projects.find(p => p.name === 'todo-app');

    // Filter by visibility
    const publicProjects = projects.filter(p => p.visibility === 'public');

    // Sort by date
    projects.sort((a, b) => 
      new Date(b.createdAt) - new Date(a.createdAt)
    );
    ```
  </Accordion>

  <Accordion title="Use for discovery, not iteration">
    List projects to help users find what they're looking for, not to perform operations on every project.

    ✅ Good: "Which project do you want to modify?"

    ❌ Avoid: "Let me check every project for errors..."
  </Accordion>

  <Accordion title="Present results clearly">
    When showing project lists to users, format them nicely:

    ```text theme={null}
    Your projects:
    1. todo-app (public) - Created Feb 10
    2. landing-page (private) - Created Feb 9
    3. dashboard (public) - Created Feb 8

    Which one would you like to work on?
    ```
  </Accordion>
</AccordionGroup>

## Error Handling

<ResponseExample>
  ```json 401 - Unauthorized theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "error": {
      "code": -32001,
      "message": "Authentication failed - invalid or expired API key"
    }
  }
  ```

  ```json 429 - Rate Limited theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "error": {
      "code": -32005,
      "message": "Rate limit exceeded - please slow down requests"
    }
  }
  ```

  ```json 500 - Server Error theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "error": {
      "code": -32603,
      "message": "Internal error"
    }
  }
  ```
</ResponseExample>

## Rate Limits

<CardGroup cols={2}>
  <Card>
    **Request Limit**

    100 requests per minute
  </Card>

  <Card>
    **Best Practice**

    Cache results within a session
  </Card>
</CardGroup>

## Performance

* **Response time**: \< 200ms typical
* **Payload size**: \~500 bytes per project
* **Max projects**: 100 per user (free tier)

<Tip>
  For users with many projects, consider pagination on the client side when displaying results.
</Tip>

## Related Tools

<CardGroup cols={3}>
  <Card title="bilt_get_project" icon="magnifying-glass" href="/docs/api-reference/bilt_get_project">
    Get details of a specific project
  </Card>

  <Card title="bilt_create_project" icon="plus" href="/docs/api-reference/bilt_create_project">
    Create a new project
  </Card>

  <Card title="bilt_send_message" icon="paper-plane" href="/docs/api-reference/bilt_send_message">
    Start working on a project
  </Card>
</CardGroup>

## Next Steps

After listing projects:

1. **Select a project** - Use the returned ID with other tools
2. **Get project details** - Call [bilt\_get\_project](/docs/api-reference/bilt_get_project)
3. **Start a workflow** - Get session with [bilt\_get\_session](/docs/api-reference/bilt_get_session)
4. **Create new project** - If list is empty, use [bilt\_create\_project](/docs/api-reference/bilt_create_project)