API's Overview

The Toucan API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication and verbs.

Organization of the documentation

---

The documentation is divided into three sections:

• The present Overview section presents general concepts that clarify and illuminate around particular topics.
• The Guides section includes tutorial lessons that allow the reader to understand a key concept of the documentation through a series of steps to - complete a particular project
• The API Reference section is an exhaustive technical description of our machinery including routes, payload and response samples.

Root endpoint

---

The root endpoint of the API is https://api-<instance>.toucantoco.com/<version>/ where <instance> represents your Toucan tenant, for example the API root endpoint of https://demo.toucantoco.com tenant is https://api-demo.toucantoco.com/<version>/ where <version> represents the API version you are aiming. For more information information about versioning see this section

Schema

---

All API access is over HTTPS, and accessed from https://api-<instance>.toucantoco.com/<version>. All data is sent and received as JSON.

$ curl -I https://api-demo.toucantoco.com/<version>
 > HTTP/2 200
 > date: Thu, 09 Jun 2022 08:56:34 GMT
 > content-type: application/json
 > content-length: 36
 > x-robots-tag: noindex, nofollow, noarchive, noodp
 > cache-control: no-store
 > access-control-allow-credentials: true
 > strict-transport-security: max-age=31536000; includeSubDomains;
 > tc-backend: docker-mutual-05
 > x-xss-protection: 1; mode=block
 > x-content-type-options: nosniff
 > referrer-policy: strict-origin-when-cross-origin
 > content-security-policy: frame-ancestors *

Blank fields are included as null instead of being omitted.

All timestamps return in UTC time, ISO 8601 format:

2022-01-01T09:30:00.000Z

For more information about timezones in timestamps see this section

Parameters

---

Many API methods take optional parameters. For GET requests, any parameter not specified as a segement in the path can be passed as a HTTP query string parameter:

$ curl -i "https://api.<instance>.toucantoco.com/<version>"
> {"version": "0.0.1"}

For POST, DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of 'application/json':

HTTP verbs

---

Where possible, our API strives to use appropriate HTTP verbs for each action.

Verbs	Description
GET	Used for retrieving resources.
POST	Used for creating resources.
PUT	Used for updating resources with partial JSON data.
DELETE	Used for deleting resources.

HTTP redirects

---

API uses HTTP redirection where appropriate. Clients should assume that any request may result in a redirection. Receiving an HTTP redirection is not an error and clients should follow that redirect. Redirect responses will have a Location header field which contains the URI fo the resources to which the client should repeat the requests.

Status Code	Description
301	Permanent redirection. The URI you used to make the request has been replaced by the one specified in the Location header field. This and all future request to this resource should be directed to the new URI.
302, 307	Temporary redirection. This request should be repeated verbatim to the URI specified in the Location header field but clients should continue to use the original URI for future requests.

Other redirection status codes may be used in accordance with the HTTP 1.1 spec.

Rate limiting

---

API requests are subject to different rate limits.

Timezones

---

All dates are transmitted in the standard ISO 8601 format.

For example:

• 2020-01-04 corresponds to January 4, 2020
• 2020-01-04T13:30:00z corresponds to November 5, 1994, 8:15:30 AM, US Eastern Standard Time.