Tasks

Related events: task.created · task.updated · task.verified

Endpoints

POST/v1/brands/{brand}/tasks
PATCH/v1/brands/{brand}/tasks/{task}
GET/v1/brands/{brand}/tasks/{task}
GET/v1/brands/{brand}/tasks
GET/v1/brands/{brand}/tasks/{task}/plan

The Task object

Attributes

idstring
Unique identifier of the object (prefixed, opaque).
objectstring
task
brandstring
The brand the object belongs to (br_…).
titlestring
descriptionstringnullable
statusenum
Kanban columns of the "À traiter" screen, in board order: À faire → En cours → En vérification → Vérifié. Transitions move one column at a time (the card CTA moves forward, the "←" button moves back); a verified task is terminal.
Possible values: todo · in_progress · in_verification · verified
kindenum
Nature of the fix — matches the mockup filter pills (Write-back / Contenu / Technique). Write-back = applicable in one click on a Shopify product (description, SEO, barcode — SKO-151); everything else is done by hand, with a guide.
Possible values: writeback · content · technical
effortenumnullable
T-shirt sizing shown on the kanban cards (S · < 1 h, M · ½ journée, L · 2-3 j).
Possible values: s · m · l
sourceenum
Where the task came from: created by hand ("+ Correctif manuel"), from a failing SEO or readiness check, from an alert, from a vacant territory on the Concurrents screen, or from a source the assistants cite without the brand (« Sources à conquérir »).
Possible values: manual · seo_check · alert · readiness · opportunity · perception · source_gap
source_labelstringnullable
alertstringnullable
The alert the task was created from (alrt_…), when source = alert.
productstringnullable
impactstringnullable
gainstringnullable
guideobjectnullable
Show child attributes
- topicstring
- platformenum
  Possible values: shopify · generic
- stepsarray of string
assigneeobjectnullable
Show child attributes
- namestring
started_atstringnullable
published_atstringnullable
verify_atstringnullable
verified_atstringnullable
livemodeboolean
true for live data, false for the test-mode sandbox.
createdinteger
Time at which the object was created (unix timestamp, seconds).
updatedstring
Time at which the object was last updated.

The Task object


{
  "id": "task_031CQmvL2QQbe3t38Gyo91",
  "object": "task",
  "brand": "br_031CQGx2DNM4mxT2CO7BL3",
  "title": "Corriger le prix affiché de la Grizl CF SL 7",
  "description": "ChatGPT annonce 2 199 € alors que le catalogue affiche 2 499 €.",
  "status": "in_progress",
  "kind": "content",
  "effort": "s",
  "source": "alert",
  "source_label": "Alerte · hallucination de prix",
  "alert": "alrt_031CQlTxUKUOFYaHSd3kBY",
  "product": "Grizl CF SL 7",
  "impact": "Critique",
  "gain": null,
  "guide": {
    "topic": "price_source",
    "platform": "shopify",
    "steps": [
      "Open the alert and its answers: note the sources cited next to the wrong price.",
      "Old promotion page still online: Online Store → Pages, hide it, then create a URL redirect (search « URL redirects » in the admin) to the current product page.",
      "Check the variant's price and « compare-at price » in Products; update Google Merchant Center and the comparison sites.",
      "Click « Verify » on the alert: a targeted re-sampling confirms the fix."
    ]
  },
  "assignee": {
    "name": "Camille Martin"
  },
  "started_at": "2026-09-21T09:12:00Z",
  "published_at": null,
  "verify_at": null,
  "verified_at": null,
  "livemode": true,
  "created": 1790000000,
  "updated": 1790003600
}

The Task plan object

Attributes

objectstring
task_plan
taskstring
statusenum
A fix plan being written (pending), written (ready), or not written (failed: no provider key, the model failed or answered nothing usable — the task keeps its fixed guide, nothing is invented).
Possible values: pending · ready · failed
contentobjectnullable
Show child attributes
- summarystring
- stepsarray of object
  Show child attributes
  - titlestring
  - detailstring
  - wherestringnullable
- verificationstring
- caveatsarray of string
platformenumnullable
What the brand's site runs on. Chosen by a person (onboarding, Réglages → Marque, an agency adding the brand), set by a connected integration, or detected from the site's crawl (Seo\Services\PlatformDetector) — see BrandPlatformSource. Only Shopify has a connector; the others tell the fix plans which admin to walk through. custom = a site built in-house.
Possible values: shopify · woocommerce · prestashop · magento · bigcommerce · wix · squarespace · webflow · wordpress · custom
localestring
generated_atstringnullable
livemodeboolean
true for live data, false for the test-mode sandbox.

The Task plan object


{
  "object": "task_plan",
  "task": "task_034ofz9YVp1OJwgvw6Kl58",
  "status": "pending",
  "content": {
    "summary": "string",
    "steps": [
      {
        "title": "Grizl CF SL 7",
        "detail": "string",
        "where": "string"
      }
    ],
    "verification": "string",
    "caveats": [
      "string"
    ]
  },
  "platform": "shopify",
  "locale": "fr",
  "generated_at": "2026-09-21T02:40:00Z",
  "livemode": true
}

Create a task

POST/v1/brands/{brand}/tasks

Adds a manual fix to the backlog, in the todo column.

Parameters

brandstringrequired
Brand id (br_…).
titlestringrequired
descriptionstringnullable
kindenumrequired
Nature of the fix — matches the mockup filter pills (Write-back / Contenu / Technique). Write-back = applicable in one click on a Shopify product (description, SEO, barcode — SKO-151); everything else is done by hand, with a guide.
Possible values: writeback · content · technical
effortenumnullable
T-shirt sizing shown on the kanban cards (S · < 1 h, M · ½ journée, L · 2-3 j).
Possible values: s · m · l
productstringnullable
impactstringnullable
source_labelstringnullable

Returns

Returns the created task object. Raises an error if something goes wrong.

curl


curl -X POST https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{"title":"Grizl CF SL 7","kind":"writeback","description":"Rewrite the product copy so the frame warranty is stated."}'

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"title":"Grizl CF SL 7","kind":"writeback","description":"Rewrite the product copy so the frame warranty is stated."}),
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('POST', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
    'json' => ['title' => 'Grizl CF SL 7', 'kind' => 'writeback', 'description' => 'Rewrite the product copy so the frame warranty is stated.'],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.post(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
    json={"title": "Grizl CF SL 7", "kind": "writeback", "description": "Rewrite the product copy so the frame warranty is stated."},
)
data = response.json()

Response


{
  "id": "task_031CQmvL2QQbe3t38Gyo91",
  "object": "task",
  "brand": "br_031CQGx2DNM4mxT2CO7BL3",
  "title": "Corriger le prix affiché de la Grizl CF SL 7",
  "description": "ChatGPT annonce 2 199 € alors que le catalogue affiche 2 499 €.",
  "status": "in_progress",
  "kind": "content",
  "effort": "s",
  "source": "alert",
  "source_label": "Alerte · hallucination de prix",
  "alert": "alrt_031CQlTxUKUOFYaHSd3kBY",
  "product": "Grizl CF SL 7",
  "impact": "Critique",
  "gain": null,
  "guide": {
    "topic": "price_source",
    "platform": "shopify",
    "steps": [
      "Open the alert and its answers: note the sources cited next to the wrong price.",
      "Old promotion page still online: Online Store → Pages, hide it, then create a URL redirect (search « URL redirects » in the admin) to the current product page.",
      "Check the variant's price and « compare-at price » in Products; update Google Merchant Center and the comparison sites.",
      "Click « Verify » on the alert: a targeted re-sampling confirms the fix."
    ]
  },
  "assignee": {
    "name": "Camille Martin"
  },
  "started_at": "2026-09-21T09:12:00Z",
  "published_at": null,
  "verify_at": null,
  "verified_at": null,
  "livemode": true,
  "created": 1790000000,
  "updated": 1790003600
}

Update a task

PATCH/v1/brands/{brand}/tasks/{task}

Updates its fields and/or moves it on the kanban with status — one column at a time (invalid_transition otherwise). Moving to verified may record the measured gain. A refused move changes nothing.

Parameters

brandstringrequired
Brand id (br_…).
taskstringrequired
Task id (task_…).
titlestring
descriptionstringnullable
kindenum
Nature of the fix — matches the mockup filter pills (Write-back / Contenu / Technique). Write-back = applicable in one click on a Shopify product (description, SEO, barcode — SKO-151); everything else is done by hand, with a guide.
Possible values: writeback · content · technical
effortenumnullable
T-shirt sizing shown on the kanban cards (S · < 1 h, M · ½ journée, L · 2-3 j).
Possible values: s · m · l
productstringnullable
impactstringnullable
source_labelstringnullable
verify_atstringnullable
statusenum
Kanban columns of the "À traiter" screen, in board order: À faire → En cours → En vérification → Vérifié. Transitions move one column at a time (the card CTA moves forward, the "←" button moves back); a verified task is terminal.
Possible values: todo · in_progress · in_verification · verified
gainstringnullable

Returns

Returns the updated task object. Raises an error if something goes wrong.

curl


curl -X PATCH https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks/task_034ofz9YVp1OJwgvw6Kl58 \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{"title":"Grizl CF SL 7","description":"Rewrite the product copy so the frame warranty is stated."}'

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks/task_034ofz9YVp1OJwgvw6Kl58', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"title":"Grizl CF SL 7","description":"Rewrite the product copy so the frame warranty is stated."}),
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('PATCH', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks/task_034ofz9YVp1OJwgvw6Kl58', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
    'json' => ['title' => 'Grizl CF SL 7', 'description' => 'Rewrite the product copy so the frame warranty is stated.'],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.patch(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks/task_034ofz9YVp1OJwgvw6Kl58",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
    json={"title": "Grizl CF SL 7", "description": "Rewrite the product copy so the frame warranty is stated."},
)
data = response.json()

Response


{
  "id": "task_031CQmvL2QQbe3t38Gyo91",
  "object": "task",
  "brand": "br_031CQGx2DNM4mxT2CO7BL3",
  "title": "Corriger le prix affiché de la Grizl CF SL 7",
  "description": "ChatGPT annonce 2 199 € alors que le catalogue affiche 2 499 €.",
  "status": "in_progress",
  "kind": "content",
  "effort": "s",
  "source": "alert",
  "source_label": "Alerte · hallucination de prix",
  "alert": "alrt_031CQlTxUKUOFYaHSd3kBY",
  "product": "Grizl CF SL 7",
  "impact": "Critique",
  "gain": null,
  "guide": {
    "topic": "price_source",
    "platform": "shopify",
    "steps": [
      "Open the alert and its answers: note the sources cited next to the wrong price.",
      "Old promotion page still online: Online Store → Pages, hide it, then create a URL redirect (search « URL redirects » in the admin) to the current product page.",
      "Check the variant's price and « compare-at price » in Products; update Google Merchant Center and the comparison sites.",
      "Click « Verify » on the alert: a targeted re-sampling confirms the fix."
    ]
  },
  "assignee": {
    "name": "Camille Martin"
  },
  "started_at": "2026-09-21T09:12:00Z",
  "published_at": null,
  "verify_at": null,
  "verified_at": null,
  "livemode": true,
  "created": 1790000000,
  "updated": 1790003600
}

Retrieve a task

GET/v1/brands/{brand}/tasks/{task}

Parameters

brandstringrequired
Brand id (br_…).
taskstringrequired
Task id (task_…).

Returns

Returns the task object. Raises an error if something goes wrong.

curl


curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks/task_034ofz9YVp1OJwgvw6Kl58 \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks/task_034ofz9YVp1OJwgvw6Kl58', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
  },
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('GET', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks/task_034ofz9YVp1OJwgvw6Kl58', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.get(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks/task_034ofz9YVp1OJwgvw6Kl58",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Response


{
  "id": "task_031CQmvL2QQbe3t38Gyo91",
  "object": "task",
  "brand": "br_031CQGx2DNM4mxT2CO7BL3",
  "title": "Corriger le prix affiché de la Grizl CF SL 7",
  "description": "ChatGPT annonce 2 199 € alors que le catalogue affiche 2 499 €.",
  "status": "in_progress",
  "kind": "content",
  "effort": "s",
  "source": "alert",
  "source_label": "Alerte · hallucination de prix",
  "alert": "alrt_031CQlTxUKUOFYaHSd3kBY",
  "product": "Grizl CF SL 7",
  "impact": "Critique",
  "gain": null,
  "guide": {
    "topic": "price_source",
    "platform": "shopify",
    "steps": [
      "Open the alert and its answers: note the sources cited next to the wrong price.",
      "Old promotion page still online: Online Store → Pages, hide it, then create a URL redirect (search « URL redirects » in the admin) to the current product page.",
      "Check the variant's price and « compare-at price » in Products; update Google Merchant Center and the comparison sites.",
      "Click « Verify » on the alert: a targeted re-sampling confirms the fix."
    ]
  },
  "assignee": {
    "name": "Camille Martin"
  },
  "started_at": "2026-09-21T09:12:00Z",
  "published_at": null,
  "verify_at": null,
  "verified_at": null,
  "livemode": true,
  "created": 1790000000,
  "updated": 1790003600
}

List tasks

GET/v1/brands/{brand}/tasks

The backlog of fixes of a brand, newest first.

Parameters

brandstringrequired
Brand id (br_…).
statusstring
sourcestring
limitinteger
Number of objects to return, between 1 and 100 (default 20).
starting_afterstring
Cursor: the id of the last object of the previous page.

Returns

A dictionary with a data property holding up to limit task objects, newest first, and has_more telling whether another page exists. Raises an error if something goes wrong.

curl


curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks?limit=3 \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks?limit=3', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
  },
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('GET', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks?limit=3', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.get(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks?limit=3",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Response


{
  "object": "list",
  "url": "/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks",
  "has_more": false,
  "data": [
    {
      "id": "task_031CQmvL2QQbe3t38Gyo91",
      "object": "task",
      "brand": "br_031CQGx2DNM4mxT2CO7BL3",
      "title": "Corriger le prix affiché de la Grizl CF SL 7",
      "description": "ChatGPT annonce 2 199 € alors que le catalogue affiche 2 499 €.",
      "status": "in_progress",
      "kind": "content",
      "effort": "s",
      "source": "alert",
      "source_label": "Alerte · hallucination de prix",
      "alert": "alrt_031CQlTxUKUOFYaHSd3kBY",
      "product": "Grizl CF SL 7",
      "impact": "Critique",
      "gain": null,
      "guide": {
        "topic": "price_source",
        "platform": "shopify",
        "steps": [
          "Open the alert and its answers: note the sources cited next to the wrong price.",
          "Old promotion page still online: Online Store → Pages, hide it, then create a URL redirect (search « URL redirects » in the admin) to the current product page.",
          "Check the variant's price and « compare-at price » in Products; update Google Merchant Center and the comparison sites.",
          "Click « Verify » on the alert: a targeted re-sampling confirms the fix."
        ]
      },
      "assignee": {
        "name": "Camille Martin"
      },
      "started_at": "2026-09-21T09:12:00Z",
      "published_at": null,
      "verify_at": null,
      "verified_at": null,
      "livemode": true,
      "created": 1790000000,
      "updated": 1790003600
    }
  ]
}

Retrieve a task’s plan

GET/v1/brands/{brand}/tasks/{task}/plan

The step-by-step plan a model wrote for the task in the app, adapted to the brand’s platform and to the task’s evidence. Read only: plans are written on demand from the app, never through the API. resource_missing until one was written.

Parameters

brandstringrequired
Brand id (br_…).
taskstringrequired
Task id (task_…).

Returns

Returns the task_plan object. Raises an error if something goes wrong.

curl


curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks/task_034ofz9YVp1OJwgvw6Kl58/plan \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks/task_034ofz9YVp1OJwgvw6Kl58/plan', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
  },
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('GET', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks/task_034ofz9YVp1OJwgvw6Kl58/plan', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.get(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/tasks/task_034ofz9YVp1OJwgvw6Kl58/plan",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Response


{
  "object": "task_plan",
  "task": "task_034ofz9YVp1OJwgvw6Kl58",
  "status": "pending",
  "content": {
    "summary": "string",
    "steps": [
      {
        "title": "Grizl CF SL 7",
        "detail": "string",
        "where": "string"
      }
    ],
    "verification": "string",
    "caveats": [
      "string"
    ]
  },
  "platform": "shopify",
  "locale": "fr",
  "generated_at": "2026-09-21T02:40:00Z",
  "livemode": true
}