Skip to main content

​
Overview

Retrieves complete details for a single project by ID. Use this when you have a project ID and need its current state, metadata, or configuration.
You must own the project or have access to it. Private projects owned by others will return 403 Forbidden.

​
Parameters

​
project_id
string
required
Unique project identifier

​
Response

​
id
string
required
Project identifier (same as input)
​
name
string
required
Project name
​
description
string
Project description (null if not set)
​
visibility
string
required
"public" or "private"
​
created_at
string
required
ISO 8601 timestamp of creation
​
updated_at
string
required
ISO 8601 timestamp of last update

​
Example Usage

{
  "project_id": "550e8400-e29b-41d4-a716-446655440000"
}

​
Agent Workflow Examples

​
Pattern 1: Get Project Before Modifying

User: "Add a search feature to my todo app"

Agent workflow:
1. Call bilt_list_projects() to find "todo-app"
2. Call bilt_get_project(project_id) to confirm details
3. Call bilt_get_session() to start workflow
4. Call bilt_send_message("Add search feature")

​
Pattern 2: Check Project Status

User: "What's the status of my landing-page project?"

Agent workflow:
1. Call bilt_list_projects() to get project ID
2. Call bilt_get_project(project_id)
3. Check updated_at to see when last modified
4. Report status to user

​
Pattern 3: Verify Ownership

Before performing operations:

Agent workflow:
1. Call bilt_get_project(project_id)
2. If successful → user owns project, proceed
3. If 403 error → user doesn't have access, inform them

​
Use Cases

Before starting work, verify the project is valid:
try {
  const project = await bilt_get_project({ project_id });
  console.log(`Working on: ${project.name}`);
} catch (error) {
  if (error.status === 404) {
    console.log("Project not found");
  }
}
Retrieve name, description, visibility for display:
Agent: "Let me check that project..."

Result:
"Your project 'todo-app' is public and was last updated 
 on Feb 10 at 2:20 PM."
See when project was last changed:
const project = await bilt_get_project({ project_id });
const lastUpdate = new Date(project.updated_at);
const hoursSince = (Date.now() - lastUpdate) / 3600000;

if (hoursSince > 24) {
  console.log("This project hasn't been touched in over a day");
}

​
Response Comparison

​
Success Response

{
  "id": "proj_abc123",
  "name": "my-app",
  "description": "Description here",
  "visibility": "public",
  "created_at": "2026-02-10T15:00:00.000Z",
  "updated_at": "2026-02-10T15:30:00.000Z"
}

​
Project Not Found (404)

{
  "error": "Project not found"
}

​
Access Denied (403)

{
  "error": "Forbidden",
  "details": "You don't have access to this project"
}

​
Best Practices

Get before modifyAlways fetch project details before making changes

Handle 404s gracefullyUser may have deleted the project

Check updated_atKnow when project was last touched

Use for validationConfirm project exists before long operations

​
Error Handling

{
  "error": "Invalid request body",
  "details": {
    "project_id": "Invalid UUID format"
  }
}

​
When to Use vs bilt_list_projects

  • You have a project ID
  • Need detailed info on one project
  • Validating project exists
  • Checking specific project status

​
Performance

  • Response time: < 100ms typical
  • Payload size: ~400 bytes
  • Caching: Consider caching if accessed frequently

bilt_list_projects

Find project ID by name

bilt_create_project

Create new project

bilt_send_message

Start working on project

​
Next Steps

After getting project details:
  1. Start a workflow - Use bilt_get_session
  2. Send instructions - Use bilt_send_message
  3. View history - Use bilt_get_messages