Tasks

curl "http://localhost:8887/api/tasks?status=in_progress&priority=high&limit=20"

const response = await fetch('http://localhost:8887/api/tasks?status=in_progress&priority=high&limit=20');
const data = await response.json();

import requests

response = requests.get(
    'http://localhost:8887/api/tasks',
    params={'status': 'in_progress', 'priority': 'high', 'limit': 20}
)
tasks = response.json()

{
  "success": true,
  "data": [
    {
      "id": "task_abc123",
      "projectId": "proj_xyz789",
      "title": "Add user authentication",
      "description": "Implement JWT-based authentication",
      "status": "in_progress",
      "priority": "high",
      "labels": ["feature", "backend", "auth"],
      "assignee": "claude",
      "createdBy": "user_123",
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

GET

api

tasks

curl "http://localhost:8887/api/tasks?status=in_progress&priority=high&limit=20"

const response = await fetch('http://localhost:8887/api/tasks?status=in_progress&priority=high&limit=20');
const data = await response.json();

import requests

response = requests.get(
    'http://localhost:8887/api/tasks',
    params={'status': 'in_progress', 'priority': 'high', 'limit': 20}
)
tasks = response.json()

{
  "success": true,
  "data": [
    {
      "id": "task_abc123",
      "projectId": "proj_xyz789",
      "title": "Add user authentication",
      "description": "Implement JWT-based authentication",
      "status": "in_progress",
      "priority": "high",
      "labels": ["feature", "backend", "auth"],
      "assignee": "claude",
      "createdBy": "user_123",
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Overview

Tasks represent individual pieces of work to be executed by AI agents. Base URL: http://localhost:8887/api/tasks

List Tasks

Get all tasks with filtering and pagination.

GET /api/tasks

Query Parameters

Parameter	Type	Description
`projectId`	string	Filter by project
`status`	enum	Filter by status
`priority`	enum	Filter by priority
`labels`	string	Comma-separated labels
`assignee`	string	Filter by assignee
`search`	string	Search title/description
`page`	integer	Page number
`limit`	integer	Items per page
`sort`	string	Sort field

Status Values

pending - Not started
in_progress - Being executed
review - Awaiting review
completed - Successfully completed
failed - Execution failed
cancelled - Cancelled by user

Priority Values

low
medium
high
critical

curl "http://localhost:8887/api/tasks?status=in_progress&priority=high&limit=20"

const response = await fetch('http://localhost:8887/api/tasks?status=in_progress&priority=high&limit=20');
const data = await response.json();

import requests

response = requests.get(
    'http://localhost:8887/api/tasks',
    params={'status': 'in_progress', 'priority': 'high', 'limit': 20}
)
tasks = response.json()

{
  "success": true,
  "data": [
    {
      "id": "task_abc123",
      "projectId": "proj_xyz789",
      "title": "Add user authentication",
      "description": "Implement JWT-based authentication",
      "status": "in_progress",
      "priority": "high",
      "labels": ["feature", "backend", "auth"],
      "assignee": "claude",
      "createdBy": "user_123",
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Get Task

Retrieve a specific task with all details.

GET /api/tasks/:id

curl http://localhost:8887/api/tasks/task_abc123

const response = await fetch('http://localhost:8887/api/tasks/task_abc123');
const data = await response.json();

import requests

response = requests.get('http://localhost:8887/api/tasks/task_abc123')
data = response.json()

{
  "success": true,
  "data": {
    "id": "task_abc123",
    "projectId": "proj_xyz789",
    "title": "Add user authentication",
    "description": "Implement JWT-based authentication with login and signup endpoints",
    "status": "completed",
    "priority": "high",
    "labels": ["feature", "backend", "auth"],
    "assignee": "claude",
    "createdBy": "user_123",
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:45:00Z",
    "completedAt": "2024-01-15T10:45:00Z",
    "attempts": [
      {
        "id": "attempt_1",
        "llm": "claude",
        "status": "completed",
        "startedAt": "2024-01-15T10:30:00Z",
        "completedAt": "2024-01-15T10:45:00Z",
        "duration": 900000,
        "cost": 0.23,
        "filesChanged": 8,
        "linesAdded": 245,
        "linesRemoved": 12
      }
    ],
    "metadata": {
      "repository": "https://github.com/user/repo",
      "branch": "feature/auth",
      "worktreePath": ".forge/worktrees/task-abc123-claude"
    },
    "stats": {
      "totalAttempts": 1,
      "successfulAttempts": 1,
      "failedAttempts": 0,
      "totalCost": 0.23,
      "totalDuration": 900000
    }
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Create Task

Create a new task.

POST /api/tasks

Request Body

{
  "projectId": "proj_xyz789",
  "title": "Add dark mode toggle",
  "description": "Create a toggle component for dark/light mode with LocalStorage persistence",
  "priority": "medium",
  "labels": ["feature", "ui"],
  "assignee": "gemini",
  "metadata": {
    "files": ["src/components/ThemeToggle.tsx"]
  }
}

curl -X POST http://localhost:8887/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "proj_xyz789",
    "title": "Add dark mode toggle",
    "description": "Create toggle component with LocalStorage",
    "priority": "medium",
    "labels": ["feature", "ui"]
  }'

const response = await fetch('http://localhost:8887/api/tasks', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({...})
});
const data = await response.json();

import requests

response = requests.post(
    'http://localhost:8887/api/tasks',
    json={...}
)
data = response.json()

{
  "success": true,
  "data": {
    "id": "task_def456",
    "projectId": "proj_xyz789",
    "title": "Add dark mode toggle",
    "status": "pending",
    "priority": "medium",
    "createdAt": "2024-01-15T11:00:00Z"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Update Task

Update task properties.

PATCH /api/tasks/:id

Request Body

{
  "title": "Updated title",
  "description": "Updated description",
  "status": "in_progress",
  "priority": "high",
  "labels": ["feature", "ui", "priority:high"],
  "assignee": "claude"
}

curl -X PATCH http://localhost:8887/api/tasks/task_abc123 \
  -H "Content-Type: application/json" \
  -d '{
    "status": "review",
    "priority": "high"
  }'

Delete Task

Delete a task and all associated attempts.

DELETE /api/tasks/:id

This deletes the task and all attempts permanently.

cURL

curl -X DELETE http://localhost:8887/api/tasks/task_abc123

JavaScript

const response = await fetch('http://localhost:8887/api/tasks/task_abc123', {
  method: 'DELETE'
});
const data = await response.json();

Python

import requests

response = requests.delete('http://localhost:8887/api/tasks/task_abc123')
data = response.json()

200 Success

{
  "success": true,
  "data": {
    "deleted": true,
    "taskId": "task_abc123"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Task not found"
  }
}

Start Task

Start executing a task with an AI agent.

POST /api/tasks/:id/start

Request Body

{
  "llm": "claude",
  "options": {
    "temperature": 0.7,
    "maxTokens": 4096
  }
}

cURL

curl -X POST http://localhost:8887/api/tasks/task_abc123/start \
  -H "Content-Type: application/json" \
  -d '{
    "llm": "claude"
  }'

JavaScript

const response = await fetch('http://localhost:8887/api/tasks/task_abc123/start', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    llm: 'claude',
    options: {
      temperature: 0.7,
      maxTokens: 4096
    }
  })
});
const data = await response.json();

Python

import requests

response = requests.post(
    'http://localhost:8887/api/tasks/task_abc123/start',
    json={'llm': 'claude', 'options': {'temperature': 0.7, 'maxTokens': 4096}}
)
data = response.json()

200 Success

{
  "success": true,
  "data": {
    "attemptId": "attempt_new123",
    "status": "running",
    "startedAt": "2024-01-15T10:30:00Z"
  }
}

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

import requests

response = requests.post(
    'http://localhost:8887/api/tasks/task_abc123',
    json={...}
)
data = response.json()

{
  "success": true,
  "data": {
    "attemptId": "attempt_new123",
    "status": "running",
    "startedAt": "2024-01-15T11:05:00Z"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Cancel Task

Cancel a running task.

POST /api/tasks/:id/cancel

curl -X POST http://localhost:8887/api/tasks/task_abc123/cancel

Get Task Attempts

Get all attempts for a task.

GET /api/tasks/:id/attempts

const response = await fetch('http://localhost:8887/api/tasks/task_abc123/cancel', { method: 'POST' });
const data = await response.json();

import requests

response = requests.post(
    'http://localhost:8887/api/tasks/task_abc123/cancel',
    json={...}
)
data = response.json()

{
  "success": true,
  "data": [
    {
      "id": "attempt_1",
      "llm": "claude",
      "status": "completed",
      "duration": 900000,
      "cost": 0.23
    },
    {
      "id": "attempt_2",
      "llm": "gemini",
      "status": "completed",
      "duration": 450000,
      "cost": 0.00
    }
  ]
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Get Task Logs

Get execution logs for a task.

GET /api/tasks/:id/logs

Query Parameters

Parameter	Type	Description
`attemptId`	string	Filter by specific attempt
`level`	enum	Filter by log level (info, warn, error)
`follow`	boolean	Stream logs in real-time

curl "http://localhost:8887/api/tasks/task_abc123/logs?attemptId=attempt_1&follow=true"

const response = await fetch('http://localhost:8887/api/tasks/task_abc123/logs?attemptId=attempt_1&follow=true');
const data = await response.json();

import requests

response = requests.get(
    'http://localhost:8887/api/tasks/task_abc123/logs',
    params={'attemptId': 'attempt_1', 'follow': True}
)
logs = response.json()

Bulk Operations

Bulk Update

Update multiple tasks at once.

POST /api/tasks/bulk/update

Request Body

{
  "taskIds": ["task_1", "task_2", "task_3"],
  "updates": {
    "status": "review",
    "priority": "high"
  }
}

Bulk Delete

POST /api/tasks/bulk/delete

Request Body

{
  "taskIds": ["task_1", "task_2", "task_3"]
}

SDK Examples

JavaScript/TypeScript

import { ForgeClient } from '@automagik/forge-sdk';

const forge = new ForgeClient();

// List tasks
const tasks = await forge.tasks.list({
  status: 'in_progress',
  priority: 'high',
  page: 1,
  limit: 20
});

// Get task
const task = await forge.tasks.get('task_abc123');

// Create task
const newTask = await forge.tasks.create({
  projectId: 'proj_xyz789',
  title: 'Add dark mode',
  description: 'Implement dark mode toggle',
  priority: 'medium',
  labels: ['feature', 'ui']
});

// Update task
await forge.tasks.update('task_abc123', {
  status: 'review',
  priority: 'high'
});

// Start task
const attempt = await forge.tasks.start('task_abc123', {
  llm: 'claude'
});

// Cancel task
await forge.tasks.cancel('task_abc123');

// Get attempts
const attempts = await forge.tasks.attempts('task_abc123');

// Get logs
const logs = await forge.tasks.logs('task_abc123', {
  attemptId: 'attempt_1',
  follow: true
});

Python

from automagik_forge import ForgeClient

forge = ForgeClient()

# List tasks
tasks = forge.tasks.list(
    status='in_progress',
    priority='high',
    page=1,
    limit=20
)

# Create task
new_task = forge.tasks.create(
    project_id='proj_xyz789',
    title='Add dark mode',
    description='Implement dark mode toggle',
    priority='medium',
    labels=['feature', 'ui']
)

# Start task
attempt = forge.tasks.start('task_abc123', llm='claude')

# Get logs (streaming)
for log in forge.tasks.logs('task_abc123', follow=True):
    print(log)

Next Steps

Attempts API

Manage task attempts

Projects API

Organize tasks in projects

Processes API

Monitor running processes

Authorizations

Authorization

string

header

required

GitHub OAuth token obtained via device flow

Query Parameters

project_id

string<uuid>

required

Project ID to filter tasks

Response

200 - application/json

List of tasks with attempt status

The response is of type any.

Projects Attempts

Getting Started

Learn

Configuration

Reference

Troubleshooting

Overview

List Tasks

Query Parameters

Status Values

Priority Values

Get Task

Create Task

Request Body

Update Task

Request Body

Cancel Task

Get Task Logs

Query Parameters

Bulk Operations

Bulk Update

Request Body

Bulk Delete

Request Body

SDK Examples

JavaScript/TypeScript

Python

Next Steps

Attempts API

Projects API

Processes API

Authorizations

Query Parameters

Response

​Overview

​List Tasks

​Query Parameters

​Status Values

​Priority Values

​Get Task

​Create Task

​Request Body

​Update Task

​Request Body

​Cancel Task

​Get Task Logs

​Query Parameters

​Bulk Operations

​Bulk Update

​Request Body

​Bulk Delete

​Request Body

​SDK Examples

​JavaScript/TypeScript

​Python

​Next Steps

Attempts API

Projects API

Processes API

Authorizations

Query Parameters

Response

Overview

List Tasks

Query Parameters

Status Values

Priority Values

Get Task

Create Task

Request Body

Update Task

Request Body

Cancel Task

Get Task Logs

Query Parameters

Bulk Operations

Bulk Update

Request Body

Bulk Delete

Request Body

SDK Examples

JavaScript/TypeScript

Python

Next Steps