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

# Projects

> Manage Forge projects via REST API

## Overview

Projects are the top-level organizational unit in Forge. Each project contains tasks, attempts, and configuration.

**Base URL**: `http://localhost:8887/api/projects`

***

## List Projects

<RequestExample>
  ```bash cURL theme={null}
  curl http://localhost:8887/api/projects?page=1&limit=10
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://localhost:8887/api/projects?page=1&limit=10');
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'http://localhost:8887/api/projects',
      params={'page': 1, 'limit': 10}
  )
  projects = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "proj_abc123",
        "name": "My Web App",
        "description": "E-commerce platform",
        "git_repo_path": "/home/user/projects/my-web-app",
        "setup_script": "npm install",
        "dev_script": "npm run dev",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T15:45:00Z"
      }
    ]
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "success": false,
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Authentication required"
    }
  }
  ```
</ResponseExample>

***

## Get Project

Retrieve a specific project by ID.

```http theme={null}
GET /api/projects/:id
```

### Example Request

```bash theme={null}
curl http://localhost:8887/api/projects/proj_abc123
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "proj_abc123",
    "name": "My Web App",
    "description": "E-commerce platform",
    "repository": {
      "url": "https://github.com/user/repo",
      "branch": "main",
      "lastSync": "2024-01-15T15:45:00Z"
    },
    "defaultLLM": "claude",
    "config": {
      "worktrees": {
        "enabled": true,
        "basePath": "./.forge/worktrees"
      },
      "llms": {
        "claude": {
          "model": "claude-3-5-sonnet-20241022"
        }
      }
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T15:45:00Z",
    "stats": {
      "tasks": 42,
      "completedTasks": 38,
      "inProgressTasks": 3,
      "failedTasks": 1,
      "activeAttempts": 2,
      "totalCost": 12.45
    }
  }
}
```

***

## Create Project

Create a new Forge project.

<ParamField body="name" type="string" required>
  Project name
</ParamField>

<ParamField body="description" type="string">
  Project description
</ParamField>

<ParamField body="repository" type="object" required>
  Repository configuration

  * `url` (string, required): GitHub repository URL
  * `branch` (string): Branch name (default: "main")
</ParamField>

<ParamField body="defaultLLM" type="string">
  Default AI agent (claude, gemini, gpt-4, etc.)
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://localhost:8887/api/projects \
    -H "Content-Type: application/json" \
    -d '{
      "name": "My New Project",
      "repository": {
        "url": "https://github.com/user/repo"
      },
      "defaultLLM": "claude"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://localhost:8887/api/projects', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'My New Project',
      repository: {
        url: 'https://github.com/user/repo'
      },
      defaultLLM: 'claude'
    })
  });
  const project = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post('http://localhost:8887/api/projects', json={
      'name': 'My New Project',
      'repository': {
          'url': 'https://github.com/user/repo'
      },
      'defaultLLM': 'claude'
  })
  project = response.json()
  ```
</CodeGroup>

### Response

```json 201 Created theme={null}
{
  "success": true,
  "data": {
    "id": "proj_xyz789",
    "name": "My New Project",
    "repository": {
      "url": "https://github.com/user/repo",
      "branch": "main"
    },
    "defaultLLM": "claude",
    "createdAt": "2024-01-15T16:00:00Z",
    "updatedAt": "2024-01-15T16:00:00Z"
  }
}
```

```json 400 Bad Request theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid project data",
    "details": {
      "name": "Project name is required",
      "repository.url": "Invalid repository URL"
    }
  }
}
```

```json 409 Conflict theme={null}
{
  "success": false,
  "error": {
    "code": "PROJECT_EXISTS",
    "message": "Project with name 'My New Project' already exists"
  }
}
```

***

## Update Project

Update project properties.

```http theme={null}
PATCH /api/projects/:id
```

### Request Body

```json theme={null}
{
  "name": "Updated Project Name",
  "description": "New description",
  "defaultLLM": "gemini"
}
```

### Example Request

```bash theme={null}
curl -X PATCH http://localhost:8887/api/projects/proj_abc123 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Project Name",
    "defaultLLM": "gemini"
  }'
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "proj_abc123",
    "name": "Updated Project Name",
    "defaultLLM": "gemini",
    "updatedAt": "2024-01-15T16:05:00Z"
  }
}
```

***

## Delete Project

Delete a project and all associated data.

```http theme={null}
DELETE /api/projects/:id
```

<Warning>
  This permanently deletes the project, all tasks, attempts, and associated data. This action cannot be undone.
</Warning>

### Example Request

```bash theme={null}
curl -X DELETE http://localhost:8887/api/projects/proj_abc123
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "proj_abc123",
    "deleted": true,
    "deletedAt": "2024-01-15T16:10:00Z"
  }
}
```

***

## Get Project Tasks

Get all tasks for a specific project.

```http theme={null}
GET /api/projects/:id/tasks
```

### Query Parameters

Same as [Tasks API](/forge/api/tasks) list parameters.

### Example Request

```bash theme={null}
curl http://localhost:8887/api/projects/proj_abc123/tasks?status=in_progress
```

***

## Get Project Stats

Get detailed statistics for a project.

```http theme={null}
GET /api/projects/:id/stats
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "tasks": {
      "total": 42,
      "pending": 3,
      "inProgress": 2,
      "completed": 36,
      "failed": 1
    },
    "attempts": {
      "total": 67,
      "successful": 58,
      "failed": 9
    },
    "costs": {
      "total": 12.45,
      "byLLM": {
        "claude": 8.23,
        "gemini": 0.00,
        "gpt-4": 4.22
      }
    },
    "performance": {
      "averageTaskDuration": 285000,
      "successRate": 0.86,
      "averageCostPerTask": 0.30
    }
  }
}
```

***

## SDK Examples

### JavaScript/TypeScript

```typescript theme={null}
import { ForgeClient } from '@automagik/forge-sdk';

const forge = new ForgeClient();

// List projects
const projects = await forge.projects.list({
  page: 1,
  limit: 10
});

// Get project
const project = await forge.projects.get('proj_abc123');

// Create project
const newProject = await forge.projects.create({
  name: 'My New Project',
  repository: {
    url: 'https://github.com/user/repo'
  },
  defaultLLM: 'claude'
});

// Update project
await forge.projects.update('proj_abc123', {
  name: 'Updated Name',
  defaultLLM: 'gemini'
});

// Delete project
await forge.projects.delete('proj_abc123');

// Get project stats
const stats = await forge.projects.stats('proj_abc123');
```

### Python

```python theme={null}
from automagik_forge import ForgeClient

forge = ForgeClient()

# List projects
projects = forge.projects.list(page=1, limit=10)

# Get project
project = forge.projects.get('proj_abc123')

# Create project
new_project = forge.projects.create(
    name='My New Project',
    repository={'url': 'https://github.com/user/repo'},
    default_llm='claude'
)

# Update project
forge.projects.update('proj_abc123', {
    'name': 'Updated Name',
    'default_llm': 'gemini'
})

# Delete project
forge.projects.delete('proj_abc123')

# Get stats
stats = forge.projects.stats('proj_abc123')
```

***

## Get Project Branches

List all git branches for a project.

```http theme={null}
GET /api/projects/:id/branches
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "currentBranch": "main",
    "branches": [
      {
        "name": "main",
        "commit": "abc123def456",
        "isCurrent": true,
        "isDefault": true,
        "lastCommit": {
          "hash": "abc123def456",
          "message": "Add authentication",
          "author": "John Doe",
          "date": "2024-01-15T10:00:00Z"
        }
      },
      {
        "name": "develop",
        "commit": "def456ghi789",
        "isCurrent": false,
        "isDefault": false,
        "lastCommit": {
          "hash": "def456ghi789",
          "message": "Work in progress",
          "author": "Jane Smith",
          "date": "2024-01-14T15:30:00Z"
        }
      },
      {
        "name": "forge/task-abc123-attempt-1",
        "commit": "ghi789jkl012",
        "isCurrent": false,
        "isDefault": false,
        "isForgeWorktree": true,
        "taskId": "abc123",
        "attemptId": "attempt-1",
        "lastCommit": {
          "hash": "ghi789jkl012",
          "message": "Add user authentication (automagik-forge abc1)",
          "author": "Claude AI",
          "date": "2024-01-15T11:00:00Z"
        }
      }
    ],
    "forgeBranches": [
      {
        "name": "forge/task-abc123-attempt-1",
        "taskId": "abc123",
        "attemptId": "attempt-1"
      }
    ]
  }
}
```

### Response Fields

| Field                        | Type    | Description                                 |
| ---------------------------- | ------- | ------------------------------------------- |
| `currentBranch`              | string  | Currently checked out branch                |
| `branches`                   | array   | All branches in repository                  |
| `branches[].name`            | string  | Branch name                                 |
| `branches[].commit`          | string  | Latest commit hash                          |
| `branches[].isCurrent`       | boolean | Currently checked out                       |
| `branches[].isDefault`       | boolean | Default branch (main/master)                |
| `branches[].isForgeWorktree` | boolean | Created by Forge for task attempt           |
| `branches[].taskId`          | string  | Associated task ID (Forge branches only)    |
| `branches[].attemptId`       | string  | Associated attempt ID (Forge branches only) |
| `forgeBranches`              | array   | Filtered list of Forge-created branches     |

### Use Cases

* List available target branches for merging
* Identify Forge worktree branches
* Check current repository state
* Find branches associated with specific tasks

***

## Error Responses

### Project Not Found

```json theme={null}
{
  "success": false,
  "error": {
    "code": "PROJECT_NOT_FOUND",
    "message": "Project with id 'proj_abc123' not found"
  }
}
```

### Validation Error

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid project data",
    "details": {
      "name": "Project name is required",
      "repository.url": "Invalid repository URL"
    }
  }
}
```

### Conflict Error

```json theme={null}
{
  "success": false,
  "error": {
    "code": "PROJECT_EXISTS",
    "message": "Project with name 'My Project' already exists"
  }
}
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Tasks API" icon="list-check" href="/forge/api/tasks">
    Manage tasks within projects
  </Card>

  <Card title="Attempts API" icon="flask" href="/forge/api/attempts">
    Execute tasks with AI agents
  </Card>

  <Card title="REST Overview" icon="book" href="/forge/api/rest-overview">
    API fundamentals and authentication
  </Card>
</CardGroup>


## OpenAPI

````yaml GET /api/projects
openapi: 3.0.3
info:
  title: Automagik Forge API
  version: 0.3.15
  description: |
    Automagik Forge API - AI-powered task orchestration and execution platform.

    ## Authentication
    Most endpoints require GitHub OAuth authentication via device flow:
    1. POST `/api/auth/github/device` to get device code
    2. User visits verification URL and enters code
    3. POST `/api/auth/github/device/poll` to get access token
    4. Include token in subsequent requests

    ## Real-time Updates
    Event streaming endpoints use Server-Sent Events (SSE):
    - `/api/events/processes/{id}/logs` - Stream process execution logs
    - `/api/events/task-attempts/{id}/diff` - Stream git diff updates
  contact:
    name: Automagik Forge Support
    url: https://github.com/namastexlabs/automagik-forge
  license:
    name: MIT
    url: https://github.com/namastexlabs/automagik-forge/blob/main/LICENSE
servers:
  - url: ''
    description: Same origin (use current server)
security: []
tags:
  - name: Core
    description: Health checks and system information
  - name: Auth
    description: GitHub OAuth authentication
  - name: Projects
    description: Project management
  - name: Tasks
    description: Task creation and management
  - name: Task Attempts
    description: Task execution attempts
  - name: Processes
    description: Execution process monitoring
  - name: Events
    description: Real-time event streaming (SSE)
  - name: Images
    description: Image upload and management
  - name: Forge
    description: Forge-specific features (Omni, config)
  - name: Filesystem
    description: Repository file browsing
  - name: Config
    description: Application configuration
  - name: Drafts
    description: Draft task management
  - name: Containers
    description: Container/worktree information
paths:
  /api/projects:
    get:
      tags:
        - Projects
      summary: List all projects
      responses:
        '200':
          description: List of projects
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Project'
      security:
        - githubAuth: []
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          nullable: true
        error_data:
          type: object
          nullable: true
        message:
          type: string
          nullable: true
      required:
        - success
    Project:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        git_repo_path:
          type: string
        setup_script:
          type: string
          nullable: true
        dev_script:
          type: string
          nullable: true
        cleanup_script:
          type: string
          nullable: true
        copy_files:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - name
        - git_repo_path
        - created_at
        - updated_at
  securitySchemes:
    githubAuth:
      type: http
      scheme: bearer
      description: GitHub OAuth token obtained via device flow

````