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 |