> ## 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_get_project

> Get detailed information about a specific project

## 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.

<Info>
  You must own the project or have access to it. Private projects owned by others will return 403 Forbidden.
</Info>

## Parameters

<ParamField path="projectId" type="string" required>
  Unique project identifier

  * **Format**: UUID
  * **Example**: `"550e8400-e29b-41d4-a716-446655440000"`
  * **Get it from**: [bilt\_list\_projects](/docs/api-reference/bilt_list_projects) or [bilt\_create\_project](/docs/api-reference/bilt_create_project)
</ParamField>

## Response

<ResponseField name="id" type="string" required>
  Project identifier (same as input)
</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>

## Example Usage

<CodeGroup>
  ```json Request theme={null}
  {
    "projectId": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```

  ```json Response theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "todo-app",
    "description": "A simple todo list application with authentication",
    "visibility": "public",
    "createdAt": "2026-02-10T10:30:00.000Z",
    "updatedAt": "2026-02-10T14:20:00.000Z"
  }
  ```
</CodeGroup>

## Agent Workflow Examples

### Pattern 1: Get Project Before Modifying

```text theme={null}
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(projectId) to confirm details
3. Call bilt_get_session() to start workflow
4. Call bilt_send_message("Add search feature")
```

### Pattern 2: Check Project Status

```text theme={null}
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(projectId)
3. Check updatedAt to see when last modified
4. Report status to user
```

### Pattern 3: Verify Ownership

```text theme={null}
Before performing operations:

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

## Use Cases

<AccordionGroup>
  <Accordion title="Confirm project exists">
    Before starting work, verify the project is valid:

    ```typescript theme={null}
    try {
      const project = await bilt_get_project({ projectId });
      console.log(`Working on: ${project.name}`);
    } catch (error) {
      if (error.status === 404) {
        console.log("Project not found");
      }
    }
    ```
  </Accordion>

  <Accordion title="Get project metadata">
    Retrieve name, description, visibility for display:

    ```text theme={null}
    Agent: "Let me check that project..."

    Result:
    "Your project 'todo-app' is public and was last updated 
     on Feb 10 at 2:20 PM."
    ```
  </Accordion>

  <Accordion title="Check modification date">
    See when project was last changed:

    ```typescript theme={null}
    const project = await bilt_get_project({ projectId });
    const lastUpdate = new Date(project.updatedAt);
    const hoursSince = (Date.now() - lastUpdate) / 3600000;

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

## Response Comparison

### Success Response

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "my-app",
  "description": "Description here",
  "visibility": "public",
  "createdAt": "2026-02-10T15:00:00.000Z",
  "updatedAt": "2026-02-10T15:30:00.000Z"
}
```

### Project Not Found (404)

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32004,
    "message": "Resource not found"
  }
}
```

### Access Denied (403)

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32003,
    "message": "Access denied - you do not have permission for this resource"
  }
}
```

## Best Practices

<CardGroup cols={2}>
  <Card>
    **Get before modify**

    Always fetch project details before making changes
  </Card>

  <Card>
    **Handle 404s gracefully**

    User may have deleted the project
  </Card>

  <Card>
    **Check updatedAt**

    Know when project was last touched
  </Card>

  <Card>
    **Use for validation**

    Confirm project exists before long operations
  </Card>
</CardGroup>

## Error Handling

<ResponseExample>
  ```json 400 - Bad Request theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "error": {
      "code": -32602,
      "message": "Missing required parameter: projectId"
    }
  }
  ```

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

  ```json 403 - Forbidden theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "error": {
      "code": -32003,
      "message": "Access denied - you do not have permission for this resource"
    }
  }
  ```

  ```json 404 - Not Found theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "error": {
      "code": -32004,
      "message": "Resource not found"
    }
  }
  ```

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

## When to Use vs bilt\_list\_projects

<Tabs>
  <Tab title="Use bilt_get_project when">
    * You have a project ID
    * Need detailed info on one project
    * Validating project exists
    * Checking specific project status
  </Tab>

  <Tab title="Use bilt_list_projects when">
    * Don't have project ID yet
    * Need to find project by name
    * Want to see all projects
    * User asks "what projects do I have?"
  </Tab>
</Tabs>

## Performance

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

## Related Tools

<CardGroup cols={3}>
  <Card title="bilt_list_projects" icon="list" href="/docs/api-reference/bilt_list_projects">
    Find project ID by name
  </Card>

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

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

## Next Steps

After getting project details:

1. **Start a workflow** - Use [bilt\_get\_session](/docs/api-reference/bilt_get_session)
2. **Send instructions** - Use [bilt\_send\_message](/docs/api-reference/bilt_send_message)
3. **View history** - Use [bilt\_get\_messages](/docs/api-reference/bilt_get_messages)