> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pult.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Console API

> Work Pult's inboxes from your own tools and agents, with the same permissions as the console.

Everything the console does goes through an HTTP API, and agents can use it too. An agent is a token with a role: it sees what the role sees, runs what the role allows, and everything it does is in the history and audit log under its name.

## Getting a token

An admin creates an agent in the project's settings, under Agents, picks its role and copies the token, which is shown once. The same page shows the address of the current environment's API:

```
https://app.pult.sh/api/env/<environment>
```

Send the token as a bearer token:

```bash theme={null}
curl https://app.pult.sh/api/env/$ENVIRONMENT/items?inbox=reports \
  -H "authorization: Bearer $PULT_AGENT_TOKEN"
```

Bodies are JSON. Errors come back with a status code and `{ "error": "..." }`, and some with a `code`.

## Items

`GET /items` lists items, newest activity first, 50 at a time:

| Query | Meaning |
| - | - |
| `inbox` | One inbox. Without it, every inbox the role sees. |
| `view` | A view defined in code. |
| `state` | Comma-separated states. |
| `tags` | Comma-separated tags, all required. |
| `assignee` | `none` or a person's id. |
| `search` | Words in the title. |
| `overdue=1` | Only items past their response time. |
| `triaged=1` | Only items triage closed. |
| `snoozed=1` | Only snoozed items. |
| `sort` | `lastSeen`, `firstSeen`, `occurrences`, `users`, `title` or `due`, `-` in front for descending. |
| `cursor`, `limit` | Paging. Pass back the `cursor` from the last page; `limit` goes up to 200. |

Each item has `id`, `inbox`, `title`, `state`, `record`, `tags`, `assignee`, `occurrences`, `users`, `firstSeen`, `lastSeen`, `dueAt` and `fields`.

`GET /items/:id` returns one item with its blocks, linked records, suggested actions, triage's answers and timeline.

Changing an item:

```http theme={null}
POST /items/:id/state    { "state": "resolved" }
POST /items/:id/assign   { "assignee": "user-id" }    null unassigns
POST /items/:id/tags     { "add": ["spam"], "remove": [] }
POST /items/:id/snooze   { "until": 1767225600000 }    null wakes it
POST /items/:id/notes    { "text": "Checked the logs, it's the CDN." }
POST /items/:id/reply    { "subject": "Re: ...", "text": "..." }
POST /items              { "inbox": "support", "title": "...", "data": {} }
```

`POST /bulk` changes many at once: `{ "ids": [...], "operation": { "type": "state", "state": "resolved" } }`. Operations are `state`, `assign`, `tags`, `snooze` and `action`.

## Records

```http theme={null}
GET  /resources/:resource?q=lena                 search
GET  /resources/:resource/list?q=&filters={}     browse, with a cursor
GET  /resources/:resource/:id                    page, items and history
GET  /resources/:resource/:id/related/:relation  related records
```

## Actions

```http theme={null}
POST /actions
{
  "action": "user.restrict",
  "record": "u_42",
  "input": { "features": ["comments"] },
  "item": "the-item-id",
  "confirmed": true
}
```

Leave out `record` for actions that don't take one. `item` is optional and records the action on that item's timeline. Actions with a danger level need `"confirmed": true`. Actions that need a fresh sign-in can't be run by agents; actions that need approval return `{ "pending": true }` and wait under Approvals for a person.

The response is the action's result: `{ "message": "...", "blocks": [...] }`, `{ "queued": true }` if your app is offline, or `{ "running": true }` for background actions.

`POST /available` with `{ "refs": [{ "resource": "user", "id": "u_42" }] }` says which actions apply to those records right now, and their defaults.

## Pages

```http theme={null}
GET /pages/:page?params={"days":"7"}    its blocks, with live data
```

## Flags

```http theme={null}
GET  /flags          every flag's value, rollout and overrides
POST /flags/:flag    { "change": { "value": true }, "confirmed": true }
```

A change can set `value`, `rollout` (a percentage, for on and off flags, or `null`), `targets` (values by record id), `rules`, and `ramp`: `{ "to": 100, "over": 86400000, "every": 3600000, "at": null }`, with durations and times in milliseconds, or `null` to stop one. Flags that need approval return `{ "pending": true }`.

## Approvals

```http theme={null}
GET  /approvals                 pending requests
POST /approvals/:id/approve
POST /approvals/:id/reject
```

## Live updates

`GET /live` upgrades to a WebSocket that streams item changes, timeline events, flag changes and counts for everything the role can see, as JSON messages with a `type`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.