API overview

Introduction

This page lists the various APIs that can be used to perform important functions in your Cinchy use cases.

List of API endpoints

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

API overview
- Introduction
- List of API endpoints

/admin/index

Description
This endpoint opens the Cinchy admin panel. This page contains your database health check and your system 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 opens the model loader/importer, 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 opens your platform health check, which displays important status information about your environment. The exact parameters and their descriptions can be reviewed in the `Response schema` table below.

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.9.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's cache data.

Example URL: https://cinchy.net/cache/clear

/API/ExecuteCQL

Description
The ExecuteCQL endpoint is used to execute a Cinchy Query Language function directly, without creating a Saved Query, via a POST request.

Example request: POST: Https://<Cinchy Web URL>/API/ExecuteCQL

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	The format in which the query results are returned. - XML - JSON - JSON - CSV - TSV - PSV - PROTOBUF
Type	String	The type of query to be executed. 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	Review the parameters section for details.
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, in seconds, to override the default timeout (30 seconds) for long running queries.
UserId	String	`ID` of a user with authorization to run the saved query, if using a bearer token.

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`

info

To use StartRow and RowCount with ExecuteCQL, set ResultFormat to DELIMITED_FILE and include an additional Delimiter parameter, such as , or |.

Example

In the below example, we are executing the following query, which updates the "Colours" column in the specified table from 'Green' to 'Pink':

UPDATE [Product].[Documentation Colours]
SET [Colours] = 'Pink'
WHERE [Colours] = 'Green'

The following parameters are used in the API call:

Query parameters

Parameter	Value
ResultsFormat	JSON
Type	NONQUERY
Query	UPDATE `[Product].[Documentation Colours]` SET `[Colours]` = 'Pink' WHERE `[Colours]` = 'Green'

Header parameters

Parameter	Value
Authorization	Bearer B5CF3E6EE83450THCILPD209A371F-1

Execute CQL Example

/API/MyDomain/MyQuery

Description
You can access any saved query via API endpoint by passing in the REST URL and a form of authentication. For more details on this endpoint, please review the documentation here.

Example requests:

v5.10+: GET: Https://<Cinchy Web URL>/API/v[API Version]/MyDomain/MyQuery

Older versions: GET: Https://<Cinchy Web URL>/API/MyDomain/MyQuery

Note that when using basic auth the URL construction differs slightly: GET: Https://<Cinchy Web URL>/BasicAuthAPI/MyDomain/MyQuery

/identity/connect/token

Definition
Returns an access token which can be used with Cinchy APIs. Review the API authentication documentation for further details.

Example request: POST: Https://<Cinchy SSO URL>/identity/connect/token

/api/getstsauthorityuri

Description
Return the platform's IDP URL endpoint.

Example URL: https://cinchy.net/api/getstsauthorityuri

/api/v1.0/secrets-manager

Description
Returns a secret from the `[Cinchy].[Secrets Manager]` table.

Example URL: https://cinchy.net/api/v1.0/secrets-manager/secret?secretName=\&domain=

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 API authentication for details.

Body parameters

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

Example request

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

Example response

{
  "secretValue": "password123"
}

/api/jobs

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

Example requests:

v5.10+: POST: Https://<Connections-URL>/api/v1.0/jobs

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

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 the page on API 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 Options - JSON structure for the structure of this JSON string.

Options - JSON structure

Parameter	Description	Example
isFile	Set to true if this parameter corresponds to a file, otherwise set it to false.	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 the protocol.	cinchy.net/product-1
useHttps	Set to true or false depending on your server's protocol.	true
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.	user
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.	12345qwerty
pat	Personal access token of the user you want to run the data sync as, if using a PAT to authenticate.
model	Value should be 'Cinchy'.	Cinchy
feed	The name of the data sync.	API Data Sync
batchsize	The size of the batches when performing inserts/updates/deletes in the target. Set to 5000 for the default behaviour.	5000
retrievalbatchsize	The size of the batches when retrieving records from the source to process. Set to 5000 for the default behaviour.	5000
writeToFile	Details whether to 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. Set this to true for the default behaviour.	true

Example structure

{
  "server": "cinchy.net/product-1",
  "useHttps": "true",
  "password": "12345qwerty",
  "userId": "user",
  "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>"

Introduction​

List of API endpoints​

/admin/index​

/apps/modelloader​

/healthcheck​

idp/healthcheck​

/connections/healthcheck​

/metaforms/healthcheck​

/cache/clear​

/API/ExecuteCQL​

Query parameters​

Header parameters​

Responses​

Parameters​

Example​

Query parameters​

Header parameters​

/API/MyDomain/MyQuery​

/identity/connect/token​

/api/getstsauthorityuri​

/api/v1.0/secrets-manager​

Header parameters​

Body parameters​

Example request​

Example response​

/api/jobs​

Request Header parameters​

Body parameters​

Options - JSON structure​

Example structure​

Endpoint example​

Responses​

Introduction

List of API endpoints

/admin/index

/apps/modelloader

/healthcheck

idp/healthcheck

/connections/healthcheck

/metaforms/healthcheck

/cache/clear

/API/ExecuteCQL

Query parameters

Header parameters

Responses

Parameters

Example

Query parameters

Header parameters

/API/MyDomain/MyQuery

/identity/connect/token

/api/getstsauthorityuri

/api/v1.0/secrets-manager

Header parameters

Body parameters

Example request

Example response

/api/jobs

Request Header parameters

Body parameters

Options - JSON structure

Example structure

Endpoint example

Responses