Skip to Content
API referenceInbox

Inbox

Endpoints

The Inbox item object

Attributes

  • objectstring

    inbox_item

  • idstring

    {kind}:{identity} (alert:{uuid}, readiness:{check}, perception:{product}:{gap}…), stable while the object holds. Not a prefixed id: a line is not a record.

  • kindenum

    The object behind the line: alert, task, a failing readiness_check or seo_check, a perception_gap, a vacant territory (opportunity), a site to win (source_gap), a finding of the Pages screen (page_insight) or a listing of an establishment.

    Possible values: alert · task · readiness_check · seo_check · perception_gap · opportunity · source_gap · page_insight · listing

  • groupenum

    now: costs sales this week · week: raises the visibility · later: when you can · verified: a task verified in the last 90 days.

    Possible values: now · week · later · verified

  • scoreinteger

    The order inside the group, higher first. Compare within a group only.

  • severityenumnullable

    Possible values: critical · medium · low

  • titlestringnullable

    Composed by Skoup, in English.

  • impactobject
    Show child attributes
    • labelstringnullable
    • pointsintegernullable

      A measured number when the source counts one; null otherwise, never 0 for « unknown ».

    • unitenumnullable

      What the impact.points of a line count — the scale its source measures in. Points of different units never compare across kinds; inside a group they only break ties. | | |---| | readiness <br/> Readiness score points (/100). | | perception <br/> Perception score points (/100). | | accuracy <br/> Accuracy points (price and stock claims). | | visibility <br/> Visibility share points. | | clicks <br/> Google clicks (Search Console). | | answers <br/> AI answers (runs). | | revenue <br/> Revenue, in the market's currency. |

      Possible values: readiness · perception · accuracy · visibility · clicks · answers · revenue

  • effortenumnullable

    T-shirt sizing shown on the kanban cards (S · < 1 h, M · ½ journée, L · 2-3 j).

    Possible values: s · m · l

  • marketstringnullable

    null for a task whose source names no market.

  • productobjectnullable

    id = prod_… when the line is about a catalogue product.

    Show child attributes
    • idstringnullable

      Unique identifier of the object (prefixed, opaque).

    • titlestring
  • locationobjectnullable
    Show child attributes
    • idstring

      Unique identifier of the object (prefixed, opaque).

    • namestringnullable
  • modelsarray of string
  • alertstringnullable

    The alert behind the line (kind: alert).

  • taskobjectnullable

    The task behind the line (kind: task).

    Show child attributes
    • idstring

      Unique identifier of the object (prefixed, opaque).

    • 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

  • plan_featureenumnullable

    The plan feature the line needs and the workspace lacks: the line is listed locked, never hidden.

    Possible values: opportunities

  • last_seen_atstringnullable
  • livemodeboolean

    true for live data, false for the test-mode sandbox.

The Inbox item object
{
  "object": "inbox_item",
  "id": "alert:0199a3c2-7a4e-7c1b-9d2f-3e8b1c5a6f70",
  "kind": "alert",
  "group": "now",
  "score": 12,
  "severity": "critical",
  "title": "Grizl CF SL 7",
  "impact": {
    "label": "string",
    "points": 12,
    "unit": "readiness"
  },
  "effort": "s",
  "market": "FR",
  "product": {
    "id": "string",
    "title": "Grizl CF SL 7"
  },
  "location": {
    "id": "string",
    "name": "Nordvelo"
  },
  "models": [
    "string"
  ],
  "alert": "alrt_034sOvSY3W2DUqG0hp23SH",
  "task": {
    "id": "string",
    "status": "todo"
  },
  "plan_feature": "opportunities",
  "last_seen_at": "2026-09-21T02:40:00Z",
  "livemode": true
}

List the inbox

GET/v1/brands/{brand}/inbox

Everything the brand can fix on a market, in the order to deal with it — the « Correctifs » queue of the app: open alerts, tasks, failing readiness and SEO checks, perception gaps, vacant territories, sources to win, page findings and listings. One line per existing object: a task absorbs the alert or the check it was opened from. Lines come in queue order: now, week, later, then verified (tasks verified in the last 90 days, with q=is:all or group=verified). The « Premiers pas » checklist of the app is not listed (it belongs to a member).

Parameters

  • brandstringrequired

    Brand id (br_…).

  • groupstring
  • limitstring
  • starting_afterstring

    Cursor: the id of the last object of the previous page.

Returns

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

curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/inbox?limit=3 \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"
Response
{
  "object": "list",
  "url": "/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/inbox",
  "has_more": false,
  "data": [
    {
      "object": "inbox_item",
      "id": "alert:0199a3c2-7a4e-7c1b-9d2f-3e8b1c5a6f70",
      "kind": "alert",
      "group": "now",
      "score": 12,
      "severity": "critical",
      "title": "Grizl CF SL 7",
      "impact": {
        "label": "string",
        "points": 12,
        "unit": "readiness"
      },
      "effort": "s",
      "market": "FR",
      "product": {
        "id": "string",
        "title": "Grizl CF SL 7"
      },
      "location": {
        "id": "string",
        "name": "Nordvelo"
      },
      "models": [
        "string"
      ],
      "alert": "alrt_034sOvSY3W2DUqG0hp23SH",
      "task": {
        "id": "string",
        "status": "todo"
      },
      "plan_feature": "opportunities",
      "last_seen_at": "2026-09-21T02:40:00Z",
      "livemode": true
    }
  ]
}
Last updated on
EventsMarkets