Knowledge Tier API
The Knowledge Tier REST API v2 provides programmatic access to various Knowledge Tier resources and data-related assets. The secure endpoints support robust features such as pagination and rate limiting. Accessing the Syniti Knowledge Tier REST API requires a username and password. To request an account to access the Knowledge Tier API, contact CustomerSuccess@syniti.com. Requests may take up to two business days to fulfill.
Integration with the Stewardship Tier
To use the API to extract data from the Knowledge Tier 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 Tier can be transformed and/or exported to the desired format, including Excel, Word and formats compatible with third-party systems. Please contact CustomerSuccess@syniti.com to obtain the plug-in and relevant installation documentation.
Current Version
The current Knowledge Tier REST API v2 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 of v2, 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/v2.
All data is sent and received as JSON.
Refer to the full endpoint documentation at https://app.swaggerhub.com/apis/Syniti2/syniti-knowledge_tier_api/2.0.
Authentication
All interactions with the Knowledge Tier API require authentication. The current supported authentication method is via HTTP Basic with a username and password provided by customersuccess@syniti.com. Provide the username and password in the Authorization header to authenticate your connection to the API.
curl https://api.syniti.com/v2 --user tapi_EXAMPLE:PASSWORD
Authenticating with invalid credentials will return 401 Unauthorized:
curl -i https://api.syniti.com/v2/categories --user badusername:badpassword
< HTTP/1.1 401 Unauthorized
Parameters
Many API endpoints of the Knowledge Tier 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/v2/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 /v2/terms endpoint will cause an error if passed as a cursor query parameter on the /v2/rules endpoint.
curl https://api.syniti.com/v2/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"], "endorse_status": "Candidate", "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 Tier API enforces rate limiting.
The API limits access to 50 requests per minute. With each request executed against the API, it will return the following headers to assist staying below the threshold:
| X-RateLimit-Limit | How many calls can be made in the time window. |
| X-RateLimit-Remaining | How many calls remaining in the time window. |
| X-RateLimit-Reset | The time at which the current rate limit window resets in UTC epoch seconds. |
When the number of requests per minute exceeds the maximum allowed, the API will return a 429 Error.
curl -i https://api.syniti.com/v2/categories --user tapi_EXAMPLE:PASSWORD
< HTTP/2 429 Too Many Requests
< Content-Type: text/plain; charset=utf-8
< X-Ratelimit-Limit: 50
< 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 Tier 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.
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.
