What can we help you with?

e.g. Getting Started, Build Dashboards

Top

Reports

Follow

 

List Reports

This endpoint returns a listing of all reports

GET /api/1.0/reports

No parameters
HTTP StatusResponse
200 OK

Output example:

{
  "list": [
    {
      "createdDate": 1648071581000,
      "lastModDate": null,
      "id": 72,
      "scheduleId": 95,
      "userId": 10077,
      "status": 1,
      "name": "rep2022-03-22-17-11",
      "text": "Email report

Knowi Team
support@knowi.com",
      "token": null,
      "schedule": {
        "frequencyType": "days",
        "frequency": 1,
        "startTime": null,
        "cronConfig": "0 0 */1 * *",
        "id": 95,
        "type": 0,
        "host": null,
        "createdDate": null,
        "lastModDate": null,
        "sync": 0,
        "nextExecutionEpoch": 0,
        "nextExecutionTime": null
      },
      "executionReport": null,
      "accessLevel": 1,
      "timeZone": null,
      "reportType": "REPORT",
      "properties": {
        "dashboards": [
          {
            "id": 111012
          }
        ],
        "subject": "subj1",
        "sendTo": [
          "some@some.com"
        ],
        "reportAs": 10222,
        "reportContentFilters": [
          {
            "fieldName": "param1",
            "values": [
              "val1"
            ],
            "operator": "Equals",
            "type": "java.lang.String",
            "enabled": true,
            "visible": true,
            "transientFilter": false,
            "fieldType": "java.lang.String"
          },
          {
            "fieldName": "param2",
            "values": [
              "val2"
            ],
            "operator": "Equals",
            "type": "java.lang.String",
            "enabled": true,
            "visible": true,
            "transientFilter": false,
            "fieldType": "java.lang.String"
          }
        ]
      }
    }
  ]
}
400 BAD_REQUEST
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:

  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
401 UNAUTHORIZED
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:

  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN
{ "message": <Error details>, "documentation_url": <Documentation link> }


Error details:

  • Current user is not allowed to see the list of reports
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X GET http://localhost:9090/api/1.0/reports

 

View Reports

This endpoint returns report details for a given report id

GET /api/1.0/reports/<objectId>

ParameterComments
objectIdReport id to view Report
HTTP StatusResponse
200 OK

Output example:

{
  "createdDate": 1648071581000,
  "lastModDate": null,
  "id": 72,
  "scheduleId": 95,
  "userId": 10077,
  "status": 1,
  "name": "rep2022-03-22-17-11",
  "text": "Email report

Knowi Team
support@knowi.com",
  "token": null,
  "schedule": {
    "frequencyType": "days",
    "frequency": 1,
    "startTime": null,
    "cronConfig": "0 0 */1 * *",
    "id": 95,
    "type": 0,
    "host": null,
    "createdDate": null,
    "lastModDate": null,
    "sync": 0,
    "nextExecutionEpoch": 0,
    "nextExecutionTime": null
  },
  "executionReport": null,
  "accessLevel": 1,
  "timeZone": null,
  "reportType": "REPORT",
  "properties": {
    "dashboards": [
      {
        "id": 111012
      }
    ],
    "subject": "subj1",
    "sendTo": [
      "some@some.com"
    ],
    "reportAs": 10222,
    "reportContentFilters": [
      {
        "fieldName": "param1",
        "values": [
          "val1"
        ],
        "operator": "Equals",
        "type": "java.lang.String",
        "enabled": true,
        "visible": true,
        "transientFilter": false,
        "fieldType": "java.lang.String"
      },
      {
        "fieldName": "param2",
        "values": [
          "val2"
        ],
        "operator": "Equals",
        "type": "java.lang.String",
        "enabled": true,
        "visible": true,
        "transientFilter": false,
        "fieldType": "java.lang.String"
      }
    ]
  }
}
400 BAD_REQUEST
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:

  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
401 UNAUTHORIZED
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:

  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN
{ "message": <Error details>, "documentation_url": <Documentation link> }


Error details:

  • Current user is not allowed to access specified report
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X GET http://localhost:9090/api/1.0/reports/70

 

Create Report

This endpoint is for creating a new report

POST /api/1.0/reports/

No parameters

POST JSON payload:

 

Sample with "Run As" (reportAs field is id of other user), and with content filters (reportContentFilters field).

      {
        "startTime": null,
        "frequency": 1,
        "frequencyType": "days",
        "subject": "subj1",
        "name": "rep2022-03-22-17-11",
        "text": "Email report

Knowi Team
support@knowi.com",
        "from": null,
        "sendTo": "some@some.com",
        "cc": null,
        "bcc": null,
        "dashIds": [
          111012
        ],
        "datasets": "[]",
        "reportAs": 10222,
        "scheduleId": 90,
        "reportContentFilters": "[{\"fieldName\":\"param1\",\"type\":\"java.lang.String\",\"values\":[\"val1\"],\"operator\":\"Equals\"},{\"fieldName\":\"param2\",\"type\":\"java.lang.String\",\"values\":[\"val2\"],\"operator\":\"Equals\"}]",
        "webhooks": [],
        "slacks": [],
        "teams": [],
        "executionReport": null,
        "nlpQuery": null,
        "contextPath": null,
        "nlpDatasetId": null,
        "datasetReports": null,
        "reportContentFiltersArr": null,
        "dashboards": null,
        "testRun": false
      }
HTTP StatusResponse
200 OKOutput created entity
400 BAD REQUEST
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:

  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
401 UNAUTHORIZED
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:

  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN
{ "message": <Error details>, "documentation_url": <Documentation link> }


Error details:

  • Current user is not allowed to create a report
  • Current user is not allowed to access specified dataset
  • Current user is not allowed to access specified dashboard
  • Not authorized to access an asset
  • Authorization exception: {exception details}
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X POST -d '{"startTime":null,"frequency":1,"frequencyType":"days","subject":"subj1","name":"rep2022-03-22-17-11","text":"<span>Email report</span><br><br>Knowi Team<br>support@knowi.com","from":null,"sendTo":"some@some.com","cc":null,"bcc":null,"dashIds":[111012],"datasets":"[]","reportAs":10222,"scheduleId":90,"reportContentFilters":"[{\"fieldName\":\"param1\",\"type\":\"java.lang.String\",\"values\":[\"val1\"],\"operator\":\"Equals\"},{\"fieldName\":\"param2\",\"type\":\"java.lang.String\",\"values\":[\"val2\"],\"operator\":\"Equals\"}]","webhooks":[],"slacks":[],"teams":[],"executionReport":null,"nlpQuery":null,"contextPath":null,"nlpDatasetId":null,"datasetReports":null,"reportContentFiltersArr":null,"dashboards":null,"testRun":false}' http://localhost:9090/api/1.0/reports

 

Edit Report

This endpoint is for updating/modifying the reports

PUT /api/1.0/reports

No parameters

PUT JSON payload:

 

Sample with "Run As" (reportAs field is id of other user), and with content filters (reportContentFilters field).
Note that id of email report is within POST data as json field "emailReportId".

      {
        "emailReportId": 68,
        "startTime": null,
        "frequency": 1,
        "frequencyType": "days",
        "subject": "subj1",
        "name": "rep1",
        "text": "Email report

Knowi Team
support@knowi.com",
        "from": null,
        "sendTo": "some@some.com",
        "cc": null,
        "bcc": null,
        "dashIds": [
          111012
        ],
        "datasets": "[]",
        "reportAs": 10222,
        "scheduleId": 90,
        "reportContentFilters": "[{\"fieldName\":\"param1\",\"type\":\"java.lang.String\",\"values\":[\"val1\"],\"operator\":\"Equals\"},{\"fieldName\":\"param2\",\"type\":\"java.lang.String\",\"values\":[\"val2\"],\"operator\":\"Equals\"}]",
        "webhooks": [],
        "slacks": [],
        "teams": [],
        "executionReport": null,
        "nlpQuery": null,
        "contextPath": null,
        "nlpDatasetId": null,
        "datasetReports": null,
        "reportContentFiltersArr": null,
        "dashboards": null,
        "testRun": false
      }
HTTP StatusResponse
200 OKOutput edited entity
400 BAD REQUEST
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:

  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
    Error details:
  • Failed to create report
401 UNAUTHORIZED
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:

  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN
{ "message": <Error details>, "documentation_url": <Documentation link> }


Error details:

  • Current user is not allowed to edit a report
  • Not authorized to run report as another user
  • Current user is not allowed to access specified dataset
  • Current user is not allowed to access specified dashboard
  • Not authorized to access an asset
  • Authorization exception: {exception details}
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d '{"emailReportId":68,"startTime":null,"frequency":1,"frequencyType":"days","subject":"subj1","name":"rep1","text":"<span>Email report</span><br><br>Knowi Team<br>support@knowi.com","from":null,"sendTo":"some@some.com","cc":null,"bcc":null,"dashIds":[111012],"datasets":"[]","reportAs":10222,"scheduleId":90,"reportContentFilters":"[{\"fieldName\":\"param1\",\"type\":\"java.lang.String\",\"values\":[\"val1\"],\"operator\":\"Equals\"},{\"fieldName\":\"param2\",\"type\":\"java.lang.String\",\"values\":[\"val2\"],\"operator\":\"Equals\"}]","webhooks":[],"slacks":[],"teams":[],"executionReport":null,"nlpQuery":null,"contextPath":null,"nlpDatasetId":null,"datasetReports":null,"reportContentFiltersArr":null,"dashboards":null,"testRun":false}' http://localhost:9090/api/1.0/reports

Run Report

This endpoint is for running all the reports

POST /api/1.0/reports/run

No parameters

POST JSON payload:

 

Sample with "Run As" (reportAs field is id of other user), and with content filters (reportContentFilters field).

 {
        "subject": "subj1",
        "name": "rep2022-11-22-15-54",
        "text": "Email report

Knowi Team
support@knowi.com",
        "from": null,
        "sendTo": "some@some.com",
        "cc": null,
        "bcc": null,
        "dashIds": [
          111012
        ],
        "datasets": "[]",
        "reportAs": 10222,
        "scheduleId": 90,
        "reportContentFilters": "[{\"fieldName\":\"param1\",\"type\":\"java.lang.String\",\"values\":[\"val1\"],\"operator\":\"Equals\"},{\"fieldName\":\"param2\",\"type\":\"java.lang.String\",\"values\":[\"val2\"],\"operator\":\"Equals\"}]",
        "webhooks": [],
        "slacks": [],
        "teams": [],
        "executionReport": null,
        "nlpQuery": null,
        "contextPath": null,
        "nlpDatasetId": null,
        "datasetReports": null,
        "reportContentFiltersArr": null,
        "dashboards": null
      }
HTTP StatusResponse
200 OKOutput created entity
400 BAD REQUEST
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:

  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
401 UNAUTHORIZED
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:

  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN
{ "message": <Error details>, "documentation_url": <Documentation link> }


Error details:

  • Current user is not allowed to create a report
  • Current user is not allowed to access specified dataset
  • Current user is not allowed to access specified dashboard
  • Not authorized to access an asset
  • Authorization exception: {exception details}
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X POST -d '{"subject":"subj1","name":"rep2022-11-22-15-54","text":"<span>Email report</span><br><br>Knowi Team<br>support@knowi.com","from":null,"sendTo":"some@some.com","cc":null,"bcc":null,"dashIds":[111012],"datasets":"[]","reportAs":10222,"scheduleId":90,"reportContentFilters":"[{\"fieldName\":\"param1\",\"type\":\"java.lang.String\",\"values\":[\"val1\"],\"operator\":\"Equals\"},{\"fieldName\":\"param2\",\"type\":\"java.lang.String\",\"values\":[\"val2\"],\"operator\":\"Equals\"}]","webhooks":[],"slacks":[],"teams":[],"executionReport":null,"nlpQuery":null,"contextPath":null,"nlpDatasetId":null,"datasetReports":null,"reportContentFiltersArr":null,"dashboards":null}' http://localhost:9090/api/1.0/reports/run

Run Saved Report

This endpoint runs an existing saved report using its configured settings, with optional overrides for email recipients, subject, message, and report content filters.

Query

POST /api/1.0/reports/<reportId>/run

 

ParameterComments
reportIdID of the saved report to execute

POST JSON payload (all fields are optional):

ParameterTypeComments
recipientsArray of stringsOverride primary email recipients (sendTo). If not provided, uses saved report configuration.
ccArray of stringsOverride CC email recipients. If not provided, uses saved report configuration.
bccArray of stringsOverride BCC email recipients. If not provided, uses saved report configuration.
subjectStringOverride email subject. If not provided, uses saved report configuration.
messageStringOverride email message body. If not provided, uses saved report configuration.
reportContentFiltersArray of Filter objectsOverride report content filters to apply to dashboard widgets and datasets in the report. Each filter object contains: fieldName (string), type (string, e.g., "java.lang.String"), values (array of strings), and operator (string, e.g., "Equals", "In", "GreaterThan"). If not provided, uses saved report configuration.
Example Payloads

Example 1 - Override recipients only:

{
  "recipients": ["user1@example.com", "user2@example.com"]
}

Example 2 - Override recipients and subject:

{
  "recipients": ["manager@example.com"],
  "cc": ["team@example.com"],
  "subject": "Monthly Sales Report - January 2024"
}

Example 3 - Full override:

{
  "recipients": ["executive@example.com"],
  "cc": ["director@example.com"],
  "bcc": ["archive@example.com"],
  "subject": "Q4 Executive Summary",
  "message": "<span>Please find attached the Q4 executive summary report.</span><br><br>Best regards,<br>Analytics Team"
}

Example 4 - Override with report content filters:

{
  "recipients": ["regional-manager@example.com"],
  "subject": "Regional Sales Report - North Region",
  "reportContentFilters": [
    {
      "fieldName": "region",
      "type": "java.lang.String",
      "values": ["North"],
      "operator": "Equals"
    },
    {
      "fieldName": "year",
      "type": "java.lang.Integer",
      "values": ["2024"],
      "operator": "Equals"
    }
  ]
}

Example 5 - Filters with multiple values using IN operator:

{
  "recipients": ["multi-region@example.com"],
  "reportContentFilters": [
    {
      "fieldName": "region",
      "type": "java.lang.String",
      "values": ["North", "South", "East"],
      "operator": "In"
    },
    {
      "fieldName": "revenue",
      "type": "java.lang.Double",
      "values": ["100000"],
      "operator": "GreaterThan"
    }
  ]
}
Response
HTTP StatusResponse
200 OK
    {
      "executionStatus": "SUCCESS",
      "executionDate": "2024-01-15T10:30:00Z",
      "duration": 2543,
      "details": [
        {
          "ok": true,
          "message": "Email sent successfully to user1@example.com, user2@example.com"
        }
      ]
    }
400 BAD REQUEST
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:Failed to run report: {exception details}Missing Authorization headerInvalid count of Authorization headersBearer token missing

401 UNAUTHORIZED
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:Bearer token is not found or expiredAuthorization issue or user does not exist

403 FORBIDDEN
{ "message": <Error details>, "documentation_url": <Documentation link> }


Error details:Current user is not allowed to run a reportReport not accessible or does not existCurrent user is not allowed to access specified datasetCurrent user is not allowed to access specified dashboardAuthorization exception: {exception details}

Example

Example with recipient override:

curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"recipients":["user1@example.com","user2@example.com"],"subject":"Monthly Report - January"}' \
  http://localhost:9090/api/1.0/reports/123/run

Example with no overrides (uses saved configuration):

curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{}' \
  http://localhost:9090/api/1.0/reports/123/run

Pause Report

This endpoint pauses the scheduled delivery of a report of a given id. A paused report stays fully configured and shared, but the scheduler stops running it until it is resumed. Reports paused this way are returned with a status of 6 by the List Reports and View Reports endpoints; active reports have a status of 1.

The user tied to the bearer token needs the report:pause permission and access to the report.

Query

POST /api/1.0/reports/<objectId>/pause

ParameterComments
objectIdReport id to pause

No request body is required.

Response
HTTP StatusResponse
200 OK

Output example:

{
  "message": "Report has been paused",
  "documentation_url": "https://www.knowi.com/docs/managementAPI.html"
}
400 BAD REQUEST
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:Missing Authorization headerInvalid count of Authorization headersBearer token missing

401 UNAUTHORIZED
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:Bearer token is not found or expiredAuthorization issue or user does not exist

403 FORBIDDEN
{ "message": <Error details>, "documentation_url": <Documentation link> }


Error details:Current user is not allowed to access report:pauseReport is not accessible

Pausing a report that is already paused succeeds and leaves the report paused, so the call can safely be retried.

Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" \
  -H "Content-Type: application/json" \
  -X POST \
  http://localhost:9090/api/1.0/reports/68/pause

Resume Report

This endpoint resumes a paused report of a given id and returns it to its saved schedule. Missed runs are not backfilled, so the next delivery happens at the next scheduled time after the report is resumed.

The user tied to the bearer token needs the report:pause permission and access to the report.

Query

POST /api/1.0/reports/<objectId>/unpause

ParameterComments
objectIdReport id to resume

No request body is required.

Response
HTTP StatusResponse
200 OK

Output example:

{
  "message": "Report has been un-paused",
  "documentation_url": "https://www.knowi.com/docs/managementAPI.html"
}
400 BAD REQUEST
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:Missing Authorization headerInvalid count of Authorization headersBearer token missing

401 UNAUTHORIZED
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:Bearer token is not found or expiredAuthorization issue or user does not exist

403 FORBIDDEN
{ "message": <Error details>, "documentation_url": <Documentation link> }


Error details:Current user is not allowed to access report:pauseReport is not accessible

Resuming a report that is not paused succeeds and leaves the report active, so the call can safely be retried.

Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" \
  -H "Content-Type: application/json" \
  -X POST \
  http://localhost:9090/api/1.0/reports/68/unpause

Share the reports to users and groups

This endpoint is for sharing the reports with users and groups of a given report id

PUT /reports/<objectId>/share

ParameterComments
objectIdReport id to share

POST JSON payload:

ParameterComments
shareProperties

Share properties json array. Available fields:

  • Type: Users, Groups.
  • accessLevel: 1 - Edit rights, 2 - Read-only
  • name: the name of the User to share to
  • ssoUser: Optional bool. Set to `true` if sharing to sso user

  • id: group id of the Group to share to.
    Example:

    [ 
  { 
    "type" : "Users", 
    "accessLevel" : 1, 
    "name" : "someUser1@host.com",
    "ssoUser": true
  },
  { 
    "type" : "Groups", 
    "accessLevel" : 1, 
    "id" : 10001 
  } 
]
HTTP StatusResponse
200 OKNo response body
400 BAD_REQUEST
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:

  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing

Error details:

  • Missed shareProperties field
  • shareProperties missed the type field
  • shareProperties missed the accessLevel field
  • shareProperties has invalid the type value
  • shareProperties has invalid the accessLevel value
  • shareProperties missed the id field
  • shareProperties missed the name field
  • shareProperties has invalid the name field
401 UNAUTHORIZED
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:

  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN
{ "message": <Error details>, "documentation_url": <Documentation link> }
415 UNSUPPORTED_MEDIA_TYPECannot consume content type - The server refused this request because the request entity is in a format not supported by the requested resource for the requested method.
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d "{\"shareProperties\" : [ { \"type\" : \"Users\", \"accessLevel\" : 1, \"name\" : \"some@some.com\", \"ssoUser\" : true } ] }" http://localhost:9090/api/1.0/reports/70/share

 

Delete Report

This endpoint for deleting the report of a given id

DELETE /reports/<objectId>

ParameterComments
objectIdReport id to delete
HTTP StatusResponse
200 OKNo response body
400 BAD REQUEST
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:

  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
401 UNAUTHORIZED
{ "message": <Error details>, "documentation_url": <Documentation link> }


Common error details:

  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN
{ "message": <Error details>, "documentation_url": <Documentation link> }


Error details:

  • Current user is not allowed to delete specified report
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X DELETE http://localhost:9090/api/1.0/reports/68

 

Was this article helpful?
0 out of 0 found this helpful
Return to top

Related articles