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

# Tasks

> Create and manage tasks via REST API

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

```http theme={null}
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`

<RequestExample>
  ```bash cURL theme={null}
  curl "http://localhost:8887/api/tasks?status=in_progress&priority=high&limit=20"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://localhost:8887/api/tasks?status=in_progress&priority=high&limit=20');
  const data = await response.json();
  ```

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

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

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "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
    }
  }
  ```

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

***

## Get Task

Retrieve a specific task with all details.

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

<RequestExample>
  ```bash cURL theme={null}
  curl http://localhost:8887/api/tasks/task_abc123
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://localhost:8887/api/tasks/task_abc123');
  const data = await response.json();
  ```

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

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

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "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
      }
    }
  }
  ```

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

***

## Create Task

Create a new task.

```http theme={null}
POST /api/tasks
```

### Request Body

```json theme={null}
{
  "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"]
  }
}
```

<RequestExample>
  ```bash cURL theme={null}
  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"]
    }'
  ```

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

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

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

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "success": true,
    "data": {
      "id": "task_def456",
      "projectId": "proj_xyz789",
      "title": "Add dark mode toggle",
      "status": "pending",
      "priority": "medium",
      "createdAt": "2024-01-15T11:00:00Z"
    }
  }
  ```

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

***

## Update Task

Update task properties.

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

### Request Body

```json theme={null}
{
  "title": "Updated title",
  "description": "Updated description",
  "status": "in_progress",
  "priority": "high",
  "labels": ["feature", "ui", "priority:high"],
  "assignee": "claude"
}
```

<RequestExample>
  ```bash cURL theme={null}
  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.

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

  <Warning>
    This deletes the task and all attempts permanently.
  </Warning>

  <RequestExample>
    ```bash cURL theme={null}
    curl -X DELETE http://localhost:8887/api/tasks/task_abc123
    ```

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

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

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

  <ResponseExample>
    ```json 200 Success theme={null}
    {
      "success": true,
      "data": {
        "deleted": true,
        "taskId": "task_abc123"
      }
    }
    ```

    ```json 404 Not Found theme={null}
    {
      "success": false,
      "error": {
        "code": "NOT_FOUND",
        "message": "Task not found"
      }
    }
    ```
  </ResponseExample>

  ***

  ## Start Task

  Start executing a task with an AI agent.

  ```http theme={null}
  POST /api/tasks/:id/start
  ```

  ### Request Body

  ```json theme={null}
  {
    "llm": "claude",
    "options": {
      "temperature": 0.7,
      "maxTokens": 4096
    }
  }
  ```

  <RequestExample>
    ```bash cURL theme={null}
    curl -X POST http://localhost:8887/api/tasks/task_abc123/start \
      -H "Content-Type: application/json" \
      -d '{
        "llm": "claude"
      }'
    ```

    ```javascript JavaScript theme={null}
    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 Python theme={null}
    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()
    ```
  </RequestExample>

  <ResponseExample>
    ```json 200 Success theme={null}
    {
      "success": true,
      "data": {
        "attemptId": "attempt_new123",
        "status": "running",
        "startedAt": "2024-01-15T10:30:00Z"
      }
    }
    ```

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

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

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

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "success": true,
    "data": {
      "attemptId": "attempt_new123",
      "status": "running",
      "startedAt": "2024-01-15T11:05:00Z"
    }
  }
  ```

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

***

## Cancel Task

Cancel a running task.

```http theme={null}
POST /api/tasks/:id/cancel
```

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST http://localhost:8887/api/tasks/task_abc123/cancel
  ```

  ***

  ## Get Task Attempts

  Get all attempts for a task.

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

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

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

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

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "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
      }
    ]
  }
  ```

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

***

## Get Task Logs

Get execution logs for a task.

```http theme={null}
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                |

<RequestExample>
  ```bash cURL theme={null}
  curl "http://localhost:8887/api/tasks/task_abc123/logs?attemptId=attempt_1&follow=true"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://localhost:8887/api/tasks/task_abc123/logs?attemptId=attempt_1&follow=true');
  const data = await response.json();
  ```

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

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

***

## Bulk Operations

### Bulk Update

Update multiple tasks at once.

```http theme={null}
POST /api/tasks/bulk/update
```

### Request Body

```json theme={null}
{
  "taskIds": ["task_1", "task_2", "task_3"],
  "updates": {
    "status": "review",
    "priority": "high"
  }
}
```

### Bulk Delete

```http theme={null}
POST /api/tasks/bulk/delete
```

### Request Body

```json theme={null}
{
  "taskIds": ["task_1", "task_2", "task_3"]
}
```

***

## SDK Examples

### JavaScript/TypeScript

```typescript theme={null}
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

```python theme={null}
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

<CardGroup cols={2}>
  <Card title="Attempts API" icon="flask" href="/forge/api/attempts">
    Manage task attempts
  </Card>

  <Card title="Projects API" icon="folder" href="/forge/api/projects">
    Organize tasks in projects
  </Card>

  <Card title="Processes API" icon="gear" href="/forge/api/processes">
    Monitor running processes
  </Card>
</CardGroup>


## OpenAPI

````yaml GET /api/tasks
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/tasks:
    get:
      tags:
        - Tasks
      summary: List tasks for a project
      parameters:
        - name: project_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
          description: Project ID to filter tasks
      responses:
        '200':
          description: List of tasks with attempt status
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/TaskWithAttemptStatus'
      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
    TaskWithAttemptStatus:
      allOf:
        - $ref: '#/components/schemas/Task'
        - type: object
          properties:
            has_in_progress_attempt:
              type: boolean
            has_merged_attempt:
              type: boolean
            last_attempt_failed:
              type: boolean
            executor:
              type: string
              nullable: true
    Task:
      type: object
      properties:
        id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        title:
          type: string
        description:
          type: string
          nullable: true
        status:
          type: string
          enum:
            - todo
            - inprogress
            - inreview
            - done
            - cancelled
        parent_task_attempt:
          type: string
          format: uuid
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - project_id
        - title
        - status
        - created_at
        - updated_at
  securitySchemes:
    githubAuth:
      type: http
      scheme: bearer
      description: GitHub OAuth token obtained via device flow

````