Skip to content

task mobile integration

Jump to bottom
Evan Feenstra edited this page Feb 24, 2026 · 3 revisions

iOS Tasks & Chat API Reference

API endpoints for listing workspace tasks and chatting with tasks.

List Tasks

GET /api/tasks?workspaceId={workspaceId}

Query Parameters

Parameter Type Required Default Description
workspaceId string yes - Workspace UUID
page int no 1 Page number
limit int no 5 Items per page (1-1000)
search string no - Search title, description, branch
status string no - PENDING, IN_PROGRESS, COMPLETED, ERROR, HALTED, FAILED, or running
priority string no - LOW, MEDIUM, HIGH
sourceType string no - USER, JANITOR, TASK_COORDINATOR, SYSTEM
sortBy string no updatedAt Field to sort by
sortOrder string no desc asc or desc
includeLatestMessage string no "false" "true" to include latest message
includeArchived string no "false" "true" for archived tasks only
showAllStatuses string no "false" "true" for kanban-style view

Response (200)

{
  "success": true,
  "data": [
    {
      "id": "string",
      "title": "string",
      "description": "string | null",
      "status": "TODO | IN_PROGRESS | DONE | CANCELLED | BLOCKED",
      "priority": "LOW | MEDIUM | HIGH | CRITICAL",
      "workflowStatus": "PENDING | IN_PROGRESS | COMPLETED | ERROR | HALTED | FAILED | null",
      "sourceType": "USER | JANITOR | TASK_COORDINATOR | SYSTEM",
      "mode": "live | agent",
      "podId": "string | null",
      "createdAt": "datetime",
      "updatedAt": "datetime",
      "feature": { "id": "string", "title": "string" },
      "assignee": { "id": "string", "name": "string", "email": "string", "image": "string" },
      "repository": { "id": "string", "name": "string", "repositoryUrl": "string" },
      "createdBy": { "id": "string", "name": "string", "image": "string" },
      "_count": { "chatMessages": 5 }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 5,
    "totalCount": 42,
    "totalPages": 9,
    "hasMore": true
  }
}

Get Task Messages (Chat History)

GET /api/tasks/{taskId}/messages

Response (200)

{
  "success": true,
  "data": {
    "task": {
      "id": "string",
      "title": "string",
      "workspaceId": "string",
      "workflowStatus": "WorkflowStatus | null",
      "mode": "live | agent",
      "podId": "string | null"
    },
    "messages": [
      {
        "id": "string",
        "message": "string",
        "role": "USER | ASSISTANT",
        "timestamp": "datetime",
        "status": "SENDING | SENT | ERROR",
        "artifacts": [
          {
            "id": "string",
            "type": "FORM | CODE | BROWSER | IDE | MEDIA | LONGFORM | PULL_REQUEST | DIFF | ...",
            "content": {}
          }
        ],
        "attachments": [
          {
            "id": "string",
            "filename": "string",
            "mimeType": "string",
            "size": 1024,
            "path": "string"
          }
        ],
        "createdBy": { "id": "string", "name": "string", "image": "string" }
      }
    ],
    "count": 12
  }
}

Send Message (Live Mode)

For tasks with mode: "live". The AI response arrives asynchronously via Pusher.

POST /api/chat/message

Request Body

{
  "taskId": "string (required)",
  "message": "string (required)",
  "sourceWebsocketID": "string (optional, Pusher socket ID to exclude from broadcast)",
  "contextTags": [{ "type": "PRODUCT_BRIEF | FEATURE_BRIEF | SCHEMATIC", "id": "string" }],
  "artifacts": [{ "type": "ArtifactType", "content": {} }],
  "attachments": [{ "path": "string", "filename": "string", "mimeType": "string", "size": 1024 }]
}

Response (201)

{
  "success": true,
  "message": {
    "id": "string",
    "taskId": "string",
    "message": "string",
    "role": "USER",
    "timestamp": "datetime",
    "status": "SENT",
    "artifacts": [],
    "attachments": [],
    "createdBy": { "id": "string", "name": "string", "image": "string" }
  }
}

The AI response will arrive via Pusher on channel task-{taskId}, event new-message, with the new message ID as payload. Fetch the full message with GET /api/chat/messages/{messageId}.

Fetch Single Message

Used after receiving a Pusher new-message event.

GET /api/chat/messages/{messageId}

Response (200)

{
  "success": true,
  "data": {
    "id": "string",
    "taskId": "string",
    "message": "string",
    "role": "USER | ASSISTANT",
    "timestamp": "datetime",
    "status": "SENDING | SENT | ERROR",
    "artifacts": [],
    "attachments": [],
    "createdBy": { "id": "string", "name": "string", "image": "string" }
  }
}

Update Task

PATCH /api/tasks/{taskId}

Request Body

{
  "status": "TODO | IN_PROGRESS | DONE | CANCELLED | BLOCKED (optional)",
  "workflowStatus": "PENDING | IN_PROGRESS | COMPLETED | ERROR | HALTED | FAILED (optional)",
  "archived": "boolean (optional)"
}

Response (200)

{
  "success": true,
  "task": {
    "id": "string",
    "title": "string",
    "status": "TaskStatus",
    "workflowStatus": "WorkflowStatus",
    "archived": false,
    "updatedAt": "datetime"
  }
}

Task Stats

GET /api/tasks/stats?workspaceId={workspaceId}

Response (200)

{
  "success": true,
  "data": {
    "total": 42,
    "inProgress": 5,
    "waitingForInput": 2
  }
}

Notification Count

GET /api/workspaces/{slug}/tasks/notifications-count

Response (200)

{
  "success": true,
  "data": {
    "waitingForInputCount": 3
  }
}

Real-Time Updates (Pusher)

Subscribe to these Pusher channels for live updates:

Channel Event Payload Description
task-{taskId} new-message "messageId" New chat message. Fetch via GET /api/chat/messages/{messageId}
task-{taskId} workflow-status-update { taskId, workflowStatus, timestamp } Workflow status changed
task-{taskId} task-title-update { taskId, newTitle, previousTitle } Task title changed
workspace-{slug} workspace-task-title-update { taskId, newTitle, previousTitle } Task title changed (for list views)
task-{taskId} pr-status-change varies PR status changed

Pusher config uses NEXT_PUBLIC_PUSHER_KEY and NEXT_PUBLIC_PUSHER_CLUSTER.

Enums

Enum Values
TaskStatus TODO, IN_PROGRESS, DONE, CANCELLED, BLOCKED
WorkflowStatus PENDING, IN_PROGRESS, COMPLETED, ERROR, HALTED, FAILED
Priority LOW, MEDIUM, HIGH, CRITICAL
ChatRole USER, ASSISTANT
ChatStatus SENDING, SENT, ERROR
ArtifactType FORM, CODE, BROWSER, IDE, MEDIA, STREAM, LONGFORM, BUG_REPORT, GRAPH, WORKFLOW, PULL_REQUEST, DIFF, PUBLISH_WORKFLOW, BOUNTY

Clone this wiki locally