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

> Create a new native mobile application project

## Overview

Creates a new project in your Bilt account. This is typically the first step in any app development workflow.

<Info>
  Projects are automatically associated with your API token's user account.
</Info>

## Parameters

<ParamField path="name" type="string" required>
  Project name.

  * **Max length**: 255 characters
  * **Example**: `"my-todo-app"`
</ParamField>

<ParamField path="description" type="string" optional>
  Human-readable project description.

  * **Max length**: 1000 characters
  * **Example**: `"A simple todo list application with user authentication"`
</ParamField>

<ParamField path="visibility" type="string" optional default="private">
  Project visibility setting.

  * **Options**: `"public"` or `"private"`
  * **Default**: `"private"`
  * **public**: Visible to others, can be shared
  * **private**: Only visible to you
</ParamField>

## Response

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

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

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

<ResponseField name="visibility" type="string" required>
  Project visibility: `"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}
  {
    "name": "todo-app",
    "description": "A todo list with authentication and dark mode",
    "visibility": "public"
  }
  ```

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

## Agent Workflow Example

<Steps>
  <Step title="Agent creates project">
    ```text theme={null}
    User: "Create a new project called 'landing-page'"

    Agent uses bilt_create_project with:
    {
      "name": "landing-page"
    }
    ```
  </Step>

  <Step title="Agent receives project ID">
    ```json theme={null}
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "landing-page",
      "visibility": "public"
    }
    ```
  </Step>

  <Step title="Agent proceeds to build">
    ```text theme={null}
    Agent: "Created project 'landing-page' (550e8400-e29b-41d4-a716-446655440000).
           Ready to start building. What features would you like?"

    User: "Add a hero section, features grid, and contact form"

    Agent uses bilt_send_message to build features...
    ```
  </Step>
</Steps>

## Best Practices

<AccordionGroup>
  <Accordion title="Use descriptive names">
    Choose clear, specific project names that indicate the app's purpose.

    ✅ Good: `"ecommerce-dashboard"`, `"blog-cms"`, `"todo-app"`

    ❌ Avoid: `"test"`, `"project1"`, `"app"`
  </Accordion>

  <Accordion title="Include descriptions for complex projects">
    Add descriptions when the project name alone doesn't fully convey the scope.

    ```json theme={null}
    {
      "name": "social-analytics",
      "description": "Social media analytics dashboard with real-time metrics, trend analysis, and competitor tracking"
    }
    ```
  </Accordion>

  <Accordion title="Choose visibility deliberately">
    Projects default to private. Set `"public"` only when you want the project discoverable or shareable.
  </Accordion>

  <Accordion title="Store project IDs">
    Save the returned `id` for subsequent operations:

    ```text theme={null}
    Created project: 550e8400-e29b-41d4-a716-446655440000
    Use this ID for all future operations on this project.
    ```
  </Accordion>
</AccordionGroup>

## Error Handling

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

  ```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"
    }
  }
  ```
</ResponseExample>

## Rate Limits

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

    10 projects created per hour
  </Card>

  <Card>
    **Total Projects**

    Up to 100 active projects per account (free tier)
  </Card>
</CardGroup>

<Info>
  Contact [support@bilt.me](mailto:support@bilt.me) for higher limits on paid plans
</Info>

## Related Tools

<CardGroup cols={3}>
  <Card title="bilt_list_projects" icon="list" href="/docs/api-reference/bilt_list_projects">
    View all projects
  </Card>

  <Card title="bilt_get_project" icon="magnifying-glass" href="/docs/api-reference/bilt_get_project">
    Get project details
  </Card>

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

## Next Steps

After creating a project:

1. **Get a session** - Use [bilt\_get\_session](/docs/api-reference/bilt_get_session)
2. **Send build instructions** - Use [bilt\_send\_message](/docs/api-reference/bilt_send_message)
3. **Monitor progress** - Check status with [bilt\_get\_messages](/docs/api-reference/bilt_get_messages)
4. **Deploy** - Send deployment message when ready