Skip to main content
BuyLog In
Report and Dashboard Server
Search in…
Docs > Configuration and API > HTTP API
All docs
V24.2
Report and Dashboard Server
Differences from BI Dashboard and Reporting
License and Distribution
Installation
Administrative Panel
Create Reports
Create Dashboards
Configuration and API
Report and Dashboard Server Authentication
Manage Scheduled Jobs
Specify Timeouts
Configure IIS Bindings
Configure SSL
Scripts
HTTP API
Display Documents from the Report and Dashboard Server
User-Specific Functions
Localization

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:

  1. Configure the Report and Dashboard Server to use the HTTPS protocol.

  2. Create a user account with Server authentication and give this account the required permissions.

  3. 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:

  1. 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"}

  2. Check the export task’s status:

    $ curl -X GET "https://localhost/api/documents/export/status/ca78996a34e14b3ebef1a8e4c35a4a42" \
--header "Authorization: Bearer <oauth-token>"

{"taskStatus":"Complete"}

  3. 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:

"format": "string", // "png" | "jpeg" | "gif"
"resolution": "integer",

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"
}