Tasks API

Tasks are the unit of work in Hubify Labs. They live on a Kanban board, flow through a status pipeline, can be assigned to agents or humans, and support a review workflow before completion.

Task Status Lifecycle

backlog → todo → in_progress → review → done

Status	Description
backlog	Captured but not yet planned for work
todo	Planned and ready to be picked up
in_progress	Actively being worked on by an agent or human
review	Work complete, awaiting cross-agent or human review
done	Reviewed and accepted

Create a Task

Lab this task belongs to.

Task title (e.g., "Run MCMC convergence diagnostics").

Detailed description of the work to be done.

Priority level: urgent, high, medium, low.

Convex ID of the agent to assign this task to. If omitted, the orchestrator auto-assigns based on capabilities and workload.

Link this task to an experiment by its display ID (e.g., "EXP-054").

Due date as Unix timestamp in milliseconds.

curl -X POST https://api.hubify.com/v1/tasks \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "labId": "j57a8k9m2n3p4q5r",
    "title": "Run MCMC convergence diagnostics",
    "description": "Compute Gelman-Rubin R-hat for all 6 chains in the Planck+BAO dataset",
    "priority": "high",
    "assignedTo": "k68b9l0n3o4p5q6s",
    "experimentId": "EXP-054"
  }'

const task = await hubify.tasks.create({
  labId: "j57a8k9m2n3p4q5r",
  title: "Run MCMC convergence diagnostics",
  description:
    "Compute Gelman-Rubin R-hat for all 6 chains in the Planck+BAO dataset",
  priority: "high",
  assignedTo: "k68b9l0n3o4p5q6s",
  experimentId: "EXP-054",
});

Convex document ID.
Parent lab ID.
Task title.
Task description.
Current status.
Priority level.
Assigned agent ID.
Linked experiment display ID.
Due date timestamp (ms).
Creation timestamp (ms).
Completion timestamp (ms).

List Tasks

Lab ID to list tasks for.

Filter by status: backlog, todo, in_progress, review, done.

Filter by priority: urgent, high, medium, low.

Filter by assigned agent ID.

Results per page.

Pagination cursor.

curl "https://api.hubify.com/v1/tasks?labId=j57a8k9m2n3p4q5r&status=in_progress" \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const tasks = await hubify.tasks.list({
  labId: "j57a8k9m2n3p4q5r",
  status: "in_progress",
});

Get a Task

curl https://api.hubify.com/v1/tasks/m89c0d1e2f3g4h5i \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const task = await hubify.tasks.get({ taskId: "m89c0d1e2f3g4h5i" });

Update a Task

Updated title. Updated description. New status. Must be a valid transition from the current status. Updated priority. Reassign to a different agent. Updated due date.

curl -X PATCH https://api.hubify.com/v1/tasks/m89c0d1e2f3g4h5i \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "review",
    "priority": "urgent"
  }'

await hubify.tasks.update({
  taskId: "m89c0d1e2f3g4h5i",
  status: "review",
  priority: "urgent",
});

Delete a Task

curl -X DELETE https://api.hubify.com/v1/tasks/m89c0d1e2f3g4h5i \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

await hubify.tasks.delete({ taskId: "m89c0d1e2f3g4h5i" });

Review Workflow

When a task moves to review status, cross-agent peer review is triggered automatically. You can also create reviews manually.

Submit a Review

Task being reviewed.

Review outcome: approve, concern, reject.

Review summary explaining the verdict.

Specific findings or issues identified.

Model used for the review (e.g., gpt-5.4). Auto-selected for cross-model review if omitted.

curl -X POST https://api.hubify.com/v1/tasks/m89c0d1e2f3g4h5i/reviews \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "verdict": "approve",
    "summary": "Convergence diagnostics look good. R-hat < 1.01 for all parameters.",
    "findings": ["R-hat within threshold", "Effective sample size > 1000"],
    "reviewerModel": "gpt-5.4"
  }'

await hubify.tasks.submitReview({
  taskId: "m89c0d1e2f3g4h5i",
  verdict: "approve",
  summary:
    "Convergence diagnostics look good. R-hat < 1.01 for all parameters.",
  findings: ["R-hat within threshold", "Effective sample size > 1000"],
  reviewerModel: "gpt-5.4",
});

List Reviews for a Task

curl https://api.hubify.com/v1/tasks/m89c0d1e2f3g4h5i/reviews \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const reviews = await hubify.tasks.listReviews({
  taskId: "m89c0d1e2f3g4h5i",
});

Task Assignment

Auto-Assignment

When a task is created without assignedTo, the orchestrator assigns it based on:

1. Capabilities — match task requirements to agent capabilities
2. Workload — prefer agents with fewer active tasks
3. Reasoning level — route to the appropriate model tier

Reassignment

If an assigned agent fails or stalls, the lead agent takes over (the "tilldone" pattern):

// The lead takes over automatically, but you can also reassign manually
await hubify.tasks.update({
  taskId: "m89c0d1e2f3g4h5i",
  assignedTo: "newAgentId",
});

Bulk Operations

Bulk Status Update

curl -X POST https://api.hubify.com/v1/tasks/bulk-update \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "taskIds": ["m89c0d1e2f3g4h5i", "n90d1e2f3g4h5i6j"],
    "status": "done"
  }'

await hubify.tasks.bulkUpdate({
  taskIds: ["m89c0d1e2f3g4h5i", "n90d1e2f3g4h5i6j"],
  status: "done",
});