Skip to main content
GET
cURL

Authorizations

X-Session-Token
string
header
required

Session token for authentication.

Query Parameters

filter
string
required

Selects the permits the figures are computed over. Required, because it carries the organisation.

  • eq(organisation,<uuid>): Required. The organisation whose permits the figures cover. Exactly one.
  • eq(id,<uuid>) / in(id,[<uuid>,…]): filter by permit id
  • eq(source_permit.reference,<ref>) / in(source_permit.reference,[…]): filter by the Street Manager work reference
  • in(source_permit.status,[granted,closed,…]): filter by permit status
  • in(source_permit.work_status,[planned,completed,…]): filter by work status
  • in(risk.status,[low,medium,high,none]): filter by the permit's stored risk band
  • not(…): negates the term it wraps, so not(in(source_permit.status,[closed,cancelled])) excludes those statuses

Terms are comma separated and combine with AND. The field names are the permit resource's own, so a nested field is dotted: source_permit.status is the state of the permit, source_permit.work_status the state of the works. The two are independent, and either being terminal means the permit carries no risk.

Note that risk.status filters on each permit's stored band, which is written nightly, whereas bands in the response is evaluated at read time. Combining the two asks for "permits whose band was X last night, banded as they are now".

assigned_to_me is not offered here. It takes its value from the caller rather than the query, so it has no expression in this syntax; use the permits list for it.

For more information on filtering, see the docs

Example:

"eq(organisation,b951325b-d02a-43f5-ba7f-c08c62ec52e4)"

horizon
integer
default:30

How many days ahead the expiry series should cover. Permits ending beyond it are still counted in the bands and the status counts; they just have no place on the chart.

Required range: 1 <= x <= 365

Response

The aggregate permit risk figures for the organisation.

JSON API response object

data
object
required

The aggregate view of an organisation's permit risk. A synthetic, read-only resource: it is computed from the permits the caller can see, never stored, and its identifier is the organisation the figures were computed for.

Every figure is derived from the same set of permits in the same read, so the band counts, the expiry series and the status counts always agree with each other. Risk bands are evaluated at read time rather than read from each permit's stored band, so a permit whose status changed since the nightly recalculation is banded on what it is now.

jsonapi
object
required