Getting started with the REST API

To interact with the IBM® Cognos® Analytics REST API, your client application must perform these tasks:

  • authenticate to the Cognos Analytics server
  • send an X-XSRF-Token request header on all requests except session creation
  • use a session key to create a session


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.

Depending on the authentication provider you are using, the /session endpoint may not allow you to authenticate with a password. In this case, you will need to use an API login key:

  "parameters": [
         "name" : "CAMAPILoginKey",
         "value" :"yourapikey"

Last, 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:


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



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 an XSRF-Token cookie by issuing a GET request to /api/v1/session. For example:

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.

Requests cannot be sent to the external gateway (IIS or Apache); otherwise, an extra rewrite rule would be required to handle /api requests.

Using session_key

To avoid using cookies, use the following example to create a session:

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

The JSON response resembles the following:

  "generation": 3,
  "shareable": false,
  "isAnonymous": false,
  "logEnabled": false,
  "canCallLogon": true,
  "url": "/api/v1",
  "session_key": "CAM MTsxMDE6OTZlNjI5YzctNzE1OC0wODQ0LWRkYTgtNjY3ZTQ5ZGQ5ZDE0OjEzMDY0NjI5NzY7MDszOzE7"

You can then use the session_key value in all subsequent requests by sending it in a request header. For example: