Skip to content

API Reference

The Falkonry 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.

Authentication

The API requests require token-based authentication. You can specify the Authorization HTTP header as Bearer <your-access-token> to authenticate and assume the user's permissions.

You can find your-access-token under API Tokens.

HTTP Codes

Falkonry APIs use conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate a TSI processing error.

Some 4xx errors that could be handled programmatically include an error message in the response.

HTTP Responses

Falkonry APIs return a JSON-encoded response. Following are the system managed properties that are also returned along with the requested object.

Property Use
tenant This is an account ID to which the returned object belongs.
type This is the type of the returned object. This is in format entities.<object_name>. For example: an Episode API response has type set as entities.Episode.
createTime This is the time when the returned object was created. This time is in epoch milliseconds.
updateTime This is the time when the returned object was updated. This time is in epoch milliseconds.
createdBy This is the user ID who created the returned object. For system-created objects, this is set as pod.
updatedBy This is the user ID who updated the returned object. For system-updated objects, this is set as pod.

Pagination

Using request parameters

To paginate through results, begin with an offset value of 0 and a limit value of N. To get the next page, set offset value to N, while the limit value stays the same. Subsequent pages start at 2N, 3N, 4N, and so on.

Note

It is recommended to use N = 50 in your implementation.

Using next-time in response

The next-time field in the response headers can be used to get more data. If reverse is set to true, set its value as the end parameter; otherwise set its value as the start parameter in the next request.

Using next in response

The next field in the response is to indicate that there is more data in the range and the mentioned endpoint can be used to get the following data.

API Versioning

Falkonry APIs are versioned to ensure backward compatibility and stability for your integrations. The API version must be specified directly within the URL path of your requests.

Format:

All API endpoints follow this structure: /api/{version}/{resource}

Example:

To access the accounts resource using the current version (1.3), your request URL will look like this:

GET https://<your-falkonry-domain>/api/1.3/accounts

When backward-incompatible changes are introduced to the API, a new version number will be released in the URL path. Older versions will then enter the 6-month deprecation period outlined in the API Deprecation & End-of-Life Policy below.

API Deprecation & End-of-Life Policy

APIs are deprecated when they are no longer actively supported or maintained. There are a variety of reasons, including:

  1. Security vulnerabilities: If an API is discovered to have a security vulnerability, it may be deprecated to protect you from potential attacks.
  2. Changes in technology: As technology evolves, APIs may need to be updated to keep up. If an API is not updated, it may become outdated and deprecated.
  3. Release of a new API with improved functionality: When a new API is released with improved functionality, the old API may be deprecated. This allows Falkonry to focus on supporting and maintaining the new API.

Falkonry follows a 6-month deprecation process for all APIs. The process begins when a new API is released that replaces the deprecated API or offers net new functionality.

API Deprecation Process:

  1. Release of a new API: A new API is released that replaces the deprecated API or offers net new functionality.
  2. Communication of deprecation: Falkonry communicates the API deprecation to you through the product update emails and updates the API documentation to notify you that the API is deprecated.
  3. 6-month deprecation period: You have 6 months to update the API usage and integrations.
  4. Retirement of the API: The deprecated API is retired and is no longer available. Attempting to call a retired API will result in a 404 HTTP response code.
  5. Removal of documentation: All documentation about the retired API and its versions is removed, and you are redirected to the new API documentation.

Note

During the deprecation period, Falkonry will communicate the deprecation to you through the product update emails and update the API documentation to notify you that the API is deprecated.