Tasks

A task is a fix to make so the AI assistants say the right thing about the brand: rewrite a product description, fix a price in the store, add structured data to a page… Tasks are created by hand, or by Skoup from an alert, a failing SEO or readiness check, a perception gap, a positioning opportunity or a source to win (source). Each one says what to change (kind: writeback, content, technical), how big it is (effort: s, m, l) and, when Skoup knows how, a step-by-step guide.

Statuses of a task

todoin_progressin_verificationverified

A task moves one column at a time, forward or back. Moving to in_verification plans the check (verify_at = next weekly sampling). A task created from an alert becomes verified by itself when its alert is resolved.

I want to…

I want to…	Call
Create a task	`POST /v1/brands/{brand}/tasks` (`title`, `kind`)
Move a task forward	`PATCH /v1/brands/{brand}/tasks/{task}` with `status`
Mark it verified with the measured gain	`PATCH …/tasks/{task}` with `status: "verified"` and `gain`
Edit its fields	`PATCH …/tasks/{task}` (`title`, `description`, `effort`, `impact`…)
List what is left to do	`GET /v1/brands/{brand}/tasks?status=todo`
List the fixes that came from alerts	`GET /v1/brands/{brand}/tasks?source=alert`
Read one task and its guide	`GET /v1/brands/{brand}/tasks/{task}`
Read the tailored plan written in the app	`GET /v1/brands/{brand}/tasks/{task}/plan`

Scopes: tasks:read, tasks:write. Events: task.created, task.updated (with previous_attributes), task.verified.

Scenario: sync Skoup’s fixes into Jira

Subscribe an endpoint to task.created and task.updated.
On task.created, create the Jira ticket from data.object (title, description, guide) and store the task_… id on it.
When the ticket moves, move the Skoup task one column at a time:


curl -X PATCH https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/tasks/task_031CQmvL2QQbe3t38Gyo91 \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{"status":"in_progress"}'

When the ticket is closed, send {"status":"in_verification"}: Skoup checks the fix at the next weekly sampling. On task.updated, update the ticket from data.object.status.

Pitfalls

One column at a time. todo → in_verification in one call answers 422 invalid_transition and changes nothing: send each step.
One PATCH, two events. A PATCH that edits fields and moves the status emits one task.updated per change.
No assignee through the API: workspace members are never exposed; assignee is read-only ({ name }).
guide or plan? guide is the standard procedure of the fix’s family (fixed text, Shopify version when the brand runs on Shopify). The plan is that procedure rewritten by AI for the brand’s platform, business and the task’s evidence. It only exists once someone clicked « Generate a tailored plan » in the app — otherwise 404 resource_missing. The API reads it, it never generates one. A failed plan has no content: follow the guide.
Test mode: the task is created and moved on the sandbox, then rolled back — the task.created event still reaches your test endpoints with livemode: false.