REST API

IBM® Cognos® Analytics includes REST APIs to perform create, read, update, and delete operations on Cognos Analytics data, in compliance with OData Version 4 (http://www.odata.org/documentation).

The OData standard defines a set of rules and guidelines that are derived from common web technologies that include HTTP, REST, XML, and JSON. The OData standard provides a rich, interactive interface to data that can be accessed by any OData-compliant HTTP application.

Full descriptions of available endpoints are available in the REST API reference section or from your Cognos Analytics instance at the following URL:

http://<cognos_analytics_server>:<port>/api/api-docs

The reference documentation in Knowledge Center remains static, while the api/api-docs references offers an interactive experience using your data. Use the Try it out button on each endpoint to perform actions.

Note: REST clients MUST send an X-XSRF-Token request header on all requests except session creation. Set the value to the value returned in the XSRF-Token cookie. You can obtain a XSRF-Token cookie by issuing a GET request to /api/v1/session. For example,

xsrf=`grep XSRF cookie.txt | awk '{print $7}'`
curl -b cookie.txt -k -H "x-xsrf-token: ${xsrf}" "https://my.caserver:9300/api/v1/content"

where -b sends the cookies. You can optionally use the -c option to generate a cookie.txtfile. Including both options sends the cookies and saves any new ones that are returned.

Before using the REST APIs, your client application must authenticate to the Cognos Analytics server by issuing a PUT https://<cognos_analytics_server>/api/v1/session request with credentials specified in the body object. For example:

{
  "parameters": [
    {
      "name": "CAMNamespace",
      "value": "LDAP"
    },
    {
      "name": "CAMUsername",
      "value": "johnsmith"
    },
    {
      "name": "CAMPassword",
      "value": "mypassword"
    }
  ]
}

Note: Parameter name-value pairs are case-sensitive.

The /session endpoint may not allow you to authenticate if you're using an alternative authentication provider. If your IdP supports password grants and you set up the namespace accordingly, you can authenticate using PUT to the /session endpoint. To learn how to provision an App ID service, on IBM Cloud, as a generic OIDC namespace with password grant, see Administration: Cognos Analytics Authentication with IBM Cloud AppID . Lastly, you can optionally use the APIs with anonymous login by issuing a GET https://<cognos_analytics_server>/api/v1/session request.

The base URL for all endpoints is api/v1. For example, to GET a list of imported files using the /files endpoint, you can issue the following request:

https://<cognos_analytics_server>/api/v1/files

or update your data modules by issuing a PUT command to:

https://<cognos_analytics_server>/api/v1/modules/{moduleid}