Skip to main content

​
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.
Returns both public and private projects owned by the current API token’s user.

​
Parameters

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

​
Response

​
projects
array
required
Array of project objects

​
Example Usage

"Show me all my Bilt projects"

​
Common Use Cases

​
1. Find Project by Name

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

User: "What projects have I created today?"

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

​
3. Check if Project Exists

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

{
  "projects": []
}
This means the user has no projects yet. Suggest creating one with bilt_create_project.

​
Single Project

{
  "projects": [
    {
      "id": "proj_abc123",
      "name": "first-app",
      "description": "My first Bilt app",
      "visibility": "public",
      "created_at": "2026-02-10T15:00:00.000Z",
      "updated_at": "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

If you need project data multiple times in a conversation, store the results instead of calling repeatedly.
// Pseudo-code
let projectCache = null;

async function getProjects() {
  if (!projectCache) {
    projectCache = await bilt_list_projects();
  }
  return projectCache;
}
The API returns all projects. Do filtering/sorting on the client:
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.created_at) - new Date(a.created_at)
);
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…”
When showing project lists to users, format them nicely:
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?

​
Error Handling

{
  "error": "Invalid or expired API key"
}

​
Rate Limits

Request Limit100 requests per minute

Best PracticeCache results within a session

​
Performance

  • Response time: < 200ms typical
  • Payload size: ~500 bytes per project
  • Max projects: 100 per user (free tier)
For users with many projects, consider pagination on the client side when displaying results.

bilt_get_project

Get details of a specific project

bilt_create_project

Create a new project

bilt_send_message

Start working on a project

​
Next Steps

After listing projects:
  1. Select a project - Use the returned ID with other tools
  2. Get project details - Call bilt_get_project
  3. Start a workflow - Get session with bilt_get_session
  4. Create new project - If list is empty, use bilt_create_project