What is the difference between the two categories?

needs_you is everything waiting on a person. in_flight is work that was approved and is currently running. The default is needs_you, because that is the question people are actually asking.

What does the type field decide?

How a row is acted on. A task is closed through the resolve endpoint, an ask is answered in the session it names, and a work item is approved in the dashboard.

Why does one problem not create many rows?

Because repeats update a single row and increment its occurrence count. That keeps the list readable and turns the count into a useful signal of how long something has been ignored.

Is this the right thing to poll?

It is the cheapest way to answer whether anything is stuck. It is read-only and spends no credits, so a scheduled check costs nothing but the request.

Does an empty inbox mean the agent is idle?

No. It means nothing is waiting on a person. Work can be running, which is what the in_flight category shows.

REST API endpoint

GET /v1/inbox — the one list that says whether anything is stuck

Everything waiting on a person — approvals, work the agent could not finish, and problems it raised — in one read-only call with two categories.

Karl-Gustav Kallasmaa, Founder & CEOLast updated 4 September 2026

GET /v1/inboxNeeds read scopeSpends no creditsMCP tool: list_inbox

The request

Paste this and change the key. Every endpoint takes a bearer key and none takes a workspace id — the key names the workspace.

curl -G https://api.attensira.com/v1/inbox \
  --data-urlencode "category=needs_you" \
  -H "Authorization: Bearer atn_live_<your key>"

Parameters

Every parameter the published reference documents, and nothing it does not.

Name	In	Type	Default	Notes
category	query	enum	needs_you	needs_you for rows waiting on a person, in_flight for work that was approved and is running.

The response (200)

Abbreviated, never invented — this is the shape the published reference documents.

{
  "items": [
    {
      "type": "task",
      "id": "tsk_4f2a",
      "category": "needs_you",
      "title": "Connect GitHub so I can open the fix as a pull request",
      "reason": "Tried: github.create_pull_request returned 403\n\nNeeded: write access to the repo",
      "session_id": "ses_9b11",
      "updated_at": "2026-09-01T03:00:00Z",
      "task": {
        "id": "tsk_4f2a",
        "kind": "blocked",
        "state": "open",
        "occurrences": 14,
        "first_seen_at": "2026-08-19T03:00:00Z",
        "last_seen_at": "2026-09-01T03:00:00Z"
      }
    }
  ]
}

What goes wrong, and what it means

The condition on the left, the correct reading of it on the right.

A row has a high occurrences count: The same problem has been seen that many times and repeats update one row rather than adding another. A count well above one means nobody has acted on it yet.
You try to resolve a row whose type is not task: Only tasks are resolvable through the API. An ask is answered inside its own session, and a work item is approved in the dashboard.
The inbox is empty but nothing seems to be happening: An empty needs_you list means nothing is blocked on a person. Check in_flight, and check whether the automations you expect to be running are active.

What this endpoint cannot tell you

The limits are part of the answer, not a disclaimer under it.

It cannot approve anything. The endpoint is read-only: a work item is approved in the dashboard and an ask is answered inside its session, so an integration built on this list can report a blockage but not clear one.
It cannot tell you why an automation produced a poor answer. It carries what needs a person, not the reasoning of a run — that lives in the session's event trace, fetched separately.

An agent that works on a schedule needs one question answered before any other: is it moving, or is it waiting for me? This endpoint is that question. It returns everything currently sitting on a human — approvals the agent stopped for, work it could not finish alone, and problems it raised and could not solve.

Two categories

needs_you is the default and is the list people mean when they ask what the inbox says. in_flight is its counterpart: work that has been approved and is running. Between them they distinguish the two ways a workspace can look quiet.

An empty needs_you list does not mean nothing is happening; it means nothing is blocked on you. Reading it as idleness is the usual mistake, and the second category is the correction.

Read the type before you do anything

Every row carries a type, and the type decides how the row is dealt with. A task is something the agent raised and it is closed through the resolve endpoint. An ask is a run parked on an approval, and it is answered inside the session the row names. A work_item is a proposal, approved or declined in the dashboard.

That distinction matters for anyone building on this API, because only one of the three is actionable from here. An integration that tries to resolve an ask is reaching for a control the API does not expose, and the reason is not an oversight: an approval is a decision about work, and answering it belongs in the conversation where the work is happening.

The occurrence count is the most useful field

Repeats do not pile up. When the same problem is seen again, the existing row is updated and its occurrence count goes up, rather than a new row appearing. That keeps the list short enough to read, and it turns the count into a straightforward measure of neglect: a row that has been seen fourteen times is not a new issue, it is a fortnight of an agent trying to do something it cannot do.

Alongside it sit first-seen and last-seen timestamps, which give the same story with dates on it. A row with a high count and a recent last-seen is actively costing you work; a row with a high count and a stale last-seen is something the agent has stopped attempting.

What a row actually says

Beyond the type and the counters, a row carries a title in plain language and a reason that names what was tried and what was needed. The reason is written for a person to act on rather than for a log — the documented example is an agent that attempted to open a pull request, got a permissions failure, and needs write access to the repository. That is a sentence somebody can do something about in a minute.

Most rows also name a session, which is the thread the row came out of. Following it gives the full trace of what the agent was doing when it stopped.

Where it fits in an integration

Because it is read-only and spends nothing, this is the natural thing for a scheduled check to poll. A daily job that fetches the needs-you list and posts anything with a rising occurrence count into a team channel is a small amount of code and removes the most common failure mode of an autonomous system, which is not that it does the wrong thing but that it silently waits.

Its twin on the other surface

The list_inbox MCP tool takes the same category argument and returns the same rows. It is worth having enabled in an assistant for exactly the reason above: "is anything blocked on me" is a question people ask conversationally far more often than they open a dashboard to check.

Questions people ask

What is the difference between the two categories?: needs_you is everything waiting on a person. in_flight is work that was approved and is currently running. The default is needs_you, because that is the question people are actually asking.
What does the type field decide?: How a row is acted on. A task is closed through the resolve endpoint, an ask is answered in the session it names, and a work item is approved in the dashboard.
Why does one problem not create many rows?: Because repeats update a single row and increment its occurrence count. That keeps the list readable and turns the count into a useful signal of how long something has been ignored.
Is this the right thing to poll?: It is the cheapest way to answer whether anything is stuck. It is read-only and spends no credits, so a scheduled check costs nothing but the request.
Does an empty inbox mean the agent is idle?: No. It means nothing is waiting on a person. Work can be running, which is what the in_flight category shows.

Sources

Every factual statement above, with the page it came from and the date that page was read.

The Attensira API reference states that repeats of the same inbox problem update one row rather than adding another, and that an occurrence count well above one means nobody has acted on it yet.
docs.attensira.com · retrieved 2026-09-04
“repeats update one row rather than adding another. A count well above 1 means nobody has acted on it yet.”
The API reference states that an inbox row's type decides how it is acted on — a work item is approved in the dashboard, an ask is answered in its session, and a task is resolved through the API.
docs.attensira.com · retrieved 2026-09-04
“type tells you how a row is acted on.”

The reference this is written from →Every endpoint →The same capability over MCP →