General API Information

Only use documented APIs

The APIs documented here are all available for your use subject to any constraints or limitations that may be described. If you find that these APIs are not sufficient for your use case, feel free to reach out to support@ovation.io for advice and so that we can consider improvements, if needed.

However, you may not use any other APIs that you may discover, such as (but not limited to) those called by the user interface but not documented here.

Base URL

Note that the documented URLs for all endpoints are preceded by a base URL, which is often implicit in the documentation.

For the sandbox environment (lab-sandbox.ovation.io), always start with https://lab-services-sandbox.ovation.io/api/v3

For the production environment (lab.ovation.io), always start with https://lab-services.ovation.io/api/v3

Authentication

Each call requires a Bearer token to be sent in the HTTP Authorization header.

For this, you need an "API key," which is generated in user settings in the application. (Select the User dropdown on top right of page and navigate to Settings and then to Security. From there, you can add an API key.)

API keys are specific to the environment. Create separate ones for use in sandbox and production.

The Bearer token is the API key preceded by the word "Bearer".

Failure to provide a valid API key will result in a 401 error from the endpoint.

Authorization

The API enforces the same permissions as the user interface as described in the Permissions Detail article. The permissions that apply are the ones held by the user that is associated with the API key that is passed as the Bearer token.

Conversion of JSON keys

JSON payloads that contain keys that are in PascalCase or camelCase will be converted, before processing, to snake_case. For example: KeyName and keyName will all be treated as if you had instead provided key_name . Some APIs may further translate these snake_case keys to some other format. See individual API documentation to see a description of any additional transformation.

Status Codes

Ovation's API returns status codes that follow the HTTP standard. Here are some of the codes returned:

Code	Meaning
200	Success
201	Success (in the case that an entity is created by the request)
401	Authentication failed Possible causes: An API key was not provided as the Bearer Token. The API key provided is revoked.
404	"Not found" In addition to the case where the endpoint is literally not available (consider a spelling error in your request), 404 is also returned when the user account does not have access to a relevant entity. For example, when attempting to GET a requisition with an API key linked to an account that does not have permission to access that requisition, the API will return a 404. 404 rather than 403 in this case is preferred for security purposes -- the API should not educate the caller as to which entities do and do not exist.
406	The request failed a requirement of the API, such as a missing required field or providing inconsistent values. The response message should indicate what the error is. 422 may sometimes be used instead.
422	This indicates that something is wrong with the request, often that the JSON is invalid. 422 may also be used in lieu of 406.
429	Too many requests were made too quickly so this one was rejected ("rate limited").