HTTP API
- 10 minutes to read
The Report and Dashboard Server exposes an HTTP API that you can use to communicate with the server from your application’s code. This document describes how to use this HTTP API in an application and lists the available API endpoints.
Authentication
To use the Report and Dashboard Server’s HTTP API, you first need to obtain an authentication token that you should then attach to all API requests. To obtain the token, do the following:
Configure the Report and Dashboard Server to use the HTTPS protocol.
Create a user account with Server authentication and give this account the required permissions.
Send the following POST request to the server to obtain a Bearer token required to access the Report and Dashboard Server’s API:
$ curl -d "grant_type=password&username=your_username&password=your_password" https://localhost/oauth/token
{"access_token":<oauth-token>, "token_type":"bearer","expires_in":1199}
Starting with the version 19.1.5, you can use the guest account with a blank password to obtain a token.
To attach the obtained token to an API request, add the following HTTP header to the request:
Authorization : Bearer <oauth-token>
Example
Use the following API requests to export a report to PDF and download the resulting document:
Initiate an export task:
$ curl https://localhost/api/documents/export/report/10 \ --header "Content-Type: application/json" \ --header "Authorization: Bearer <oauth-token>" \ --data \ ' { exportOptions: { exportFormat:"pdf" }, documentParameters: [ { name:"CustomerID", value:15 } ] } ' {"exportId":"a60f409c5bf744ec86d537ef971c289f"}Check the export task’s status:
$ curl -X GET "https://localhost/api/documents/export/status/ca78996a34e14b3ebef1a8e4c35a4a42" \ --header "Authorization: Bearer <oauth-token>" {"taskStatus":"Complete"}Download the exported document:
$ curl -X GET "https://localhost/api/documents/export/result/ca78996a34e14b3ebef1a8e4c35a4a42" \ --header "Authorization: Bearer <oauth-token>" -o "report.pdf"
API List
Manage Categories
Use these API endpoints to manage document categories.
Create Category
post /api/categories
{
"optimisticLock": "integer",
"name": "string"
}
Delete Category
delete /api/categories
id: integer (query)
Get Category
get /api/categories/{id}
id: integer (path)
Get All Categories
get /api/categories
Modify Category
put /api/categories
{
"optimisticLock": "integer",
"name": "string"
}
Manage Data Models
Use these API endpoints to configure data models.
Add Data Model Custom SQL Query
post /api/datamodels/{id}/customsqlquery
{
"optimisticLock": "integer",
"name": "string",
"query": "string",
"parameters": [
{
"name": "string",
"type": "string",
"value": "string",
"isNull": "boolean"
}
]
}
Create Data Model
post /api/datamodels/
{
"name": "string",
"description": "string",
"commandTimeout": "integer",
"providerModel": {
"providerType": "string",
<provider-specific options>
}
}
The ProviderModel option specifies the provider type and provider-specific options:
"authenticationType": "string", // "windows" | "sqlServer"
"serverName": "string",
"userName": "string",
"password": "string",
"database": "string",
"additionalParameters": "string"
In addition to the data providers listed above, you can use any database system that supports XPO:
- “advantage”
- “amazon redshift”
- “firebird”
- “bigQuery”
- “db2”
- “access2007”
- “access97”
- “msSqlServerCE”
- “pervasive”
- “asa”
- “sqLite”
- “vistaDB”
- “vistaDB5”
- “vistaDB6”
- “inMemoryDataSource”
These data providers do not have provider-specific options. Use the providerModel.connectionString option to specify connection settings. For more information on the supported data providers, refer to Database Systems Supported by XPO.
Delete Data Model
delete /api/datamodels/{id}
id: integer (path)
Get All Data Models
get /api/datamodels
Get Data Model Connection Provider
get /api/datamodels/{id}/connection
id: integer (path)
Get Data Model Custom SQL Query
get /api/datamodels/{id}/customsqlquery/{name}
id: integer (path)
name: string (path)
Get Data Model Data Members
get /api/datamodels/{id}/datamembers
id: integer (path)
Get Data Model Procedure Schema
get /api/datamodels/{id}/procedures/{procedureName}/columns
id: integer (path)
procedureName: string (path)
Get Data Model Queries
get /api/datamodels/{id}/queries
id: integer (path)
Get Data Model Stored Procedures
get /api/datamodels/{id}/procedures
id: integer (path)
Get Data Module Table Columns
get /api/datamodels/{id}/tables/{tableName}/columns
id: integer (path)
tableName: string (path)
Get Data Model Tables and Views
get /api/datamodels/{id}/tables
id: integer (path)
Modify Data Model Tables and Views
put /api/datamodels/{id}/tables
{
"optimisticLock": "integer",
"tables": [
{
"optimisticLock": "integer",
"name": "string",
"nonEscapedName": "string",
"checked": "boolean",
"columns": [
{
"name": "string",
"checked": "boolean"
}
]
}
]
}
Modify Data Model
put /api/datamodels/{id}
{
"optimisticLock": "integer",
"name": "string",
"description": "string",
"commandTimeout": "integer",
"providerModel": {
"providerType": "string",
<provider-specific options>
}
}
The ProviderModel option specifies the provider type and provider-specific options:
"authenticationType": "string", // "windows" | "sqlServer"
"serverName": "string",
"userName": "string",
"password": "string",
"database": "string",
"additionalParameters": "string"
In addition to the data providers listed above, you can use any database system that supports XPO:
- “advantage”
- “amazon redshift”
- “firebird”
- “bigQuery”
- “db2”
- “access2007”
- “access97”
- “msSqlServerCE”
- “pervasive”
- “asa”
- “sqLite”
- “vistaDB”
- “vistaDB5”
- “vistaDB6”
- “inMemoryDataSource”
These data providers do not have provider-specific options. Use the providerModel.connectionString option to specify connection settings. For more information on the supported data providers, refer to Database Systems Supported by XPO.
Rename Data Model
put /api/datamodels/{id}/rename
{
"optimisticLock": "integer",
"name": "string"
}
Update data model Custom SQL Query
put /api/datamodels/{id}/customsqlquery/{name}
{
"optimisticLock": "integer",
"name": "string",
"query": "string",
"parameters": [
{
"name": "string",
"type": "string",
"value": "string",
"isNull": "boolean"
}
]
}
Manage Documents
Use these API endpoints to manage dashboards, reports and report documents.
Create Document
post /api/documents
{
"categoryId": "integer",
"name": "string",
"description": "string",
"revisionComment": "string",
"documentType": "string",
"autoRefreshInterval": "integer",
"layout": "string"
}
The DocumentType option accepts the following values:
- “report”
- “dashboard”
Delete Document
delete /api/documents
Download Exported Document
get /api/documents/export/result/{exportId}
exportId: string (path)
Export Dashboard
post /api/documents/export/dashboard/{documentId}
{
"exportOptions": {
"exportFormat": "string",
"exportParameters": "boolean"
<format-specific options>
},
"documentParameters": [
{
"name": "string"
}
]
}
The ExportFormat option accepts the following values:
- “pdf”,
- “image”,
- “xlsx”
Depending on the export format, you can provide the following format-specific export options:
The Export Dashboard task returns the resulting document or an error.
Export Report
post /api/documents/export/report/{documentId}
{
"exportOptions": {
"exportFormat": "string",
<format-specific options>
},
"documentParameters": [
{
"Name": "string"
}
]
}
The exportFormat option accepts the following values:
- “pdf”
- “html”
- “xlsx”
- “docx”
Depending on the export format, you can provide the following format-specific export options:
"exportMode": "string", // "singleFile" | "singleFilePageByPage"
"tableLayout": "boolean",
"keepRowHeight": "boolean"
The Export Report task returns the export task identifier (exportId).
Get Generated Documents
get /api/documents/{id}/jobresults
id: integer (path)
Get Document
get /api/documents/{id}
id: integer (path)
Get All Documents
get /api/documents
Get Document Export Status
get /api/documents/export/status/{exportId}
exportId: string (path)
Get Document Layout
get /api/documents/{id}/layout
id: integer
Get Document Layout’s Revision
get /api/documents/{id}/revisionLayout/{revisionId}
id: integer (path)
revisionId: integer (path)
Get Document Revisions
get /api/documents/{id}/revisions
id: integer (path)
Save Document
put /api/documents/{id}/save
{
"optimisticLock": "integer",
"autoRefreshInterval": "integer",
"revisionComment": "string",
"layout": "string"
}
Update Document
put /api/documents
{
"optimisticLock": "integer",
"categoryId": "integer",
"name": "string",
"description": "string"
}
Manage Jobs
Use these API endpoints to manage document generation jobs.
Create Job
post /api/jobs
{
"optimisticLock": "integer",
"name": "string",
"mode": "string",
"documentId": "integer",
"retentionPeriod": "integer",
"enabled": "boolean",
"startDate": "string",
"timeZone": "string",
"recurrenceRule": "string",
"parameters": [
{
"name": "string",
"source": "string",
"value": any
}
],
"billingStatementBinding": {
"dataModelId": "integer",
"dataMember": "string",
"emailAddressField": "string",
"emailRecipientField": "string"
},
"emailDeliveryFormat": "string",
"sendIndividualEmails": "boolean",
"sendBlankDocument": "boolean",
"subscribedEmails": [
"string"
],
"sharedFolders": [
"string"
],
"internalSubscriberIds": [
"integer"
]
}
The following options require only allowed values:
| Option Name | Allowed Values |
|---|---|
| mode | “document”, “billingStatement” |
| parameters.source | “static”, “calculated”, “bound” |
| emailDeliveryFormat | “url”, “pdf”, “excel”, “html” |
| timeZone | the IANA Time Zone Database time zone identifier |
Delete Job
delete /api/jobs/
id: integer (query)
Execute Job
post /api/jobs/{id}/execute
id: integer (query)
Get Documents Generated by the Job
get /api/jobs/{id}/jobresults
id: integer (path)
startDate: string (query)
endDate: string (query)
Get a Generated Document
/api/jobs/generateddocuments/{generatedDocumentId}/export
generatedDocumentId: string (path)
Get Job
get /api/jobs/{id}
id: integer (path)
Get All Jobs
get /api/jobs
Update Job
put /api/jobs
{
"optimisticLock": "integer",
"name": "string",
"mode": "string",
"documentId": "integer",
"retentionPeriod": "integer",
"enabled": "boolean",
"startDate": "string",
"timeZone": "string",
"recurrenceRule": "string",
"parameters": [
{
"name": "string",
"source": "string",
"value": any
}
],
"billingStatementBinding": {
"dataModelId": "integer",
"dataMember": "string",
"emailAddressField": "string",
"emailRecipientField": "string"
},
"emailDeliveryFormat": "string",
"sendIndividualEmails": "boolean",
"sendBlankDocument": "boolean",
"subscribedEmails": [
"string"
],
"sharedFolders": [
"string"
],
"internalSubscriberIds": [
"integer"
]
}
The following options require enumeration values:
| Option Name | Allowed Values |
|---|---|
| mode | “document”, “billingStatement” |
| parameters.source | “static”, “calculated”, “bound” |
| emailDeliveryFormat | “url”, “pdf”, “excel”, “html” |
| timeZone | the IANA Time Zone Database time zone identifier |
Manage Users
Use these API endpoints to manage users, user groups and their permissions.
Add Group
post /api/usergroups
{
"name": "string"
}
Add Group Permissions
post /api/usergroups/{id}/permissions
{
"optimisticLock": "integer",
"permissions": [
{
"accessMode": "integer",
"scope": "string",
"entityId": "integer"
}
]
}
The AccessMode option is a bitmask that supports the following values:
create = 1 << 0,
read = 1 << 1,
modify = 1 << 2,
delete = 1 << 3
The Scope option accepts the following values:
- “allCategories”
- “category”
- “allDocuments”
- “documentsInCategory”
- “document”
- “allDataModels”
- “dataModel”
- “allScheduledJobs”
- “scheduledJob”
Delete Group
delete /api/usergroups/{id}
{
"optimisticLock": "integer",
"permissions": [
"integer"
]
}
Delete Group Permissions
post /api/usergroups/{id}/permissions/delete
id: integer (path)
Get Groups
get /api/usergroups
Get Group Permissions
get /api/usergroups/{id}/permissions
id: integer (path)
Modify User Group
put /api/usergroups/{id}
{
"optimisticLock": "integer",
"name": "string"
}
Add User Permissions
post /api/users/{id}/permissions
{
"optimisticLock": "integer",
"permissions": [
{
"accessMode": "integer",
"scope": "string",
"entityId": "integer"
}
]
}
The AccessMode option is a bitmask that supports the following values:
create = 1 << 0,
read = 1 << 1,
modify = 1 << 2,
delete = 1 << 3
The Scope option accepts the following values:
- “allCategories”
- “category”
- “allDocuments”
- “documentsInCategory”
- “document”
- “allDataModels”
- “dataModel”
- “allScheduledJobs”
- “scheduledJob”
Add User
post /api/users
{
"userName": "string",
"firstName": "string",
"lastName": "string",
"email": "string",
"groupsId": "number[]",
"accountType": "string"
}
The accountType option accepts the following values:
- “reportServer”
- “windows”
- “external”
Delete User
delete /api/users/{id}
id: integer (path)
Delete User Permissions
post /api/users/{id}/permissions/delete
{
"optimisticLock": "integer",
"permissions": [
{
"accessMode": "integer",
"scope": "string",
"entityId": "integer"
}
]
}
The AccessMode option is a bitmask that supports the following values:
create = 1 << 0,
read = 1 << 1,
modify = 1 << 2,
delete = 1 << 3
The Scope option accepts the following values:
- “allCategories”
- “category”
- “allDocuments”
- “documentsInCategory”
- “document”
- “allDataModels”
- “dataModel”
- “allScheduledJobs”
- “scheduledJob”
Get User
get /api/users
Get User Photo
get /api/users/{id}/photo
id: integer (path)
Get All User Permissions
get /api/users/{id}/permissions
id: integer (path)
Modify a User
put /api/users/{id}
{
"optimisticLock": "integer",
"firstName": "string",
"lastName": "string",
"email": "string",
"groupsId": [
"integer"
],
"active": "boolean"
}