API Overview

Introduction

Cinchy has various available APIs, each performing important functions for your use cases.

For example, using the MyQuery API will allow you to turn any Saved Query on your platform into a REST API.

Many of the APIs listed on this page can use Bearer Tokens or Personal Access Tokens to authenticate. Please review the API Authentication page for further information.

List of common endpoints

The following is a list of common API endpoints. These follow the format of <baseurl> endpoint.

API Overview
- Introduction
- List of common endpoints

/admin/index

Description
This endpoint will bring you to a page with your database health check. This page also allows you to change your system's logo. This endpoint can only be reached by an Admin user.

Example URL: https://cinchy.net/admin/index

Example Response Admin Index Response

/apps/modelloader

Description
This endpoint will open the model loader, which is used to import data models between Cinchy instances.

Example URL: https://cinchy.net/apps/modelloader

Example Response Model Loader Response

/healthcheck

Description
This endpoint will bring you to a page with your platform health check. The platform healthcheck will show you important status information about your environment.

Example URL: https://cinchy.net/healthcheck

Response Schema:

Parameter	Description	Example
`component`	Identifies the system component.	"Cinchy"
`version`	Specifies the version of the component.	"5.0.0"
`buildIdentifier`	The build identifier for the current version.	"release/v5.7/b7cd786fd721ac69e0d8d8c4"
`ipAddress`	Array of IP addresses associated with the component.	["876.31.167.197"]
`systemTime`	The current system time in UTC format.	"2024-03-13T13:31:12.1294819Z"
`status`	Overall health status of the system.	"Green"
`healthChecks[].name`	Name of the specific health check.	"Database Connectivity"
`healthChecks[].description`	Description of what the health check entails.	"Validates that the application can connect to the database"
`healthChecks[].status`	Status of the health check.	"Green"

Example Response

{
 "component": "Cinchy",
 "version": "5.9.0",
 "buildIdentifier": "release/v5.7/b7cd786fd721ac69e0d8d8c4",
 "ipAddress": [
   "876.31.167.197"
 ],
 "systemTime": "2024-03-13T13:31:12.1294819Z",
 "status": "Green",
 "healthChecks": [
   {
     "name": "Database Connectivity",
     "description": "Validates that the application can connect to the database",
     "status": "Green"
   },
   {
     "name": "Identity Provider",
     "description": "Validates that the application can connect to the Cinchy IdP",
     "status": "Green"
   }
 ]
}

idp/healthcheck

Description
The `/idp/healthcheck` provides a comprehensive status check for the Cinchy Single Sign-On (SSO) component. It returns a JSON response detailing various aspects of the system's health and operational status.

*Example URL: https://cinchy.net/idp/healthcheck

Response Schema

Parameter	Description	Example
`component`	Identifies the system component.	"Cinchy"
`version`	Specifies the version of the component.	"5.9.0"
`buildIdentifier`	The build identifier for the current version.	"release/v5.9/b7cd786fd721ac69e0d8d8c4"
`ipAddress`	Array of IP addresses associated with the component.	["172.31.158.166"]
`systemTime`	The current system time in UTC format.	"2024-03-13T13:50:02.7435816Z"
`status`	Overall health status of the system.	"Green"
`healthChecks[].name`	Name of the specific health check.	"Database Connectivity"
`healthChecks[].description`	Description of what the health check entails.	"Validates that the application can connect to the database"
`healthChecks[].status`	Status of the health check.	"Green"

Example Response:

{
  "component": "Cinchy SSO",
  "version": "5.9.0",
  "buildIdentifier": "release/v5.9/76017f43b9171f16cc9e0bb5",
  "ipAddress": [
    "172.31.157.120"
  ],
  "systemTime": "2024-03-13T13:50:02.7435816Z",
  "status": "Green",
  "healthChecks": [
    {
      "name": "Database Connectivity",
      "description": "Validates that the application can connect to the database",
      "status": "Green"
    }
  ]
}

/connections/healthcheck

Description
This endpoint checks the health and version information of the Connections API. It's useful for monitoring the API's status and its current version in deployment.

Example URL: https://cinchy.net/connections/healthcheck

Response Schema:

Parameter	Description	Example
`component`	The name of the API component being checked.	`"Connections API"`
`version`	The current version of the Connections API.	`"5.9.0"`
`buildIdentifier`	A unique identifier for the build, usually including commit hash and branch information.	`"refs/heads/release/v5.9/be511e3a10a77c6c1df083f20d214e34a808415f"`

Example Response

{"component":"Connections API","version":"5.9.0","buildIdentifier":"release/v5.9/76017f43b9171f16cc9e0bb5"}

/metaforms/healthcheck

Description
This endpoint will bring you to a page with your Meta-Forms health check.

Example URL: https://cinchy.net/metaforms/healthcheck

Response Schema:

Parameter	Description	Example
`component`	The name of the API component being checked.	`"Meta-Forms"`
`version`	The current version of the Connections API.	`"5.9.3"`
`buildIdentifier`	A unique identifier for the build, usually including commit hash and branch information.	`"refs/heads/release/v5.9/be511e3a10a77c6c1df083f20d214e34a808415f"`
`githubURL`	The URL to the GitHub repository that stores the application	"https://github.com/cinchy-co/meta-forms-app-experience/commit/ab9b84b1c5565e36b22254a1660c3518cf3eb11e"

Example Response

{
    "component":"Meta-Forms",
    "version": "5.9.3",
    "buildIdentifier": "refs/heads/release/v5.9.3/ab9b84b1c5565e36b22254a1660c3518cf3eb11e",
    "githubURL": "https://github.com/cinchy-co/meta-forms-app-experience/commit/ab9b84b1c5565e36b22254a1660c3518cf3eb11e"
}

/cache/clear

Description
This endpoint will delete your platform cache data.

/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's returned to be expanded rather than having the schema being returned separately.
ResultFormat	string	- XML - JSON - 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're 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 Personal Access token. See Authentication for details.

Responses

200 (OK)

Parameters

To pass in parameters in your executeCQL, use this format. For one parameter, include 3 query parameters starting with Parameters[0]. For a second parameter, add 3 more query parameters starting with Parameters[1]..

Query String Parameter Name	Content
`Parameters[n].ParameterName`	Name of the parameter, including '@'. Example: `@name`
`Parameters[n].XmlSerializedValue`	XML serialized value. Example: `"test"`
`Parameters[n].ValueType`	Data type of the value. Example: `System.String`

/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's 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 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 couldn't 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 for invalid credentials. This includes missing, expired, or 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

/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	v5.9 or below: Set as `js_api` v5.10+: This will be either read:all or write:all, and should match the "Permitted Scopes" column from the [Cinchy].[Integrated Clients] table of the associated client.

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"
}

/api/getstsauthorityuri

Description
This will return your IDP URL endpoint.

/api/v1.0/secrets-manager

/api/v1.0/secrets-manager/secret?secretName=&domain=

Description
This API will return a secret from the Cinchy Secrets Manager table.

Header parameters

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

Body parameters

Parameter	Description
`<base-url>`	Your Cinchy base URL.
`<secret-name>`	Name of the secret, as it appears in the Cinchy Secrets table.
`<domain-name>`	Domain where your secret resides.

Blank example

<base-url>/api/v1.0/secrets-manager/secret?secretName=<secret-name>&domain=<domain-name>

Populated example

Cinchy.net/api/v1.0/secrets-manager/secret?secretName=<ExampleSecret>&domain=<Sandbox>

The API will return an object in the below format:

{
    "secretValue": "password123"
}

/api/jobs

POST: Https://<Connections-URL>/api/jobs

Description
This endpoint can be used to trigger a batch data sync job that has been configured in Cinchy.

Request Header parameters

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

Body parameters

caution

Note that the parameter names "files" and "options" are both case sensitive and must use lowercase in your JSON. The contents of the parameters themselves aren't case sensitive.

Name	Data Type	Description
files	binary	The URL to any file(s) needed to be uploaded to be used in place of a parameter in the data sync
options	string	A JSON string of the data sync options. See here for the structure of this JSON string.

Options - JSON structure

 {
     "paramValues": {
       "<name of parameter in sync>": {
         "isFile": <set to true if this parameter corresponds to a file, otherwise set it to false>,
         "value": "<value of the parameter, if the parameter corresponds to a file, then it should match the file name that was uploaded>"
       }
     },
     "server": "<cinchy url without protocol>",
     "useHttps": <true or false, depending on the server's protocol>,
     "userId": "<username of the user you want to run the data sync as, leave as null if you want to run it as the user associated with the access token used in the Authorization header>",
     "password": "<password of the user you want to run the data sync as, leave as null if you want to run it as the user associated with the access token used in the Authorization header>",
     "model": "Cinchy",
     "feed": "<name of the data sync configuration>",
     "batchsize": <Set to 5000 for the default behaviour - the size of the batches when performing inserts/updates/deletes in the target, set to 5000 if you want the default behaviour>,
     "retrievalbatchsize": <Set to 5000 for the default behaviour -  this is the size of the batches when retrieving records from the source to process>,
     "writeToFile": <Set to true for the default behaviour - This will ensure it will write records to temp files on disk to save memory on larger syncs. If this is set to false, it'll store source records in memory, which will be faster for smaller data syncs>
   }

//example
{
    "server": "cinchy.net/product-1",
    "useHttps": "true",
    "password": "cinchy",
    "userId": "admin",
    "model": "Cinchy",
    "feed": "API Data Sync",
    "batchsize": 5000,
    "retrievalbatchsize": 5000,
    "writeToFile": "true"
}

Endpoint example

--request POST
  --url https://cinchy.net/product-1/connections/api/jobs
  --header 'Authorization: Bearer xxx’
  --header 'Content-Type: multipart/form-data'
  --form files=@/Users/admin/Worker.zip
  --form 'options={ "paramValues": {  "file": {   "isFile": true,   "value": "FBL costing model with upload to SF.xlsx"  } }, "server": "cinchy.net/product-1", "useHttps": "true", "password": null, "userId": null, "model": "Cinchy", "feed": "API Data Sync", "batchsize": 5000, "retrievalbatchsize": 5000, "writeToFile": "true"}'

Responses

**200:The request was successful.

{
   executionId = "<The Cinchy Id of the data sync execution, it will correspond go the Cinchy Id of the newly created record in the [Cinchy.[Execution Log] table>"
}

400: The request couldn't be completed.**

{
   status = <Http status code>,
   message = "<Error message>"
}

API Overview

Introduction​

List of common endpoints​

/admin/index​

/apps/modelloader​

/healthcheck​

idp/healthcheck​

/connections/healthcheck​

/metaforms/healthcheck​

/cache/clear​

/API/ExecuteCQL​

Query Parameters​

Header Parameters​

Responses​

Parameters​

/API/MyDomain/MyQuery​

Query Parameters​

Header Parameters​

Responses​

/identity/connect/token​

Header parameters​

Body parameters​

Responses​

/api/getstsauthorityuri​

/api/v1.0/secrets-manager​

Header parameters​

Body parameters​

Blank example​

Populated example​

/api/jobs​

Request Header parameters​

Body parameters​

Options - JSON structure​

Endpoint example​

Introduction

List of common endpoints

/admin/index

/apps/modelloader

/healthcheck

idp/healthcheck

/connections/healthcheck

/metaforms/healthcheck

/cache/clear

/API/ExecuteCQL

Query Parameters

Header Parameters

Responses

Parameters

/API/MyDomain/MyQuery

Query Parameters

Header Parameters

Responses

/identity/connect/token

Header parameters

Body parameters

Responses

/api/getstsauthorityuri

/api/v1.0/secrets-manager

Header parameters

Body parameters

Blank example

Populated example

/api/jobs

Request Header parameters

Body parameters

Options - JSON structure

Endpoint example