# Inbox and time

## Read the inbox: `list_notifications`

Shows the notifications addressed to you from all organisations the token reaches, latest
activity first. Without further options, only unread ones come back.

| Argument | Meaning |
|---|---|
| `status` | `unread` (default), `read` or `all` |
| `since` | only activity after this moment, ISO 8601 with offset or `Z` |
| `organisation_id` | this organisation only |
| `project_id` | this project only |
| `page`, `per_page` | page, at most 100 per page |

Each row carries a readable text. Rows about a ticket also name its id, number, title and
`project_id`, so the agent can open it right away with `get_ticket`. `meta.by_organisation` counts
the unread rows per organisation.

For the agent to see all organisations, it needs a token with **All organisations, including
future ones**. A token limited to some projects counts only those.

## Mark as read: `mark_notification_read`

Takes the `notification_id` from the list. A notification already read stays read, an archived one
is refused. Reading alone marks nothing.

## Book time: `create_time_session`

Books time on a ticket, always in your name.

| Argument | Meaning |
|---|---|
| `ticket_id` | required, the ticket's id |
| `duration` | `1:30` (hours:minutes), `90` (minutes) or `1.5` (hours) |
| `duration_minutes` | minutes as a number, instead of `duration`; exactly one of the two is required |
| `occurred_on` | day of the work, default today in your time zone |
| `description` | internal description |
| `customer_description` | description for the customer |

One booking covers at most 24 hours. Whether you may book on the ticket is decided, as always, by
your rights in the project.

## Booked time: `summarize_time_sessions`

Adds up a project's time by billing state and returns sums, not individual bookings.

| Sum | Meaning |
|---|---|
| `billed` | billed, with an invoice number |
| `in_billing` | in an open billing |
| `without_billing` | not assigned to any billing yet |
| `not_invoiced` | `in_billing` and `without_billing` together |
| `total` | everything |

Filters are `start_date`, `end_date`, `creator` (`me` or a user id) and `ticket` (id or number). The
field `scope` says whether the numbers cover all bookings of the project or only your own (`own`).
That depends on your rights.