Inbox

The inbox is the « Correctifs » screen of the app as an API: one queue of everything the brand can fix on a market, whatever it comes from, already in the order to deal with it. Open alerts, tasks, failing readiness and SEO checks, perception gaps, vacant territories, sources to win, findings of the Pages screen, listings of an establishment: each line is one of them.

A line is not a record of its own. It IS an existing object, so it has no prefixed id: its id is composite (alert:{uuid}, task:{uuid}, readiness:{check}, seo:{check}, perception:{product}:{gap}, opportunity:{attribute}, source_gap:{host}, insight:{kind}:{hash}, listing:{id}:{kind}) and stable while the object holds. The objects that have a public id carry it (alert, task.id, product.id, location.id). The inbox writes nothing: you act on the object behind a line, through its own endpoints.

One line per object. A task absorbs what it was opened from: an alert, a check or a gap that already has an open task is listed as that task, never twice. A false price or stock that has an open alert is listed as the alert.

I want to…

I want to…	Call
Get the queue of a market, in order	`GET /v1/brands/{brand}/inbox?market=FR`
Only what costs sales this week	`GET /v1/brands/{brand}/inbox?group=now`
Only the critical alerts	`GET /v1/brands/{brand}/inbox?q=kind:alert severity:critical`
Everything, verified fixes included	`GET /v1/brands/{brand}/inbox?q=is:all`
Treat the alert behind a line	`POST /v1/brands/{brand}/alerts/{alert}/treat` with the line’s `alert`
Move the task behind a line	`PATCH /v1/brands/{brand}/tasks/{task}` with the line’s `task.id`
Track a line in your own task	`POST /v1/brands/{brand}/tasks` (a manual task: the line stays until its object is fixed — tasks tied to a check or a gap are opened from the app)

Scopes: alerts:read and tasks:read (the queue lists both). An assistant reads the same queue with the MCP tool list_inbox.

The groups

Lines come grouped, in this order, and sorted inside each group. Read them as they come: the order is the point.

`group`	What lands there
`now`	Costs sales this week: a `critical` alert; a wrong price, stock or establishment fact seen at least twice or still there after a verification; a visibility drop; an SEO regression; a false price or stock in the perception of a product; a page losing its clicks or receiving traffic while in error; a task whose verification date has passed; a small task (`effort: s`) that says what it wins.
`week`	Raises the visibility: a `medium` alert; a readiness or SEO check in error; a distorted or absent perception gap worth at least 2 points; a vacant territory; a listing that contradicts its establishment; the other open tasks.
`later`	When you can: a `low` alert; a check in warning; a small perception gap; a site to win; the minor page findings; an incomplete or missing listing.
`verified`	The tasks verified in the last 90 days — what the fixes changed. Listed only with `q=is:all`, `q=is:verified` or `group=verified`.

Inside a group: severity first, then impact.points, then how often the problem was seen, then the effort (small first), then the most recent. score is that order as one number: compare it within a group only.

Search

q takes the app’s search grammar. Without is:, only the open groups (now, week, later) are listed.

Qualifier	Values
`is:`	`open` (default), `verified`, `all`
`kind:`	`alert`, `task`, `audit` (readiness), `seo`, `perception`, `traffic`, `competitors`, `listing`
`severity:`	`critical`, `medium`, `low`
`product:` / `offer:` / `location:`	part of the product title or the establishment name, e.g. `product:"Strade 7"`
`model:`	`chatgpt`, `claude`, `gemini`, `perplexity`…
`effort:`	`s`, `m`, `l`
`after:` / `before:`	`YYYY-MM-DD`, on the last time the line was seen

- negates a qualifier (-kind:task); anything else is free text on the title.

Scenario: a Monday list for the team


curl -G "https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/inbox" \
  --data-urlencode "market=FR" \
  --data-urlencode "group=now" \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Run it after the weekly sampling.completed: the lines are already in order, post them as they come.

Pitfalls

No event. The inbox is computed when you call it; nothing « happens » to a line. Follow the objects instead: alert.created, alert.resolved, task.verified.
impact.points may be null. It is a measured number when the source counts one (readiness or perception points, answers, clicks, visibility points), never 0 for « unknown ». Points of different units do not compare.
A task is the brand’s. A task line has market: null when its source names no market, and is listed on every market.
Pagination is a cursor in queue order: limit (1–100, default 20) and starting_after = the id of the last line of the previous page. The queue may move between two calls (a sampling, a fix): start over rather than resume an old cursor.
A plan without the opportunities feature keeps one line opportunity:locked with plan_feature: "opportunities": the module is shown locked, never hidden.
Titles are in English, composed by Skoup from the measured facts.