This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.

Reports: what can be queried, and the jobs that run a query.

The reports API. Every operation takes an access token for this realm’s /report-api carrying report:use or report:admin — the public client sts-report’s, DPoP-bound and sent as Authorization: DPoP, or an application’s own (client_credentials) where the application is a member of REPORT_USE or REPORT_ADMIN and declares the scope. The scopes are the permissions of those two roles; the access-control policy decides every definition and job: an owner their own, a report administrator every one, a shared group’s member reading and running one shared with them, an application only what it defined. A job id is not an authorization: retrieving a result takes the same token. Paths are after the realm prefix; the default realm has none. The catalog is the field reference. A query names one source. An offset, a second source and a SQL statement are invalid_query. Errors are English. The body never carries an STS-REPORT code.

Every answer is checked against the model shown here before it is sent, and no answer carries a member its model does not list. A member shown as any JSON is one whose shape belongs to somebody else, and says whose. .{key} is a key that is data, and [] an element of a list.

A refusal

Unless an operation below says otherwise, any status it does not list answers this:

Member Type Required What it is
error string    
error_description string    

GET /report-api

The report API index

Names the catalog and realms addresses, and carries the service version the application draws in its footer.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The index.

Member Type Required What it is
catalog string    
realms string    
service string    
version object    
version.buildInfo string    
version.stamped boolean    
version.version string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

GET /report-api/announcements

Announcements for everybody signed in

What an administrator broadcast to this application (#1086) after since — the now this operation answered the tab’s first ask with — within ssf.announcementKeepS, oldest first. With no since it answers only now. everyMs is how often an open tab asks again.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
since query integer    
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: now, everyMs and announcements.

Member Type Required What it is
announcements list    
announcements[].at string    
announcements[].id string    
announcements[].message string    
everyMs number    
now number   This service’s clock, in milliseconds: the since of the next ask.

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

GET /report-api/catalog

The report catalog

Every source. Each field has an id, a meaning, a type, whether it can be filtered, sorted or grouped, and its operators. paging is limit. relationships is empty. retention is the English sentence for how long the rows last.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The sources.

Member Type Required What it is
sources list    
sources[].anchored boolean   True for a source read from the directory (users, credentialHolders): a filter on it has to name a field whose indexed list holds the operator — a leaf of an and, or every arm of an or — or it is refused as invalid_query; the other fields narrow an indexed read.
sources[].bounded boolean    
sources[].fields list    
sources[].fields[].filter boolean    
sources[].fields[].group boolean    
sources[].fields[].id string    
sources[].fields[].indexed list   The operators the directory answers with an index, so a filter using one of them reads only the rows it names. A users query whose filter uses none, with an order or a count, or on a sealed field, reads every person: refused in sync mode (result_too_large), a job in auto mode.
sources[].fields[].indexed[] string    
sources[].fields[].indexedValues list   The values whose equality the index answers, when it answers only some: users status is indexed for locked, and active is everybody else. Absent when every value is answered.
sources[].fields[].indexedValues[] string    
sources[].fields[].meaning string    
sources[].fields[].operators list    
sources[].fields[].operators[] string    
sources[].fields[].sort boolean    
sources[].fields[].type one of string, number, boolean, timestamp    
sources[].fields[].values list   Every value the field can hold, when it is an enumeration; the page draws a dropdown of them for equals and not equals. Absent for an open field.
sources[].fields[].values[] string    
sources[].id one of users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions    
sources[].paging one of limit    
sources[].presets list   Predefined queries (#1110): a name and a whole query document the page offers as a starting point. Data, not a stored definition: nobody owns one and nothing runs it until somebody does.
sources[].presets[].document object    
sources[].presets[].document.aggregate one of count, null    
sources[].presets[].document.format one of json, csv, pdf    
sources[].presets[].document.groupBy list    
sources[].presets[].document.groupBy[] string    
sources[].presets[].document.limit integer    
sources[].presets[].document.locale string   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
sources[].presets[].document.mode one of auto, sync, async    
sources[].presets[].document.orderBy list    
sources[].presets[].document.orderBy[].dir one of asc, desc    
sources[].presets[].document.orderBy[].field string    
sources[].presets[].document.select list   The fields. A count may name none, as three presets do.
sources[].presets[].document.select[] string    
sources[].presets[].document.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
sources[].presets[].document.where object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
sources[].presets[].document.where.arg object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
sources[].presets[].document.where.args list    
sources[].presets[].document.where.args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
sources[].presets[].document.where.field string    
sources[].presets[].document.where.op string    
sources[].presets[].document.where.param string    
sources[].presets[].document.where.value list, or string, or number, or boolean    
sources[].presets[].document.where.value[] object   Nested deeper than this page draws.
sources[].presets[].id string    
sources[].presets[].name string    
sources[].relationships list    
sources[].relationships[] string    
sources[].retention string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

GET /report-api/catalog/{id}

One report source

The same object the catalog lists for one id.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
id path string yes The source id.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The source.

Member Type Required What it is
source object    
source.anchored boolean   True for a source read from the directory (users, credentialHolders): a filter on it has to name a field whose indexed list holds the operator — a leaf of an and, or every arm of an or — or it is refused as invalid_query; the other fields narrow an indexed read.
source.bounded boolean    
source.fields list    
source.fields[].filter boolean    
source.fields[].group boolean    
source.fields[].id string    
source.fields[].indexed list   The operators the directory answers with an index, so a filter using one of them reads only the rows it names. A users query whose filter uses none, with an order or a count, or on a sealed field, reads every person: refused in sync mode (result_too_large), a job in auto mode.
source.fields[].indexed[] string    
source.fields[].indexedValues list   The values whose equality the index answers, when it answers only some: users status is indexed for locked, and active is everybody else. Absent when every value is answered.
source.fields[].indexedValues[] string    
source.fields[].meaning string    
source.fields[].operators list    
source.fields[].operators[] string    
source.fields[].sort boolean    
source.fields[].type one of string, number, boolean, timestamp    
source.fields[].values list   Every value the field can hold, when it is an enumeration; the page draws a dropdown of them for equals and not equals. Absent for an open field.
source.fields[].values[] string    
source.id one of users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions    
source.paging one of limit    
source.presets list   Predefined queries (#1110): a name and a whole query document the page offers as a starting point. Data, not a stored definition: nobody owns one and nothing runs it until somebody does.
source.presets[].document object    
source.presets[].document.aggregate one of count, null    
source.presets[].document.format one of json, csv, pdf    
source.presets[].document.groupBy list    
source.presets[].document.groupBy[] string    
source.presets[].document.limit integer    
source.presets[].document.locale string   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
source.presets[].document.mode one of auto, sync, async    
source.presets[].document.orderBy list    
source.presets[].document.orderBy[].dir one of asc, desc    
source.presets[].document.orderBy[].field string    
source.presets[].document.select list   The fields. A count may name none, as three presets do.
source.presets[].document.select[] string    
source.presets[].document.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
source.presets[].document.where object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
source.presets[].document.where.arg object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
source.presets[].document.where.args list    
source.presets[].document.where.args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
source.presets[].document.where.field string    
source.presets[].document.where.op string    
source.presets[].document.where.param string    
source.presets[].document.where.value list, or string, or number, or boolean    
source.presets[].document.where.value[] string, or number, or boolean    
source.presets[].id string    
source.presets[].name string    
source.relationships list    
source.relationships[] string    
source.retention string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

404: unknown_source.

Member Type Required What it is
error string    
error_description string    

GET /report-api/definitions

List definitions

The caller’s own definitions, those shared with a group the caller belongs to, and every definition when the token has report:admin. In name order, numbered pages: page and per (50 unless given, at most 200); the answer carries page, pages, per and total beside the rows. limit is the older spelling of per, read when per is absent.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
page query integer    
per query integer    
limit query integer   The older spelling of per.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The definitions.

Member Type Required What it is
definitions list    
definitions[].createdAt string, date-time    
definitions[].document object    
definitions[].document.aggregate one of count, null    
definitions[].document.format one of json, csv, pdf    
definitions[].document.groupBy list    
definitions[].document.groupBy[] string    
definitions[].document.limit integer    
definitions[].document.locale string   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
definitions[].document.mode one of auto, sync, async    
definitions[].document.orderBy list    
definitions[].document.orderBy[].dir one of asc, desc    
definitions[].document.orderBy[].field string    
definitions[].document.select list   The fields. A count may name none, as three presets do.
definitions[].document.select[] string    
definitions[].document.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
definitions[].document.where object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
definitions[].document.where.arg object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definitions[].document.where.args list    
definitions[].document.where.args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definitions[].document.where.field string    
definitions[].document.where.op string    
definitions[].document.where.param string    
definitions[].document.where.value list, or string, or number, or boolean    
definitions[].document.where.value[] string, or number, or boolean    
definitions[].editable boolean    
definitions[].failures list    
definitions[].failures[] object   A run a schedule skipped: reportNoteFailure().
definitions[].failures[].at number   When, in milliseconds.
definitions[].failures[].description string    
definitions[].groups list    
definitions[].groups[] string    
definitions[].id string    
definitions[].lastSlotAt string   The most recent occurrence the schedule has taken (queued, or skipped with a note), or null.
definitions[].modifiedAt string, date-time    
definitions[].name string    
definitions[].nextRunAt string   When the enabled schedule next occurs, ISO-8601 UTC; null when it is off or has no occurrence.
definitions[].notify boolean    
definitions[].owner string   The owner’s subject (urn:uuid:…).
definitions[].ownerName string   The owner’s display name, or username; empty for a subject this realm cannot name.
definitions[].parameters map   Parameter name to the value the filter uses. A string, a number, a boolean, null, or a short array of those. Not a nested object. Null where a definition has none.
definitions[].parameters.{key} list, or string, or number, or boolean    
definitions[].parameters.{key}[] string, or number, or boolean    
definitions[].schedule string   A five-field cron expression in UTC, or empty. The application composes it from a date-time and weekday boxes.
definitions[].scheduleEnabled boolean    
page integer    
pages integer    
per integer    
total integer    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

POST /report-api/definitions

Create a definition

Stores the document. parameters is the bag a schedule runs with. A missing value can still be type-checked; it is not stored as a dummy, and the schedule will not run until the value is saved.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

Request body (optional)

Member Type Required What it is
document object yes  
document.aggregate one of count, null    
document.format one of json, csv, pdf    
document.groupBy list    
document.groupBy[] string    
document.limit integer    
document.locale string   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
document.mode one of auto, sync, async    
document.orderBy list    
document.orderBy[].dir one of asc, desc    
document.orderBy[].field string    
document.select list   The fields. A count may name none, as three presets do.
document.select[] string    
document.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
document.where object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
document.where.arg object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
document.where.args list    
document.where.args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
document.where.field string    
document.where.op string    
document.where.param string    
document.where.value list, or string, or number, or boolean    
document.where.value[] string, or number, or boolean    
name string yes  
notify boolean   Mail the owner when a scheduled run finishes. The message links to the job. It does not contain rows.
parameters map   Parameter name to the value the filter uses. A string, a number, a boolean, null, or a short array of those. Not a nested object. Null where a definition has none.
parameters.{key} list, or string, or number, or boolean    
parameters.{key}[] string, or number, or boolean    
schedule string   A UTC cron expression, or empty.
scheduleEnabled boolean    

200: The stored definition.

Member Type Required What it is
definition object    
definition.createdAt string, date-time    
definition.document object    
definition.document.aggregate one of count, null    
definition.document.format one of json, csv, pdf    
definition.document.groupBy list    
definition.document.groupBy[] string    
definition.document.limit integer    
definition.document.locale string   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
definition.document.mode one of auto, sync, async    
definition.document.orderBy list    
definition.document.orderBy[].dir one of asc, desc    
definition.document.orderBy[].field string    
definition.document.select list   The fields. A count may name none, as three presets do.
definition.document.select[] string    
definition.document.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
definition.document.where object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
definition.document.where.arg object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definition.document.where.args list    
definition.document.where.args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definition.document.where.field string    
definition.document.where.op string    
definition.document.where.param string    
definition.document.where.value list, or string, or number, or boolean    
definition.document.where.value[] string, or number, or boolean    
definition.editable boolean    
definition.failures list    
definition.failures[] object   A run a schedule skipped: reportNoteFailure().
definition.failures[].at number   When, in milliseconds.
definition.failures[].description string    
definition.groups list    
definition.groups[] string    
definition.id string    
definition.lastSlotAt string   The most recent occurrence the schedule has taken (queued, or skipped with a note), or null.
definition.modifiedAt string, date-time    
definition.name string    
definition.nextRunAt string   When the enabled schedule next occurs, ISO-8601 UTC; null when it is off or has no occurrence.
definition.notify boolean    
definition.owner string   The owner’s subject (urn:uuid:…).
definition.ownerName string   The owner’s display name, or username; empty for a subject this realm cannot name.
definition.parameters map   Parameter name to the value the filter uses. A string, a number, a boolean, null, or a short array of those. Not a nested object. Null where a definition has none.
definition.parameters.{key} list, or string, or number, or boolean    
definition.parameters.{key}[] string, or number, or boolean    
definition.schedule string   A five-field cron expression in UTC, or empty. The application composes it from a date-time and weekday boxes.
definition.scheduleEnabled boolean    

400: invalid_query.

Member Type Required What it is
error string    
error_description string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

GET /report-api/definitions/{id}

Read a definition

An id the caller may not see is not_found, the same answer as an id that does not exist.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
id path string yes The definition id.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The definition.

Member Type Required What it is
definition object    
definition.createdAt string, date-time    
definition.document object    
definition.document.aggregate one of count, null    
definition.document.format one of json, csv, pdf    
definition.document.groupBy list    
definition.document.groupBy[] string    
definition.document.limit integer    
definition.document.locale string   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
definition.document.mode one of auto, sync, async    
definition.document.orderBy list    
definition.document.orderBy[].dir one of asc, desc    
definition.document.orderBy[].field string    
definition.document.select list   The fields. A count may name none, as three presets do.
definition.document.select[] string    
definition.document.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
definition.document.where object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
definition.document.where.arg object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definition.document.where.args list    
definition.document.where.args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definition.document.where.field string    
definition.document.where.op string    
definition.document.where.param string    
definition.document.where.value list, or string, or number, or boolean    
definition.document.where.value[] string, or number, or boolean    
definition.editable boolean    
definition.failures list    
definition.failures[] object   A run a schedule skipped: reportNoteFailure().
definition.failures[].at number   When, in milliseconds.
definition.failures[].description string    
definition.groups list    
definition.groups[] string    
definition.id string    
definition.lastSlotAt string   The most recent occurrence the schedule has taken (queued, or skipped with a note), or null.
definition.modifiedAt string, date-time    
definition.name string    
definition.nextRunAt string   When the enabled schedule next occurs, ISO-8601 UTC; null when it is off or has no occurrence.
definition.notify boolean    
definition.owner string   The owner’s subject (urn:uuid:…).
definition.ownerName string   The owner’s display name, or username; empty for a subject this realm cannot name.
definition.parameters map   Parameter name to the value the filter uses. A string, a number, a boolean, null, or a short array of those. Not a nested object. Null where a definition has none.
definition.parameters.{key} list, or string, or number, or boolean    
definition.parameters.{key}[] string, or number, or boolean    
definition.schedule string   A five-field cron expression in UTC, or empty. The application composes it from a date-time and weekday boxes.
definition.scheduleEnabled boolean    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

404: not_found.

Member Type Required What it is
error string    
error_description string    

POST /report-api/definitions/{id}

Replace a definition

The owner, or report:admin. parameters omitted keeps the stored bag. parameters null clears it.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
id path string yes The definition id.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

Request body (optional)

Member Type Required What it is
document object yes  
document.aggregate one of count, null    
document.format one of json, csv, pdf    
document.groupBy list    
document.groupBy[] string    
document.limit integer    
document.locale string   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
document.mode one of auto, sync, async    
document.orderBy list    
document.orderBy[].dir one of asc, desc    
document.orderBy[].field string    
document.select list   The fields. A count may name none, as three presets do.
document.select[] string    
document.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
document.where object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
document.where.arg object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
document.where.args list    
document.where.args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
document.where.field string    
document.where.op string    
document.where.param string    
document.where.value list, or string, or number, or boolean    
document.where.value[] string, or number, or boolean    
name string yes  
notify boolean   Mail the owner when a scheduled run finishes. The message links to the job. It does not contain rows.
parameters map   Parameter name to the value the filter uses. A string, a number, a boolean, null, or a short array of those. Not a nested object. Null where a definition has none.
parameters.{key} list, or string, or number, or boolean    
parameters.{key}[] string, or number, or boolean    
schedule string   A UTC cron expression, or empty.
scheduleEnabled boolean    

200: The stored definition.

Member Type Required What it is
definition object    
definition.createdAt string, date-time    
definition.document object    
definition.document.aggregate one of count, null    
definition.document.format one of json, csv, pdf    
definition.document.groupBy list    
definition.document.groupBy[] string    
definition.document.limit integer    
definition.document.locale string   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
definition.document.mode one of auto, sync, async    
definition.document.orderBy list    
definition.document.orderBy[].dir one of asc, desc    
definition.document.orderBy[].field string    
definition.document.select list   The fields. A count may name none, as three presets do.
definition.document.select[] string    
definition.document.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
definition.document.where object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
definition.document.where.arg object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definition.document.where.args list    
definition.document.where.args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definition.document.where.field string    
definition.document.where.op string    
definition.document.where.param string    
definition.document.where.value list, or string, or number, or boolean    
definition.document.where.value[] string, or number, or boolean    
definition.editable boolean    
definition.failures list    
definition.failures[] object   A run a schedule skipped: reportNoteFailure().
definition.failures[].at number   When, in milliseconds.
definition.failures[].description string    
definition.groups list    
definition.groups[] string    
definition.id string    
definition.lastSlotAt string   The most recent occurrence the schedule has taken (queued, or skipped with a note), or null.
definition.modifiedAt string, date-time    
definition.name string    
definition.nextRunAt string   When the enabled schedule next occurs, ISO-8601 UTC; null when it is off or has no occurrence.
definition.notify boolean    
definition.owner string   The owner’s subject (urn:uuid:…).
definition.ownerName string   The owner’s display name, or username; empty for a subject this realm cannot name.
definition.parameters map   Parameter name to the value the filter uses. A string, a number, a boolean, null, or a short array of those. Not a nested object. Null where a definition has none.
definition.parameters.{key} list, or string, or number, or boolean    
definition.parameters.{key}[] string, or number, or boolean    
definition.schedule string   A five-field cron expression in UTC, or empty. The application composes it from a date-time and weekday boxes.
definition.scheduleEnabled boolean    

400: invalid_query.

Member Type Required What it is
error string    
error_description string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

404: not_found.

Member Type Required What it is
error string    
error_description string    

DELETE /report-api/definitions/{id}

Delete a definition

The owner, or report:admin. A share cannot delete.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
id path string yes The definition id.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: Deleted.

Member Type Required What it is
deleted string   The definition’s id.

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

404: not_found.

Member Type Required What it is
error string    
error_description string    

POST /report-api/definitions/{id}/run

Run a saved definition

Always a job. The body is a parameter object, not a query document. A key in the body overrides the stored default. An empty body uses the stored defaults. The stored document already carries locale.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
id path string yes The definition id.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

Request body (optional)

Member Type Required What it is
(the answer) map   Parameter name to the value the filter uses. A string, a number, a boolean, null, or a short array of those. Not a nested object. Null where a definition has none.
.{key} list, or string, or number, or boolean    
.{key}[] string, or number, or boolean    

202: The job.

Member Type Required What it is
job object    
job.byteSize integer    
job.completedAt string    
job.definitionId string    
job.definitionName string    
job.error string   The public error token. A job that exceeded report.asyncMaxMs carries result_too_large. The body of a failed job is not partial.
job.fields list    
job.fields[] string    
job.format string    
job.id string    
job.query object    
job.query.aggregate one of count, null    
job.query.format one of json, csv, pdf    
job.query.groupBy list    
job.query.groupBy[] string    
job.query.limit integer    
job.query.locale string   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
job.query.mode one of auto, sync, async    
job.query.orderBy list    
job.query.orderBy[].dir one of asc, desc    
job.query.orderBy[].field string    
job.query.select list   The fields. A count may name none, as three presets do.
job.query.select[] string    
job.query.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
job.query.where object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
job.query.where.arg object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where.args list    
job.query.where.args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where.field string    
job.query.where.op string    
job.query.where.param string    
job.query.where.value list, or string, or number, or boolean    
job.query.where.value[] string, or number, or boolean    
job.queuedBecause one of every-person, asked, limit, source, run, schedule, null   Why this query is a job: every-person (an auto-mode query whose filter the directory cannot answer from an index, so it has to read every person), asked (mode async, or POST /jobs), limit (auto over report.syncMaxRows), source (a source that cannot be read synchronously), run (a saved definition run by hand) or schedule.
job.source string    
job.status one of queued, running, completed, failed, cancelled, expired    
job.submittedAt string    

400: invalid_query or result_too_large.

Member Type Required What it is
error string    
error_description string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

404: not_found.

Member Type Required What it is
error string    
error_description string    

429: too_many_jobs.

Member Type Required What it is
error string    
error_description string    

POST /report-api/definitions/{id}/share

Share a definition

Replaces the group list. A share can run and retrieve. It cannot edit or delete. Each value is a group DN in this realm.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
id path string yes The definition id.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

Request body (optional)

Member Type Required What it is
groups list yes  
groups[] string    

200: The definition.

Member Type Required What it is
definition object    
definition.createdAt string, date-time    
definition.document object    
definition.document.aggregate one of count, null    
definition.document.format one of json, csv, pdf    
definition.document.groupBy list    
definition.document.groupBy[] string    
definition.document.limit integer    
definition.document.locale string   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
definition.document.mode one of auto, sync, async    
definition.document.orderBy list    
definition.document.orderBy[].dir one of asc, desc    
definition.document.orderBy[].field string    
definition.document.select list   The fields. A count may name none, as three presets do.
definition.document.select[] string    
definition.document.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
definition.document.where object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
definition.document.where.arg object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definition.document.where.args list    
definition.document.where.args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
definition.document.where.field string    
definition.document.where.op string    
definition.document.where.param string    
definition.document.where.value list, or string, or number, or boolean    
definition.document.where.value[] string, or number, or boolean    
definition.editable boolean    
definition.failures list    
definition.failures[] object   A run a schedule skipped: reportNoteFailure().
definition.failures[].at number   When, in milliseconds.
definition.failures[].description string    
definition.groups list    
definition.groups[] string    
definition.id string    
definition.lastSlotAt string   The most recent occurrence the schedule has taken (queued, or skipped with a note), or null.
definition.modifiedAt string, date-time    
definition.name string    
definition.nextRunAt string   When the enabled schedule next occurs, ISO-8601 UTC; null when it is off or has no occurrence.
definition.notify boolean    
definition.owner string   The owner’s subject (urn:uuid:…).
definition.ownerName string   The owner’s display name, or username; empty for a subject this realm cannot name.
definition.parameters map   Parameter name to the value the filter uses. A string, a number, a boolean, null, or a short array of those. Not a nested object. Null where a definition has none.
definition.parameters.{key} list, or string, or number, or boolean    
definition.parameters.{key}[] string, or number, or boolean    
definition.schedule string   A five-field cron expression in UTC, or empty. The application composes it from a date-time and weekday boxes.
definition.scheduleEnabled boolean    

400: invalid_query.

Member Type Required What it is
error string    
error_description string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

404: not_found.

Member Type Required What it is
error string    
error_description string    

GET /report-api/groups

Search the realm’s groups

The groups of this realm whose name or DN contains q (case-insensitive; empty matches every group), five a page in name order, each with its own mail attribute or an empty string. The definition page builds its share list from it; a definition’s groups are who is emailed its result, at that address (#989).

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
q query string    
page query integer    
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: One page of groups.

Member Type Required What it is
groups list    
groups[].dn string    
groups[].mail string   The group’s own address, or empty.
groups[].name string   The cn.
page integer    
pages integer    
per integer    
q string    
total integer    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

GET /report-api/jobs

List jobs

Newest first, in numbered pages: page and per (50 unless given, at most 200), with page, pages, per and total beside the rows. A caller may page by cursor instead: after is the previous page’s next id and limit its size. A job id in the list is not permission to read a job the token cannot see.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
page query integer    
per query integer    
after query string   The last id of the previous page, for a cursor walk; page and per are then ignored.
limit query integer   How many jobs a cursor page returns.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The page. next is null on the last page.

Member Type Required What it is
jobs list    
jobs[].byteSize integer    
jobs[].completedAt string    
jobs[].definitionId string    
jobs[].definitionName string    
jobs[].error string   The public error token. A job that exceeded report.asyncMaxMs carries result_too_large. The body of a failed job is not partial.
jobs[].fields list    
jobs[].fields[] string    
jobs[].format string    
jobs[].id string    
jobs[].query object    
jobs[].query.aggregate one of count, null    
jobs[].query.format one of json, csv, pdf    
jobs[].query.groupBy list    
jobs[].query.groupBy[] string    
jobs[].query.limit integer    
jobs[].query.locale string   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
jobs[].query.mode one of auto, sync, async    
jobs[].query.orderBy list    
jobs[].query.orderBy[].dir one of asc, desc    
jobs[].query.orderBy[].field string    
jobs[].query.select list   The fields. A count may name none, as three presets do.
jobs[].query.select[] string    
jobs[].query.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
jobs[].query.where object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
jobs[].query.where.arg object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
jobs[].query.where.args list    
jobs[].query.where.args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
jobs[].query.where.field string    
jobs[].query.where.op string    
jobs[].query.where.param string    
jobs[].query.where.value list, or string, or number, or boolean    
jobs[].query.where.value[] string, or number, or boolean    
jobs[].queuedBecause one of every-person, asked, limit, source, run, schedule, null   Why this query is a job: every-person (an auto-mode query whose filter the directory cannot answer from an index, so it has to read every person), asked (mode async, or POST /jobs), limit (auto over report.syncMaxRows), source (a source that cannot be read synchronously), run (a saved definition run by hand) or schedule.
jobs[].source string    
jobs[].status one of queued, running, completed, failed, cancelled, expired    
jobs[].submittedAt string    
next string    
page integer   Absent on a cursor page.
pages integer    
per integer    
total integer    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

POST /report-api/jobs

Queue a job

The same document as a query, forced to a job even when it would have fit in one synchronous call.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

Request body (optional)

Member Type Required What it is
aggregate one of count, null    
format one of json, csv, pdf    
groupBy list    
groupBy[] string    
limit integer    
locale string   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
mode one of auto, sync, async    
orderBy list    
orderBy[].dir one of asc, desc    
orderBy[].field string    
select list   The fields. A count may name none, as three presets do.
select[] string    
source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
where object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
where.arg object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
where.args list    
where.args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
where.field string    
where.op string    
where.param string    
where.value list, or string, or number, or boolean    
where.value[] string, or number, or boolean    

202: The job.

Member Type Required What it is
job object    
job.byteSize integer    
job.completedAt string    
job.definitionId string    
job.definitionName string    
job.error string   The public error token. A job that exceeded report.asyncMaxMs carries result_too_large. The body of a failed job is not partial.
job.fields list    
job.fields[] string    
job.format string    
job.id string    
job.query object    
job.query.aggregate one of count, null    
job.query.format one of json, csv, pdf    
job.query.groupBy list    
job.query.groupBy[] string    
job.query.limit integer    
job.query.locale string   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
job.query.mode one of auto, sync, async    
job.query.orderBy list    
job.query.orderBy[].dir one of asc, desc    
job.query.orderBy[].field string    
job.query.select list   The fields. A count may name none, as three presets do.
job.query.select[] string    
job.query.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
job.query.where object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
job.query.where.arg object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where.args list    
job.query.where.args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where.field string    
job.query.where.op string    
job.query.where.param string    
job.query.where.value list, or string, or number, or boolean    
job.query.where.value[] string, or number, or boolean    
job.queuedBecause one of every-person, asked, limit, source, run, schedule, null   Why this query is a job: every-person (an auto-mode query whose filter the directory cannot answer from an index, so it has to read every person), asked (mode async, or POST /jobs), limit (auto over report.syncMaxRows), source (a source that cannot be read synchronously), run (a saved definition run by hand) or schedule.
job.source string    
job.status one of queued, running, completed, failed, cancelled, expired    
job.submittedAt string    

400: invalid_query, unknown_field, unsupported_operation or result_too_large.

Member Type Required What it is
error string    
error_description string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

429: too_many_jobs.

Member Type Required What it is
error string    
error_description string    

GET /report-api/jobs/{id}

Read a job

The owner and report:admin also receive the query document. A hidden id is job_not_found.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
id path string yes The job id.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The job.

Member Type Required What it is
job object    
job.byteSize integer    
job.completedAt string    
job.definitionId string    
job.definitionName string    
job.error string   The public error token. A job that exceeded report.asyncMaxMs carries result_too_large. The body of a failed job is not partial.
job.fields list    
job.fields[] string    
job.format string    
job.id string    
job.query object    
job.query.aggregate one of count, null    
job.query.format one of json, csv, pdf    
job.query.groupBy list    
job.query.groupBy[] string    
job.query.limit integer    
job.query.locale string   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
job.query.mode one of auto, sync, async    
job.query.orderBy list    
job.query.orderBy[].dir one of asc, desc    
job.query.orderBy[].field string    
job.query.select list   The fields. A count may name none, as three presets do.
job.query.select[] string    
job.query.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
job.query.where object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
job.query.where.arg object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where.args list    
job.query.where.args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where.field string    
job.query.where.op string    
job.query.where.param string    
job.query.where.value list, or string, or number, or boolean    
job.query.where.value[] string, or number, or boolean    
job.queuedBecause one of every-person, asked, limit, source, run, schedule, null   Why this query is a job: every-person (an auto-mode query whose filter the directory cannot answer from an index, so it has to read every person), asked (mode async, or POST /jobs), limit (auto over report.syncMaxRows), source (a source that cannot be read synchronously), run (a saved definition run by hand) or schedule.
job.source string    
job.status one of queued, running, completed, failed, cancelled, expired    
job.submittedAt string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

404: job_not_found.

Member Type Required What it is
error string    
error_description string    

POST /report-api/jobs/{id}/cancel

Cancel a job

A queued job becomes cancelled. A running job is asked to stop and is not returned in part.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
id path string yes The job id.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The job.

Member Type Required What it is
job object    
job.byteSize integer    
job.completedAt string    
job.definitionId string    
job.definitionName string    
job.error string   The public error token. A job that exceeded report.asyncMaxMs carries result_too_large. The body of a failed job is not partial.
job.fields list    
job.fields[] string    
job.format string    
job.id string    
job.query object    
job.query.aggregate one of count, null    
job.query.format one of json, csv, pdf    
job.query.groupBy list    
job.query.groupBy[] string    
job.query.limit integer    
job.query.locale string   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
job.query.mode one of auto, sync, async    
job.query.orderBy list    
job.query.orderBy[].dir one of asc, desc    
job.query.orderBy[].field string    
job.query.select list   The fields. A count may name none, as three presets do.
job.query.select[] string    
job.query.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
job.query.where object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
job.query.where.arg object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where.args list    
job.query.where.args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where.field string    
job.query.where.op string    
job.query.where.param string    
job.query.where.value list, or string, or number, or boolean    
job.query.where.value[] string, or number, or boolean    
job.queuedBecause one of every-person, asked, limit, source, run, schedule, null   Why this query is a job: every-person (an auto-mode query whose filter the directory cannot answer from an index, so it has to read every person), asked (mode async, or POST /jobs), limit (auto over report.syncMaxRows), source (a source that cannot be read synchronously), run (a saved definition run by hand) or schedule.
job.source string    
job.status one of queued, running, completed, failed, cancelled, expired    
job.submittedAt string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

404: job_not_found.

Member Type Required What it is
error string    
error_description string    

GET /report-api/jobs/{id}/result

Download a result

The artifact bytes. The media type is the format. A job id is not enough: the token must be allowed to see the job. Past artifact retention the result is gone.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
id path string yes The job id.
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The artifact. JSON, CSV or PDF.

As application/json:

Member Type Required What it is
fields list    
fields[] string    
rows list    
rows[] map   One row: a field’s id to what it holds. The keys are the fields the query selected, and count where it counted.
rows[].{key} list, or string, or number, or boolean    
rows[].{key}[] string, or number, or boolean    
source string    
truncated boolean    

As application/pdf.

As text/csv.

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

404: job_not_found.

Member Type Required What it is
error string    
error_description string    

409: job_not_ready.

Member Type Required What it is
error string    
error_description string    

410: result_expired.

Member Type Required What it is
error string    
error_description string    

GET /report-api/me

What the user menu draws

The path of the signed-in person’s own profile photo on this realm (#719), empty where they have none. It answers only about the token’s person.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: photo.

Member Type Required What it is
photo string   The path of the person’s own photo, or empty.

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

GET /report-api/openapi.json

This document

The description of the released routes.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: This OpenAPI document.

Member Type Required What it is
components any JSON   The operations and components of an OpenAPI document are that specification’s vocabulary, not this API’s, and this document describes itself with them. The operations and components of an OpenAPI document are that specification’s vocabulary, not this API’s, and this document describes itself with them.
info object    
info.description string    
info.title string    
info.version string    
openapi string    
paths any JSON   The operations and components of an OpenAPI document are that specification’s vocabulary, not this API’s, and this document describes itself with them. The operations and components of an OpenAPI document are that specification’s vocabulary, not this API’s, and this document describes itself with them.

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

POST /report-api/queries

Run a query

Synchronous when the source is bounded and the limit fits the sync caps. Otherwise 202 and a job. mode sync over the cap is result_too_large. A body over the byte cap or a sync call over the time cap is refused whole.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

Request body (optional)

Member Type Required What it is
aggregate one of count, null    
format one of json, csv, pdf    
groupBy list    
groupBy[] string    
limit integer    
locale string   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
mode one of auto, sync, async    
orderBy list    
orderBy[].dir one of asc, desc    
orderBy[].field string    
select list   The fields. A count may name none, as three presets do.
select[] string    
source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
where object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
where.arg object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
where.args list    
where.args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
where.field string    
where.op string    
where.param string    
where.value list, or string, or number, or boolean    
where.value[] string, or number, or boolean    

200: The JSON, CSV or PDF body. JSON is an object with rows and truncated false. CSV is RFC 4180. PDF is PDF 1.4.

As application/json:

Member Type Required What it is
fields list    
fields[] string    
rows list    
rows[] map   One row: a field’s id to what it holds. The keys are the fields the query selected, and count where it counted.
rows[].{key} list, or string, or number, or boolean    
rows[].{key}[] string, or number, or boolean    
source string    
truncated boolean    

As application/pdf.

As text/csv.

202: A job was queued.

Member Type Required What it is
job object    
job.byteSize integer    
job.completedAt string    
job.definitionId string    
job.definitionName string    
job.error string   The public error token. A job that exceeded report.asyncMaxMs carries result_too_large. The body of a failed job is not partial.
job.fields list    
job.fields[] string    
job.format string    
job.id string    
job.query object    
job.query.aggregate one of count, null    
job.query.format one of json, csv, pdf    
job.query.groupBy list    
job.query.groupBy[] string    
job.query.limit integer    
job.query.locale string   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
job.query.mode one of auto, sync, async    
job.query.orderBy list    
job.query.orderBy[].dir one of asc, desc    
job.query.orderBy[].field string    
job.query.select list   The fields. A count may name none, as three presets do.
job.query.select[] string    
job.query.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
job.query.where object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
job.query.where.arg object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where.args list    
job.query.where.args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
job.query.where.field string    
job.query.where.op string    
job.query.where.param string    
job.query.where.value list, or string, or number, or boolean    
job.query.where.value[] string, or number, or boolean    
job.queuedBecause one of every-person, asked, limit, source, run, schedule, null   Why this query is a job: every-person (an auto-mode query whose filter the directory cannot answer from an index, so it has to read every person), asked (mode async, or POST /jobs), limit (auto over report.syncMaxRows), source (a source that cannot be read synchronously), run (a saved definition run by hand) or schedule.
job.source string    
job.status one of queued, running, completed, failed, cancelled, expired    
job.submittedAt string    

400: invalid_query, unknown_source is 404, unknown_field, unsupported_operation, unsupported_format or result_too_large.

Member Type Required What it is
error string    
error_description string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

429: too_many_jobs.

Member Type Required What it is
error string    
error_description string    

GET /report-api/realms

The trust realms

The realm this request is in, and every realm with its id, name and path prefix where realms are active (null where they are not). The application draws its realm field and switch from it.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The realms.

Member Type Required What it is
current object    
current.id string    
current.name string    
current.prefix string   The realm’s path prefix; empty for the default realm.
realms list    
realms[].id string    
realms[].name string    
realms[].prefix string   The realm’s path prefix; empty for the default realm.

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string    

GET /report-api/schedules

The scheduled definitions and their runs

Every definition that carries a schedule, with when it next runs, the occurrence it last took, the notes a skipped run left, and its most recent scheduled jobs. A report:use token sees the definitions it owns or is shared; report:admin sees every one in the realm and may name one owner with owner (a urn:uuid subject or a username). A report:use token that names another owner is refused with forbidden (403). Paged; per is at most 100.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
owner query string    
page query integer    
per query integer    
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: The schedules.

Member Type Required What it is
owner string    
page integer    
pages integer    
per integer    
schedules list    
schedules[].definition object    
schedules[].definition.failures list    
schedules[].definition.failures[].at string    
schedules[].definition.failures[].description string    
schedules[].definition.id string    
schedules[].definition.lastSlotAt string    
schedules[].definition.name string    
schedules[].definition.nextRunAt string    
schedules[].definition.notify boolean    
schedules[].definition.owner string    
schedules[].definition.ownerName string    
schedules[].definition.schedule string    
schedules[].definition.scheduleEnabled boolean    
schedules[].jobCount integer   How many scheduled jobs the definition has in all.
schedules[].jobs list   The most recent scheduled jobs, newest first, at most five.
schedules[].jobs[].byteSize integer    
schedules[].jobs[].completedAt string    
schedules[].jobs[].definitionId string    
schedules[].jobs[].definitionName string    
schedules[].jobs[].error string   The public error token. A job that exceeded report.asyncMaxMs carries result_too_large. The body of a failed job is not partial.
schedules[].jobs[].fields list    
schedules[].jobs[].fields[] string    
schedules[].jobs[].format string    
schedules[].jobs[].id string    
schedules[].jobs[].query object    
schedules[].jobs[].query.aggregate one of count, null    
schedules[].jobs[].query.format one of json, csv, pdf    
schedules[].jobs[].query.groupBy list    
schedules[].jobs[].query.groupBy[] string    
schedules[].jobs[].query.limit integer    
schedules[].jobs[].query.locale string   A language tag. Omitted means the PDF chrome is English. The page sends the signed-in user’s language. Filipino and Swedish are drawn. Chinese is named on an English page because the PDF font is WinAnsi.
schedules[].jobs[].query.mode one of auto, sync, async    
schedules[].jobs[].query.orderBy list    
schedules[].jobs[].query.orderBy[].dir one of asc, desc    
schedules[].jobs[].query.orderBy[].field string    
schedules[].jobs[].query.select list   The fields. A count may name none, as three presets do.
schedules[].jobs[].query.select[] string    
schedules[].jobs[].query.source string yes One source, by its id in the catalog: users, groups, applications, federation, authMechanisms, auditEvents, authActivity, serviceMetrics, reportJobs, credentialHolders, attributeSources, postLoginProgress, passkeyHistory, passkeyCeremonies, authzenSubjects, authzenResources, authzenActions. An array is invalid_query.
schedules[].jobs[].query.where object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter.
schedules[].jobs[].query.where.arg object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
schedules[].jobs[].query.where.args list    
schedules[].jobs[].query.where.args[] object   A comparison, or and, or, or not. A comparison names field and either value or param, not both. in takes an array. isNull names only the field. The form offers three comparisons and does not offer in; the API does. Null is no filter. The same shape as the member holding it.
schedules[].jobs[].query.where.field string    
schedules[].jobs[].query.where.op string    
schedules[].jobs[].query.where.param string    
schedules[].jobs[].query.where.value list, or string, or number, or boolean    
schedules[].jobs[].query.where.value[] object   Nested deeper than this page draws.
schedules[].jobs[].queuedBecause one of every-person, asked, limit, source, run, schedule, null   Why this query is a job: every-person (an auto-mode query whose filter the directory cannot answer from an index, so it has to read every person), asked (mode async, or POST /jobs), limit (auto over report.syncMaxRows), source (a source that cannot be read synchronously), run (a saved definition run by hand) or schedule.
schedules[].jobs[].source string    
schedules[].jobs[].status one of queued, running, completed, failed, cancelled, expired    
schedules[].jobs[].submittedAt string    
scope one of mine, realm    
total integer    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: Another owner was named without report:admin.

Member Type Required What it is
error string    
error_description string    

GET /report-api/signals

This application’s Shared Signals inbox

The CAEP and RISC events this application’s own stream delivered in this realm, newest first, twenty a page by default (#1042). report:admin sees every one (scope realm); anybody else sees only the events about themselves (scope own), and an application sees none. Each row says what this application did with it: the sessions it ended and the tokens of its own client it revoked for the person named, or why it did nothing. receiving is false, with why, when nothing can arrive. per is at most 100.

Scope: report:use, report:admin.

Parameters

Name In Type Required What it is
page query integer    
per query integer    
DPoP header string   RFC 9449: the proof of possession for the DPoP-bound access token, which Authorization: DPoP <token> requires.
X-Requested-With header string   Added by an Android WebView, naming the application that hosts the page. This API reads nothing in it.

200: One page of the inbox.

Member Type Required What it is
page integer    
pages integer    
per integer    
receiving boolean    
rows list    
rows[].at string    
rows[].name string    
rows[].reactions list    
rows[].reactions[].ended number    
rows[].reactions[].failed boolean    
rows[].reactions[].observed boolean    
rows[].reactions[].revoked number    
rows[].reactions[].skipped string   Why nothing was done, or empty.
rows[].subject string    
rows[].type string    
rows[].verified boolean    
rows[].vocabulary string    
scope one of realm, own    
total integer    
why list   Why nothing can arrive, where nothing can.
why[] string    

401: invalid_token or invalid_dpop_proof. The code is recorded and is not in the body.

Member Type Required What it is
error string    
error_description string    

403: forbidden or insufficient_scope.

Member Type Required What it is
error string    
error_description string