Console API

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:

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:

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

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

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

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

Flags

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

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.

Getting started

Building

Using Pult

Reference

Console API

Getting a token

Items

Records

Actions

Pages

Flags

Approvals

Live updates

​Getting a token

​Items

​Records

​Actions

​Pages

​Flags

​Approvals

​Live updates

Getting a token

Items

Records

Actions

Pages

Flags

Approvals

Live updates