Knowledge Platform API

The Knowledge Platform REST API provides programmatic access to various Knowledge Platform resources and data-related assets. The secure endpoints support robust features such as pagination and rate limiting.

Accessing the Knowledge Platform REST API requires a username and password. For the API to programmatically perform tasks for a tenant, our team must configure an API User account for that tenant. The API User account provides credentials to perform API-driven tasks. When those tasks are completed, assets indicate that the API User completed them. To request an account to access the Knowledge Platform API, open a Support ticket. Requests may take up to two business days to fulfill.

You can subscribe to our API on SwaggerHub to receive updates whenever changes are made to the Syniti REST API OpenAPI documentation. Follow the instructions in the description of our OpenAPI document or refer to Subscribe to Notifications in SwaggerHub for more information about how to subscribe to receive updates about our API.

For a list of our supported API versions, refer to REST API Version Support.

Integration with the Stewardship Tier

To integrate with the Stewardship Tier:

• Use the API to extract data from the Knowledge Platform to populate database tables for the Stewardship Tier; you can install a plug-in for the Stewardship Tier. Once the plug-in is installed, data from the Knowledge Platform can be transformed and/or exported to the desired format, including Excel, Word and formats compatible with third-party systems. Please contact Support to obtain the plug-in and relevant installation documentation.

Current Version

The current Knowledge Platform REST API works with all requests. A newer version of the API will not be released until we develop a new feature that hinders the backwards compatibility to the current version, at which point we will update the URI version and provide a new URL to access the API. Additionally, this document and the JSON will be updated to identify any header, response or other changes when the new version is released.

Schema

All API access is over HTTPS, via https://api.syniti.com/.

All data is sent and received as JSON.

Refer to the full endpoint documentation of the current version of the API at https://app.swaggerhub.com/apis-docs/Syniti2/syniti_knowledge_platform_api/3.1.

Authentication

All interactions with the Knowledge Platform API require authentication. The current supported authentication method is via HTTP Basic with a username and password provided by the Support Team. Provide the username and password in the Authorization header to authenticate your connection to the API.

curl https://api.syniti.com/v3 --user tapi_EXAMPLE:PASSWORD

Authenticating with invalid credentials will return 401 Unauthorized:

curl -i https://api.syniti.com/v3/categories --user badusername:badpassword
< HTTP/1.1 401 Unauthorized

Parameters

Many API endpoints of the Knowledge Platform API support optional parameters. For GET requests, any parameters which are not part of the path can be passed as HTTP Query string parameters.

curl --user tapi_EXAMPLE:PASSWORD https://api.syniti.com/v3/rules?cursor=1Ag6HiZScGv61hgs

In this example, the cursor value is used to retrieve secondary results after an initial payload. Please see Pagination for more information.

Pagination

Endpoints for assets may return an incomplete set of resources. In this case, the response payload will contain a field cursor. A response with an empty cursor indicates that no more resources are available. The value of the cursor can be returned as the value for a query parameter cursor on a follow-up request to the same endpoint. This follow-up request will return a collection of records from the cursor's endpoint value. These cursors are specific to their endpoint, so a cursor returned from the /v3/terms endpoint will cause an error if passed as a cursor query parameter on the /v3/rules endpoint. The number of records returned per page is fixed.

curl https://api.syniti.com/v3/terms --user tapi_EXAMPLE:PASSWORD
< HTTP/2 200
{
	"data": [
	{
		"id": "TE_00101",
		"version": "7de08d2e-d0b6-48fe-a9e3-296fb4f53c53",
		"asset_id": "9b6f3f13-4b62-4875-bfd9-cf86e22b724f",
		"name": "Customer",
		"definition": "A valued customer who engages with products.",
		"additional_info": "Customers make the world go round.",
		"is_critical": true,
		"assigned_to": ["b5b80104-78ba-48fb-a2e4-b7bb142f2a18"],
		"sponsors": ["b5b80104-78ba-48fb-a2e4-b7bb142f2a18"],
		"review_status": "InProgress",
		"category_values": ["c8111e77-9559-4dcc-9256-4fa7c643e562"],
		"relationships": [{
			"id": "22805a41-6167-4108-a896-a6648de21905",
			"version": "62b7c8b6-df26-4417-95ad-bc482586211d",
			"type": "policy",
			"relationship": "links_to"
			}]
		}
	],
	"cursor": "exysG404av_4oun13=="
}

Rate Limiting

To ensure proper access for all clients, the Knowledge Platform API enforces rate limiting.

The API limits access to 8 requests per second. With each request executed against the API, it will return the following headers to assist staying below the threshold:

When the number of requests per second exceeds the maximum allowed, the API will return a 429 Error.

curl -i https://api.syniti.com/v3/categories --user tapi_EXAMPLE:PASSWORD
< HTTP/2 429 Too Many Requests
< Content-Type: text/plain; charset=utf-8
< X-Ratelimit-Limit: 8
< X-Ratelimit-Remaining: 0
< X-Ratelimit-Reset: 1589113120
< Date: Mon, 1 May 2020 20:00:30 GMT
< Content-Length: 14
<
Limit exceeded

Errors

Common errors from the Knowledge Platform API are as follows:

401 Unauthorized

The credentials provided are not valid. This could be due to typos, revocation, or expiration. Ensure that the credentials provided are present in the request and that they match. If this error continues, please contact support.syniti.com.

409 Conflict

The request conflicted with another request. To work around this, send requests one at a time.

429 Rate Limited

The number of calls against the API per time window has been exceeded. This response will be accompanied with the headers listed in Rate Limiting. No more requests will be fulfilled until the time represented by the X-RateLimit-Reset value.

Time Zones

All date-time fields in the responses are represented as UTC.