API Overview

1. Introduction
You can query or manipulate any data on the Cinchy Platform using the Cinchy Query Language (CQL). You can then save that as a Saved Query which allows it to be accessed via an API endpoint.
You will need to first a Cinchy bearer token (see Authentication), and then you can either access a pre-defined Saved Query via the Saved Query endpoints, or perform freeform querying via the ExecuteCQL endpoint.​
Note that regardless of how you query or manipulate data on the platform, it is always associated back to an account.
2. Master List of Endpoints
The following is a list of common API endpoints. These follow the format of <baseurl>/endpoint
​/admin/index​
​/apps/modelloader​
​/healthcheck​
​/cache/clear​
​/API/ExecuteCQL​
​/API/MyDomain/MyQuery​
​/identity/connect/token​
2.1 /admin/index
Description
This endpoint will bring you to a page with your logs and health check.
2.2 /apps/modelloader
Description
This endpoint will open the model loader.
2.3 /healthcheck
Description
This endpoint will bring you to a page with your platform health check.
2.4 /cache/clear
Description
This endpoint will delete your platform cache data.
2.5 /API/ExecuteCQL​
​POST: https://<Cinchy Web URL>/API/ExecuteCQL​
Description
The Post Request will return an access token which can be used to access Cinchy APIs.
Header Parameters
Name
Data Type
Description
Content-Type
string
application/x-www-form-urlencoded
Body Parameters
Name
Data Type
Description
Token
string
You can pass in your base64 encoded SAML token instead of your Cinchy username and password
Client_id
string
Client Id value from Integrated Clients table
Client_secret
string
Guid value from Integrated Clients table
Username
string
Username of Cinchy user
Password
string
Password for Cinchy user in plain text
Grant_type
string
Set as "password" for username/password authentication. Set as "saml2" for saml token authentication.
Scope
string
Set as "js_api"
Responses
200: The request is successful
// {
    "access_token": "eyUzI1NiIsImtpZCI6IkE4M0UwQTFEQTY1MzE0NkZENUQxOTFDMzRDNTQ0RDJDODYyMzMzMzkiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJxRDRLSGFaVEZHX1YwWkhEVEZSTkxJWWpNemsifQ.eyJuYmYiOjE1NTQxMzE4MjAsImV4cCI6MTU1NDEzNTQyMCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgxIiwiYXVkIjpbImh0dHA6Ly9sb2NhbGhvc3Q6ODA4MS9yZXNvdXJjZXMiLCJqc19hcGkiXSwiY2xpZW50X2lkIjoiYWJjIiwic3ViIjoiMSIsImF1dGhfdGltZSI6MTU1NDEzMTgyMCwiaWRwIjoibG9jYWwiLCJwcm9maWxlIjoiQWRtaW5pc3RyYXRvciIsImVtYWlsIjoiYWRtaW5AY2luY2h5LmNvIiwicm9sZSI6IkNpbmNoeSBVc2VyIEFjY291bnQiLCJpZCI6ImFkbWluIiwic2NvcGUiOlsianNfYXBpIl0sImFtciI6WyJjdXN0b20iXX0.N7drAlvtFiQoN4njs1rd5ZnTvJ_x8ZEnUEi6G1GjR4FS5FyS4hC6xdsT-Zhn1yRJQMkI2HA7HMPWwjsfkZ0IlBwuC25ECkGhbjv7DlK6baHQIkqeB0aTB9aDZSxWfDhV66O0dhby6EIEa4YuGspyjQMsDpx_LimmE9alfsUU-608944ZZkS6lBJlJ9LFCC5hYKARQIMZavrftz0tFUBsDU0T2fHpLNGo5GGwG1f9jUZTWTu7s3C05EsgboW3scUfDzjS_Wf55ExwhopIg9SD6ktHYYNRaCPtfMhU-e43l6a2LH-XrmP7OfoxJP2bvTMcvQCQWUEizKHuxKLl-ehWBw",
    "expires_in": 3600,
    "token_type": "Bearer"
}
400: For invalid parameters, a 400 error will be returned with the following JSON response with a description of the error.
Example:
{
  "error": "invalid_grant",
  "error_description": "Invalid username or password"
}
2.6 /API/MyDomain/MyQuery​
GET: https://<Cinchy Web URL>/API/MyDomain/MyQuery
Description
To access any Cinchy Saved Query API, pass the access token received from the Bearer Token Request in the Authorization header, prefixed by "Bearer".
Query Parameters
Name
Data Type
Description
WrapSingleRecordInArray
boolean
Default is true. Add this parameter and set to false if you want single record results returned as an object instead of within an array.
@param
string
If you have parameters in your query, you pass them indirectly as query parameters.
CompressJSON
boolean
Default is true. Add this parameter and set to false if you want the JSON that is returned to be expanded rather than having the schema being returned separately.
Header Parameters
Name
Data Type
Description
Authorization
string
Bearer <token goes here>
Responses
200: The request has successfully returned the record set.
< HTTP/2 200 
< cache-control: private, s-maxage=0
< content-type: application/json; charset=utf-8
< server: Microsoft-IIS/10.0
< x-aspnetmvc-version: 5.2
< access-control-allow-origin: *
< x-aspnet-version: 4.0.30319
< x-powered-by: ASP.NET
< date: Wed, 1 Aug 2020 17:40:13 GMT
< content-length: 2985
​
400: The request could not be understood, the client is sending a request with incomplete data, poorly constructed data or invalid data.
Optional Validation Logic: To validate query business / control conditional logic failure can be added at the beginning of the API which can intentionally generate a 400 error code (using RAISERROR) and stopping (using RETURN) the API. If there is no RETURN the errors will accumulate and will be provided at the end of running the API.
An attribute (X-Cinchy Error) will be returned in the HTTP header with the custom RAISERROR message indicated (see example)
Example:
--given the following CQL used within a saved query:
​
IF (ISNULL(@Int,0) = 0)
BEGIN
  RAISERROR('Invalid parameter: @Int cannot be NULL or zero',18,0)
  RETURN
END
IF (ISNULL(@String,'') = '' OR ISNULL(@String,'') = 'X')
BEGIN
  RAISERROR('Invalid parameter: @String cannot be NULL or empty or X',18,0)
  RETURN
END
​
--note "X-Cinchy-Error" in the sample response:
​
< HTTP/1.1 400 Bad Request
< Cache-Control: private
< Content-Type: text/html; charset=utf-8
< Server: Microsoft-IIS/10.0
< X-AspNetMvc-Version: 5.2
< Access-Control-Allow-Origin: *
< X-Cinchy-Error: Invalid parameter: @Int cannot be NULL or zero
< X-AspNet-Version: 4.0.30319
< X-Powered-By: ASP.NET
< Date: Wed, 1 Aug 2020 17:43:04 GMT
< Content-Length: 4517
​
401: The saved query API endpoint will return a 401 error code when you provide invalid credentials, this includes not providing credentials, expired credentials and incorrect credentials.
< HTTP/1.1 401 Unauthorized
< Cache-Control: private
< Content-Type: text/html; charset=utf-8
< Server: Microsoft-IIS/10.0
< X-AspNetMvc-Version: 5.2
< X-AspNet-Version: 4.0.30319
​
2.7 /identity/connect/token​
POST: https://<Cinchy SSO URL>/identity/connect/token
Definition
The Post Request will return an access token which can be used to access Cinchy APIs.
Header Parameters
Name
Data Type
Description
Content-type
string
application/x-www-form-urlencoded
Body Parameters
Name
Data Type
Description
Token
string
You can pass in your base64 encoded SAML token instead of your Cinchy username and password
Client_id
string
Client Id value from Integrated Clients table
Client_secret
string
Guid value from Integrated Clients table
Username
string
Username of Cinchy user
Password
string
Password for Cinchy user in plain text
Grant_Type
string
Set as "password" for username/password authentication. Set as "saml2" for saml token authentication.
Scope
string
Set as "js_api"
Responses
200: The request is successful
// {
    "access_token": "eyUzI1NiIsImtpZCI6IkE4M0UwQTFEQTY1MzE0NkZENUQxOTFDMzRDNTQ0RDJDODYyMzMzMzkiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJxRDRLSGFaVEZHX1YwWkhEVEZSTkxJWWpNemsifQ.eyJuYmYiOjE1NTQxMzE4MjAsImV4cCI6MTU1NDEzNTQyMCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgxIiwiYXVkIjpbImh0dHA6Ly9sb2NhbGhvc3Q6ODA4MS9yZXNvdXJjZXMiLCJqc19hcGkiXSwiY2xpZW50X2lkIjoiYWJjIiwic3ViIjoiMSIsImF1dGhfdGltZSI6MTU1NDEzMTgyMCwiaWRwIjoibG9jYWwiLCJwcm9maWxlIjoiQWRtaW5pc3RyYXRvciIsImVtYWlsIjoiYWRtaW5AY2luY2h5LmNvIiwicm9sZSI6IkNpbmNoeSBVc2VyIEFjY291bnQiLCJpZCI6ImFkbWluIiwic2NvcGUiOlsianNfYXBpIl0sImFtciI6WyJjdXN0b20iXX0.N7drAlvtFiQoN4njs1rd5ZnTvJ_x8ZEnUEi6G1GjR4FS5FyS4hC6xdsT-Zhn1yRJQMkI2HA7HMPWwjsfkZ0IlBwuC25ECkGhbjv7DlK6baHQIkqeB0aTB9aDZSxWfDhV66O0dhby6EIEa4YuGspyjQMsDpx_LimmE9alfsUU-608944ZZkS6lBJlJ9LFCC5hYKARQIMZavrftz0tFUBsDU0T2fHpLNGo5GGwG1f9jUZTWTu7s3C05EsgboW3scUfDzjS_Wf55ExwhopIg9SD6ktHYYNRaCPtfMhU-e43l6a2LH-XrmP7OfoxJP2bvTMcvQCQWUEizKHuxKLl-ehWBw",
    "expires_in": 3600,
    "token_type": "Bearer"
}
400: For invalid parameters, a 400 error will be returned with the following JSON response with a description of the error.
Example:
{
  "error": "invalid_grant",
  "error_description": "Invalid username or password"
}

Setting Up Experiences

API Authentication

Last modified 3mo ago

Copy link

On this page

1. Introduction

2. Master List of Endpoints

2.1 /admin/index

2.2 /apps/modelloader

2.3 /healthcheck

2.4 /cache/clear

2.5 /API/ExecuteCQL

2.6 /API/MyDomain/MyQuery

2.7 /identity/connect/token