> For the complete documentation index, see [llms.txt](https://docs.tiny.plus/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tiny.plus/api/endpoints/dashboards.md).

# Dashboards

<mark style="color:blue;">`GET`</mark> `https://api.tiny.plus/v2/dashboards`

A person's dashboards, as the Dashboard page shows them: each dashboard a grid of panels, each panel a tile, a list, the pipeline strip, their meetings and tasks and the rest, read with a **scope** of whose records and which period. These endpoints read a dashboard; a dashboard is laid out and edited on the web. See the [Dashboard guide](https://docs.tiny.plus/guides/everyday/for-me.md).

## The person's dashboards

```bash
curl "https://api.tiny.plus/v2/dashboards" \
  -H "Authorization: Bearer {{user_access_token}}"
```

```json
[
    { "id": 51980, "name": "Overview", "panels": 9, "first": true, "shared": false, "scope": { "who": "mine", "period": "this_quarter" }, "url": "/dashboard/51980" },
    { "id": 51981, "name": "Leadership", "panels": 6, "first": false, "shared": true, "scope": { "who": "all", "period": "this_fy" }, "url": "/dashboard/51981" }
]
```

In the order the person keeps them. `first` marks the one the Dashboard menu opens. `shared` marks someone else's dashboard, shared with the firm: the person reads it but can't edit it (`perm_edit` is false on it), and it comes after their own unless they have dragged it elsewhere. `scope` is the scope the person sees on it (below).

## One dashboard

<mark style="color:blue;">`GET`</mark> `https://api.tiny.plus/v2/dashboards/{id}`

| Parameter | Description                                                                                              |
| --------- | -------------------------------------------------------------------------------------------------------- |
| `who`     | Read the dashboard as if this were chosen on its Showing chip: a key from `scope.choices.who`. Not kept. |
| `period`  | The same for the Period chip: a key from `scope.choices.period`. Not kept.                               |
| `month`   | `YYYY-MM`: the month a Calendar panel shows. This month by default.                                      |

```json
{
    "id": 51980,
    "name": "Overview",
    "perm_edit": true,
    "scope": {
        "who": "mine",
        "period": "this_quarter",
        "choices": {
            "who": [
                { "key": "mine", "label": "Mine", "team": null },
                { "key": "t228967", "label": "Sydney", "team": 228967 },
                { "key": "all", "label": "Everyone", "team": null }
            ],
            "period": [
                { "key": "this_week", "label": "This week" },
                { "key": "this_month", "label": "This month" },
                { "key": "this_quarter", "label": "This quarter" },
                { "key": "this_fy", "label": "This financial year" },
                { "key": "last_90", "label": "Last 90 days" },
                { "key": "last_12m", "label": "Last 12 months" }
            ]
        }
    },
    "rows": [
        [ { "item": 0, "type": "project_pipeline", "kind": "strip", "width": 12, "...": "..." } ],
        [ { "item": 1, "kind": "tile", "width": 3, "...": "..." }, { "item": 2, "kind": "tile", "width": 3, "...": "..." } ]
    ],
    "url": "/dashboard/51980"
}
```

`rows` is the layout: rows of panels, each row adding up to twelve `width` units. On a narrow screen draw every panel full width, with tiles two to a row.

### The scope

`who` is whose records the dashboard reads: `mine`, a team's `t<id>`, or `all` (everyone's). `choices.who` lists what this person may choose: their own teams where the account opens the team's pipeline to them, every team and `all` for a reports admin, just `mine` otherwise. `period` is the span the dashboard reads; `choices.period` lists them.

Each panel says what it follows of the scope in `follow` (`who`, `period`, both or neither; a panel can keep a scope of its own) and what it was read with in `who` and `period`, or `null` where the panel has no such setting.

## A panel

Every panel carries `item` (its number on the dashboard), `type`, `name` (the kind of panel, as the catalogue names it), `title`, `width`, `follow`, `who`, `period`, `web_url` and a `kind`, which says what else it carries:

| `kind`          | Panel types                                                  | Carries                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| --------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tile`          | the six count and fee tiles                                  | `value` (a number), `display` (as written, `"$8.64M"`), `colour`, `url` (the list behind it), `delta`: `{ "text": "+5 added this quarter", "direction": "up" }` or `null`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `strip`         | Project Pipeline                                             | `statuses`: each `{ status, label, colour, count, sum, weighted, phases: [{ id, name, count, sum, weighted }] }`; `url`. A phase with `id` 0 is the projects on the status with no phase.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `list`          | Projects, Companies, Contacts, Tasks, Meetings, Events lists | `record_type`, `columns`: `[{ key, label, type }]`, `rows`: each `{ id, name, url, record_status, stage_id, stage_name, cells, values }` where `cells` is each column as text and `values` the record's own values; `shown`, `total`, `more_url`. A project with stages lists one row per stage: `id` and `url` are the project's, `stage_id` and `stage_name` the stage's (null on every other row), and the name cell is the name alone. A panel set to list a saved [table view](https://docs.tiny.plus/api/endpoints/table-views.md) also carries `view`, its `{ id, name }`, and its `more_url` opens the table on that view. Where the view has been deleted or isn't shared with the person, `rows` is empty, `view` is `null` and `note` says so in a sentence. |
| `items`         | Meetings & tasks                                             | `kinds`, `to_do`, `late`, `meetings`, `shown`, `total`, `items`: each `{ type: "activities" or "meetings", id, name, status, due, start, end, late, url, on, with, for, plan, may: { status, due_date } }`. Complete a task with [`PATCH /v2/activities/{id}`](https://docs.tiny.plus/api/endpoints/tasks.md) and `record_status: completed`, then read the panel again.                                                                                                                                                                                                                                                                                                                                                                                                |
| `attention`     | Needs attention, People to contact                           | `days`, `groups`: each `{ label, rows: [{ id, type, name, why, amount, url, plan }] }`. People to contact (`type: "people_to_contact"`) is the top of the [Connect](https://docs.tiny.plus/api/endpoints/connect.md) board: `days` is `null`; it adds `people`, `late` and `url`; a group adds its column's `key` and `count` (everyone in it, where `rows` holds the panel's limit); and a row is a contact, with `tone`, `also`, `job_title`, `company`, `last` and `task_id` as a card has them.                                                                                                                                                                                                                                                                     |
| `dates`         | Key dates                                                    | `period_words`, `shown`, `total`, `rows`: each `{ day, label, id, type, name, under, url }`, sorted by day.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `lists`         | Lists                                                        | `which`, `rows`: each `{ id, name, type, target, count, words, on_plan, url }`; `on_plan` is how many of a target list's companies are on a plan, or `null`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `feed`          | News feed                                                    | `feed` (`following` or `home`), `posts`: each `{ id, created_date, type, poster, text, record, url }`. `created_date` is the stored UTC stamp, as a record's is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `note`          | Note                                                         | `text` as typed, `html` as the web draws it (links and the feed's codes).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `heading`       | Title Block                                                  | `subtitle`. The heading itself is `title`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `launch`        | Launcher                                                     | `text`, `url`, `style` (`standard` or `solid`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `plans`         | Relationship Plans                                           | `available`, `rows`: each `{ id, name, status, company, next, health, label }`, `more_url`. `health` is `late`, `soon`, `ok`, `paused` or `none`, with `label` as its words; `company.url` is the company's page.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `history`       | Pipeline History                                             | `period_type`, `periods`: each `{ period, label, won_sum, lost_sum, won_count, lost_count, won_sum_percent, won_count_percent }`. The sums are written as money.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `forecast`      | Budget Forecaster                                            | `period_type`, `budget`, `periods`: each `{ period, label, projects, total, budget_percent, colour }`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `calendar`      | Calendar                                                     | `month`, `items`: each `{ id, type, name, date, end, status, url }` for the month.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `email_reports` | Email Reports                                                | `rows`: each `{ id, name, sent, url }`, `more_url`. `sent` is a UTC stamp in the same shape as `created_date`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `chart_report`  | Report Chart                                                 | `report_id`, `report_name`, `url`: the report's page. The chart itself is drawn on the web.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `web`           | anything else                                                | Nothing: open `web_url` on the web.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

`url`s are paths on the web app unless they are absolute.

## One panel again

<mark style="color:blue;">`GET`</mark> `https://api.tiny.plus/v2/dashboards/{id}/panel/{item}`

One panel, as a row's entry above, taking the same `who`, `period` and `month`. For redrawing a panel after a change, such as completing a task, without reading the whole dashboard. `404` for a panel that isn't there.

## Keeping the scope

<mark style="color:green;">`POST`</mark> `https://api.tiny.plus/v2/dashboards/{id}/scope`

| Parameter | Description                        |
| --------- | ---------------------------------- |
| `who`     | A key from `scope.choices.who`.    |
| `period`  | A key from `scope.choices.period`. |

Keeps the choice for the token's user on that dashboard, as the web's chips do; where they may edit the dashboard, it also becomes the dashboard's default for everyone else. Either may be left out. Answers `{ "scope": { "who": "...", "period": "..." } }`. A key that isn't one of the choices is refused with `400`.

## Errors

| Code  | When                                                                                                             |
| ----- | ---------------------------------------------------------------------------------------------------------------- |
| `400` | An id that isn't one, a panel number that isn't one, a `who` or `period` that isn't a choice.                    |
| `404` | A dashboard the person can't see, or a panel that isn't on it.                                                   |
| `405` | Anything but `GET` on a dashboard or panel, or anything but `POST` on `scope`: dashboards are edited on the web. |
