Introduction
Welcome to the Datascaphe Uplink API! You can use our API to access Datascaphe Uplink API endpoints, which will allow you to manage the following objects :
- User
- Service Principal
- Scanner Data (refresh)
The API can be accessed at the url:
http://datascaphe.com/api/{version}/{endpointname},
for example http://datascaphe.com/api/v1/service-principal.
General information
Request/Response Format
The default response format is JSON. Requests with a message-body use plain JSON to set or update resource attributes. Successful requests will return a 200 OK HTTP status. The content can also be requested XML.
Some general information about responses:
- Dates are returned in ISO8601 format (without T): YYYY-MM-DD HH:MM:SS
- Resource IDs are returned as integers.
- Blank fields are generally included as null or emtpy string instead of being omitted.
Except when specified otherwise, endpoint returns the item created or modified in case of success, or a message with the following attributes in case of failure:
- status: 'error'
- message: error message(s)
Filtering
To return only specific fields from the requested resource, use the query parameter field={list of fields}.
For example: http://datascaphe.com/api/v1/service-principal?fields=id,client_id.
Most of the 'list all' endpoints can use query parameters to filter the returned items. The available parameters are described in every endpoint where they are available.
Authentication
To authorize, use this code:
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here" \
-H "Authorization: fe62a504-379b-123e-a8ff-7085c2acf744:5LiFnv8B7pPlHAJu62fapG4z9ggQ3gR7mRuBElw8VCW5w-n2KJ51d_rgJEaa4wlK"
All endpoints expect the request to contain a header with authentication information using your organization code and an API key.
The header must have the following structure:
Authorization: {organization code}:{api key}
You can register a new API key on your dashboard, in the API keys section.
The organization code can be obtained in the Organization section of the dashboard.
Service Principals
These endpoints allow you to specify the Client Id and secret of service principals that Datascaphe Uplink will use to connect to your Power BI tenant.
Their main use is to create Service Principals or update their secret programmatically before they expire.
Please note that Service Principals secrets are write-only, their value cannot be retreived by the API.
Service Principals Properties
| Attribute | Format | Description | Type |
|---|---|---|---|
| id | string | Client Id associated to the Service Principal/App Registration in Azure. | read-only |
| client_id | string | Client Id associated to the Service Principal/App Registration in Azure. | required |
| client_secret | string | A valid secret associated to the Service Principal in Azure. | required, write-only |
| description | string | Indicative text to recognize SP or search them. | |
| created_date | datetime | Date of the item creation. | read-only |
| updated_date | datetime | Date of the last item update. | read-only |
Read-only values will be ignored if specified in the create/update endpoints.
Required values are required when creating an item.
Get All Service Principals
curl "https://datascaphe.com/api/v1/service-principal" \
-H "Authorization: {organization code}:{api key}"
The above command returns JSON structured like this:
[
{
"id": 1,
"description": "Main SP",
"client_id": "4e9c15e6-6b22-42bc-b33b-2cb5509729aa",
"created_date": "2024-05-24 11:56:58",
"updated_date": "2024-05-26 15:09:13"
},
{
"id": 2,
"description": "Secondary SP",
"client_id": "2cb48097-4b17-28cf-b35b-4e8c19e837bc",
"created_date": "2025-02-24 13:36:11",
"updated_date": "2025-02-26 14:09:55"
}
]
This endpoint retrieves all Service Principals defined on Datascaphe Uplink.
HTTP Request
GET https://datascaphe.com/api/v1/service-principal
Request parameters
| Parameter | Expected Values | Condition |
|---|---|---|
| description | string | like |
| client_id | string | equals |
| created_date_min | datetime | superior or equal to |
| created_date_max | datetime | inferior or equal to |
| updated_date_min | datetime | superior or equal to |
| updated_date_max | datetime | inferior or equal to |
Example: https://datascaphe.com/api/v1/service-principal?created_date_min=2025-02-26%2014%3A09%3A55
Get a Specific Service Principal
curl "https://datascaphe.com/api/v1/service-principal/2" \
-H "Authorization: {organization code}:{api key}"
The above command returns JSON structured like this:
{
"id": 2,
"description": "Secondary SP",
"client_id": "2cb48097-4b17-28cf-b35b-4e8c19e837bc",
"created_date": "2025-02-24 13:36:11",
"updated_date": "2025-02-26 14:09:55"
}
This endpoint retrieves a specific Service Principal.
HTTP Request
GET https://datascaphe.com/v1/service-principal/{ID}
Create a new Service Principal
curl -X POST "https://datascaphe.com/api/v1/service-principal" \
-H "Authorization: {organization code}:{api key}" \
-d '{
"client_id": "2cb48097-4b17-28cf-b35b-4e8c19e837bc",
"description": "Name to recognize the SP"
"client_secret": "secretValue"
}'
The above command returns JSON structured like this:
{
"id": 2,
"description": "Name to recognize the SP",
"client_id": "2cb48097-4b17-28cf-b35b-4e8c19e837bc",
"created_date": "2025-02-24 13:36:11",
"updated_date": "2025-02-26 14:09:55"
}
This endpoint creates a new Service Principal and returns the created item.
HTTP Request
POST https://datascaphe.com/v1/service-principal
Update a Service Principal
curl -X PATCH "https://datascaphe.com/api/v1/service-principal/2" \
-H "Authorization: {organization code}:{api key}"
-d '{
"client_secret": "new secretValue"
}'
The above command returns JSON structured like this:
{
"id": 2,
"description": "Secondary SP",
"client_id": "2cb48097-4b17-28cf-b35b-4e8c19e837bc",
"created_date": "2025-02-24 13:36:11",
"updated_date": "2025-02-26 14:09:55"
}
This endpoint updates a specific Service Principal and returns the updated item.
Only the attributes listed below are updatable, other attributes will be ignored:
| Attribute | Type | Description |
|---|---|---|
| client_id | string | Client Id associated to the Service Principal/App Registration in Azure. |
| client_secret | string | A valid secret associated to the Service Principal in Azure. |
| description | string | Indicative text to recognize SP or search them. |
HTTP Request
PATCH https://datascaphe.com/v1/service-principal/{ID}
Reports
These endpoints allow you to manage the Power BI reports on Datascaphe Uplink. Please note that this is only the representation of Power BI report on Datascaphe backend, you will need to use schedules or the Power BI REST API to refresh the actual report on your Power BI tenant.
The refresh endpoints allow to refresh the data cache on Datascaphe Uplink from Power BI datasets. They will typically be called after a dataset has been refreshed to display the latest data in Datascaphe Uplink.
Report Properties
| Attribute | Format | Description | Type |
|---|---|---|---|
| id | string | Client Id associated to the Service Principal/App Registration in Azure. | read-only |
| name | string | Name of the report, it will be replaced by the actual report name after refresh. | |
| report_id | string | The Power BI Id of the report. | required |
| report_workspace_id | string | The Power BI Id of the workspace. It will be replaced by the actual workspace Id after refresh. | |
| report_workspace_name | string | The name of the workspace. It will be replaced by the actual workspace name after refresh. | |
| dataset_id | string | The Power BI Id of the dataset. | required |
| dataset_workspace_id | string | The Power BI Id of the workspace. It will be replaced by the actual workspace Id after refresh. | |
| dataset_workspace_name | string | The name of the workspace. It will be replaced by the actual workspace name after refresh. | |
| has_rls | bool | (0 or 1) Indicates if the report has RLS. Default 0. Must be set manually. | |
| use_id_service_principal | integer | The datascaphe Id of the Service Principal to use to connect to the report. Null if not using a Service Principal. Default null | |
| cache_max_duration | integer | Duration in seconds during which the scanner data stays valid. After this time, the first user who requests scanner data will generate a call to the Power BI API to update the cache. Default 86400 (24h) | |
| scanner_data_updated_at | datetime | Date of the last scanner data cache refresh. | read-only |
| created_date | datetime | Date of the item creation. | read-only |
| updated_date | datetime | Date of the last item update. | read-only |
Read-only values will be ignored if specified in the create/update endpoints.
Required values are required when creating an item.
Get All Reports
curl "https://datascaphe.com/api/v1/report" \
-H "Authorization: {organization code}:{api key}"
The above command returns JSON structured like this:
[
{
"id": 3,
"name": "S_P_500",
"report_id": "c814f3b2-5f12-40b7-bdee-5a0e02f05363",
"report_workspace_id": "e359bb89-1128-4832-ce47-d65ad7ebed61",
"report_workspace_name": "Financial reporting",
"dataset_id": "e4c7b8bb-decb-45bf-9417-74e9a4edaf86",
"dataset_workspace_id": "e359bb89-1128-4832-ce47-d65ad7ebed61",
"dataset_workspace_name": "Financial reporting",
"has_rls": 0,
"use_id_service_principal": null,
"cache_max_duration": 86400,
"scanner_data_updated_at": "2025-03-01 11:36:42",
"created_date": "2023-08-14 12:41:31",
"updated_date": "2025-03-01 11:36:42"
},
{
"id": 4,
"name": "Chicago",
"report_id": "f332ad4b-d6c4-4864-a2bc-8fcc0cee9d32",
"report_workspace_id": "e359bb89-1128-4832-ce47-d65ad7ebed61",
"report_workspace_name": "Financial reporting",
"dataset_id": "6559f20c-246c-4d99-b89a-6b5dfd6906f5",
"dataset_workspace_id": "e359bb89-1128-4832-ce47-d65ad7ebed61",
"dataset_workspace_name": "Financial reporting",
"has_rls": 0,
"use_id_service_principal": null,
"cache_max_duration": 86400,
"scanner_data_updated_at": "2025-03-03 19:24:17",
"created_date": "2025-01-18 23:43:09",
"updated_date": "2025-03-03 19:24:17"
}
]
This endpoint retrieves all Service Principals defined on Datascaphe Uplink.
HTTP Request
GET https://datascaphe.com/api/v1/service-principal
Request parameters
| Parameter | Expected Values | Condition |
|---|---|---|
| name | string | like |
| report_id | string | equals |
| report_workspace_id | string | equals |
| dataset_id | string | equals |
| dataset_workspace_id | string | equals |
| has_rls | integer(0/1) | equals |
| created_date_min | datetime | superior or equal to |
| created_date_max | datetime | inferior or equal to |
| updated_date_min | datetime | superior or equal to |
| updated_date_max | datetime | inferior or equal to |
| scanner_data_updated_at_min | datetime | superior or equal to |
| scanner_data_updated_at_max | datetime | inferior or equal to |
Example: https://datascaphe.com/api/v1/report?created_date_min=2025-02-26%2014%3A09%3A55
Get a Specific Report
curl "https://datascaphe.com/api/v1/report/3" \
-H "Authorization: {organization code}:{api key}"
The above command returns JSON structured like this:
{
"id": 3,
"name": "S_P_500",
"report_id": "c814f3b2-5f12-40b7-bdee-5a0e02f05363",
"report_workspace_id": "e359bb89-1128-4832-ce47-d65ad7ebed61",
"report_workspace_name": "Financial reporting",
"dataset_id": "e4c7b8bb-decb-45bf-9417-74e9a4edaf86",
"dataset_workspace_id": "e359bb89-1128-4832-ce47-d65ad7ebed61",
"dataset_workspace_name": "Financial reporting",
"has_rls": 0,
"use_id_service_principal": null,
"cache_max_duration": 86400,
"scanner_data_updated_at": "2025-03-01 11:36:42",
"created_date": "2023-08-14 12:41:31",
"updated_date": "2025-03-01 11:36:42"
}
This endpoint retrieves a specific Report.
HTTP Request
GET https://datascaphe.com/v1/report/{ID}
Create a new Report
curl -X POST "https://datascaphe.com/api/v1/report" \
-H "Authorization: {organization code}:{api key}" \
-d '{
"name": "S_P_500",
"report_id": "c814f3b2-5f12-40b7-bdee-5a0e02f05363"
"dataset_id": "e4c7b8bb-decb-45bf-9417-74e9a4edaf86"
}'
The above command returns JSON structured like this:
{
"id": 3,
"name": "S_P_500",
"report_id": "c814f3b2-5f12-40b7-bdee-5a0e02f05363",
"report_workspace_id": null,
"report_workspace_name": null,
"dataset_id": "e4c7b8bb-decb-45bf-9417-74e9a4edaf86",
"dataset_workspace_id": null,
"dataset_workspace_name": null,
"has_rls": 0,
"use_id_service_principal": "0",
"cache_max_duration": 86400,
"scanner_data_updated_at": "2025-03-01 11:36:42",
"created_date": "2023-08-14 12:41:31",
"updated_date": "2025-03-01 11:36:42"
}
This endpoint creates a new Report.
The information about Power BI workspaces will be empty at creation. Values will be filled during report refresh.
HTTP Request
POST https://datascaphe.com/v1/report
Update a Specific Report
curl -X PATCH "https://datascaphe.com/api/v1/report/3" \
-H "Authorization: {organization code}:{api key}"
-d '{
"report_id": "e9a4eda3-5f12-40b7-bdee-7f1a02f05446"
}'
The above command returns JSON structured like this:
{
"id": 3,
"name": "S_P_500",
"report_id": "e9a4eda3-5f12-40b7-bdee-7f1a02f05446",
"report_workspace_id": "e359bb89-1128-4832-ce47-d65ad7ebed61",
"report_workspace_name": "Financial reporting",
"dataset_id": "e4c7b8bb-decb-45bf-9417-74e9a4edaf86",
"dataset_workspace_id": "e359bb89-1128-4832-ce47-d65ad7ebed61",
"dataset_workspace_name": "Financial reporting",
"has_rls": 0,
"use_id_service_principal": null,
"cache_max_duration": 86400,
"scanner_data_updated_at": "2025-03-01 11:36:42",
"created_date": "2023-08-14 12:41:31",
"updated_date": "2025-03-01 11:36:42"
}
This endpoint updates a specific Report.
Only the attributes listed below are updatable, other attributes will be ignored
Name and workspace information will be replaced at report cache refresh so it is not really usefull to specify them.
| Attribute | Type | Description |
|---|---|---|
| name | string | Name of the report. |
| report_id | string | Power BI Id of the report. |
| report_workspace_id | string | Power BI Id of the workspace containing the report. |
| report_workspace_id | string | Name of the workspace containing the report. |
| dataset_id | string | Power BI Id of the dataset. |
| dataset_workspace_id | string | Power BI Id of the workspace containing the dataset. |
| dataset_workspace_id | string | Name of the workspace containing the dataset. |
| has_rls | int(0/1) | 1 if the report uses RLS, 0 otherwise. |
| use_id_service_principal | int | Datascaphe Id of the Service Principal used to get report data, null if no SP is used. |
| cache_max_duration | int | Duration of scanner data cache validity in seconds. |
HTTP Request
PATCH https://datascaphe.com/v1/report/{ID}
Refresh a Specific Report
curl -X POST "https://datascaphe.com/api/v1/report/3/refresh" \
-H "Authorization: {organization code}:{api key}"
-d '{}'
The above command returns JSON structured like this:
{
"message": "Report refreshed succesfully",
"report": {
"id": 3,
"name": "S_P_500",
"report_id": "e9a4eda3-5f12-40b7-bdee-7f1a02f05446",
"report_workspace_id": "e359bb89-1128-4832-ce47-d65ad7ebed61",
"report_workspace_name": "Financial reporting",
"dataset_id": "e4c7b8bb-decb-45bf-9417-74e9a4edaf86",
"dataset_workspace_id": "e359bb89-1128-4832-ce47-d65ad7ebed61",
"dataset_workspace_name": "Financial reporting",
"has_rls": 0,
"use_id_service_principal": null,
"cache_max_duration": 86400,
"scanner_data_updated_at": "2025-03-01 11:36:42",
"created_date": "2023-08-14 12:41:31",
"updated_date": "2025-03-01 11:36:42"
}
}
This endpoint refreshes the Scanner Data cache for the report.
We recommend using a Service Principal for API refresh on the target report. If the report does not have a Service Principal, the most recent user token will be used for refreshing the data.
If the report does not use RLS, then Scanner Data will be cached at the report level.
If the report uses RLS, then Scanner Data will be cached at the user level. If the report does not have a Service Principal, the existing user tokens will be used to refresh each user's data.
Errors
The Datascaphe API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is invalid. |
| 401 | Unauthorized -- Your API key is wrong. |
| 403 | Forbidden -- You are not authorized to access the requested resource. |
| 404 | Not Found -- The specified resource could not be found. |
| 405 | Method Not Allowed -- You tried to access a resource with an invalid method. |
| 406 | Not Acceptable -- You requested a format that isn't json. |
| 429 | Too Many Requests -- You're requesting too many resources in a short amount of time. |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |