Projects - Automagik Suite Documentation

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

curl http://localhost:8887/api/projects?page=1&limit=10

{
  "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"
    }
  ]
}

Get Project

Retrieve a specific project by ID.

GET /api/projects/:id

Example Request

curl http://localhost:8887/api/projects/proj_abc123

Example Response

{
  "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.

name

string

required

Project name

description

string

Project description

repository

object

required

Repository configuration

url (string, required): GitHub repository URL
branch (string): Branch name (default: “main”)

defaultLLM

string

Default AI agent (claude, gemini, gpt-4, etc.)

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"
  }'

Response

201 Created

{
  "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"
  }
}

400 Bad Request

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

409 Conflict

{
  "success": false,
  "error": {
    "code": "PROJECT_EXISTS",
    "message": "Project with name 'My New Project' already exists"
  }
}

Update Project

Update project properties.

PATCH /api/projects/:id

Request Body

{
  "name": "Updated Project Name",
  "description": "New description",
  "defaultLLM": "gemini"
}

Example Request

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

Example Response

{
  "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.

DELETE /api/projects/:id

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

Example Request

curl -X DELETE http://localhost:8887/api/projects/proj_abc123

Example Response

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

Get Project Tasks

Get all tasks for a specific project.

GET /api/projects/:id/tasks

Query Parameters

Same as Tasks API list parameters.

Example Request

curl http://localhost:8887/api/projects/proj_abc123/tasks?status=in_progress

Get Project Stats

Get detailed statistics for a project.

GET /api/projects/:id/stats

Example Response

{
  "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

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

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.

GET /api/projects/:id/branches

Example Response

{
  "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

{
  "success": false,
  "error": {
    "code": "PROJECT_NOT_FOUND",
    "message": "Project with id 'proj_abc123' not found"
  }
}

Validation Error

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

Conflict Error

{
  "success": false,
  "error": {
    "code": "PROJECT_EXISTS",
    "message": "Project with name 'My Project' already exists"
  }
}

Next Steps

Tasks API

Manage tasks within projects

Attempts API

Execute tasks with AI agents

REST Overview

API fundamentals and authentication

Authorizations

Authorization

string

header

required

GitHub OAuth token obtained via device flow

Response

200 - application/json

List of projects

success

boolean

required

data

any

error_data

object | null

message

string | null

Getting Started

Learn

Configuration

Reference

Troubleshooting

​Overview

​List Projects

​Get Project

​Example Request

​Example Response

​Create Project

​Response

​Update Project

​Request Body

​Example Request

​Example Response

​Delete Project

​Example Request

​Example Response

​Get Project Tasks

​Query Parameters

​Example Request

​Get Project Stats

​Example Response

​SDK Examples

​JavaScript/TypeScript

​Python

​Get Project Branches

​Example Response

​Response Fields

​Use Cases

​Error Responses

​Project Not Found

​Validation Error

​Conflict Error

​Next Steps

Tasks API

Attempts API

REST Overview

Authorizations

Response

Overview

List Projects

Get Project

Example Request

Example Response

Create Project

Response

Update Project

Request Body

Example Request

Example Response

Delete Project

Example Request

Example Response

Get Project Tasks

Query Parameters

Example Request

Get Project Stats

Example Response

SDK Examples

JavaScript/TypeScript

Python

Get Project Branches

Example Response

Response Fields

Use Cases

Error Responses

Project Not Found

Validation Error

Conflict Error

Next Steps