API Overview

This page gives an overview of APIs.

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
You can execute CQL directly without creating a Saved Query using the below endpoint:
Query Parameters:
​
Name
Data Type
Description
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.
ResultFormat
string
XML
JSON
CSV
TSV
PSV
PROTOBUF
Type
string
QUERY 
- Query (Approved Data Only) 
DRAFT_QUERY 
- Query (Include Draft Changes) 
SCALAR 
- Scalar 
NONQUERY 
- Non Query, such as an insert or delete 
VERSION_HISTORY_QUERY 
- Query (Include Version History)
ConnectionId
string
​
TransactionId
string
When one or more requests share the same TransactionId, they are considered to be within the scope of a single transaction.
Query
string
The CQL query statement to execute
Parameters
boolean
See below on format for the parameters.
SchemaOnly
integer
Defaults to false.
StartRow
integer
When implementing pagination, specify a starting offset. Combine with RowCount to set the size of the data window.
RowCount
integer
When implementing pagination, specify the number of rows to retrieve for the current page. Combine with StartRow to set the paging position.
CommandTimeout
string
Use this parameter to override the default timeout (30s) for long running queries. In seconds.
UserId
string
ID of a user with authorization to run the saved query.
Header Parameters:
Name
Data Type
Description
Authorization
string
Bearer <access_token>

The access token can be either a Bearer token or a Personal Access token.

See Authentication for details.
Responses:
200 (OK)
Parameters
To pass in parameters in your executeCQL, you will need to pass in sets of parameters in the following format. So if you have one parameter then you would pass in 3 query parameters beginning with Parameters[0]. , and if you have a second parameter you would include an additional 3 query parameters beginning with Parameters[1]. .
Query String Parameter Name
Content
Parameters[n].ParameterName
Name of the parameter that is in your query, including the '@'.
Ex. @name
Parameters[n].XmlSerializedValue
XML Serialized version of the value of that parameter.
Ex. &quot;test&quot;
Parameters[n].ValueType
Datatype of the value.
Ex. System.String
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 either the Bearer Token Request or created as a PAT, 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 <access_token>

The access token can be either a Bearer token or a Personal Access token.

See Authentication for details.
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"
}

Description
This endpoint will bring you to a page with your logs and health check.

Description
This endpoint will open the model loader.

Description
This endpoint will bring you to a page with your platform health check.

Description
This endpoint will delete your platform cache data.

Description
You can execute CQL directly without creating a Saved Query using the below endpoint:

Name	Data Type	Description
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.
ResultFormat	string	XML JSON CSV TSV PSV PROTOBUF
Type	string	QUERY - Query (Approved Data Only) DRAFT_QUERY - Query (Include Draft Changes) SCALAR - Scalar NONQUERY - Non Query, such as an insert or delete VERSION_HISTORY_QUERY - Query (Include Version History)
ConnectionId	string
TransactionId	string	When one or more requests share the same TransactionId, they are considered to be within the scope of a single transaction.
Query	string	The CQL query statement to execute
Parameters	boolean	See below on format for the parameters.
SchemaOnly	integer	Defaults to false.
StartRow	integer	When implementing pagination, specify a starting offset. Combine with `RowCount` to set the size of the data window.
RowCount	integer	When implementing pagination, specify the number of rows to retrieve for the current page. Combine with `StartRow` to set the paging position.
CommandTimeout	string	Use this parameter to override the default timeout (30s) for long running queries. In seconds.
UserId	string	ID of a user with authorization to run the saved query.

Name	Data Type	Description
Authorization	string	Bearer <access_token> The access token can be either a Bearer token or a Personal Access token. See Authentication for details.

Query String Parameter Name	Content
Parameters[n].ParameterName	Name of the parameter that is in your query, including the '@'. Ex. `@name`
Parameters[n].XmlSerializedValue	XML Serialized version of the value of that parameter. Ex. `"test"`
Parameters[n].ValueType	Datatype of the value. Ex. `System.String`

Description
To access any Cinchy Saved Query API, pass the access token, received from either the Bearer Token Request or created as a PAT, in the Authorization header, prefixed by "Bearer".

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.

Name	Data Type	Description
Authorization	string	Bearer <access_token> The access token can be either a Bearer token or a Personal Access token. See Authentication for details.

Definition
The Post Request will return an access token which can be used to access Cinchy APIs.

Name	Data Type	Description
Content-type	string	application/x-www-form-urlencoded

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"

Setting Up Experiences

API Authentication

Last modified 16d ago

API Overview

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​

Responses:

Parameters

2.6 /API/MyDomain/MyQuery​

2.7 /identity/connect/token​

2.5 /API/ExecuteCQL

2.6 /API/MyDomain/MyQuery

2.7 /identity/connect/token