<aside> 💡 Use ctrl/cmd + k to search this document

</aside>

Index

Welcome to Octy's API. This API can be used to access all of Octy's retention toolchain API endpoints. The Octy API is organised around REST. All requests must be made over an SSL protocol.

All request and response bodies are JSON encoded, including errors.

Each response will be returned with:

a standard relevant HTTP status code.
a request meta-object within the response body itself.
- containing the status of the request (Success/Failure).
- and a friendly message.

Explore the Octy API with our Postman collection:

Collection Web View | Postman

Base URL

<https://api.octy.ai>

Version info

Octy API :  **v1**
Octy API build : **v6.0.3**

Resource prefix

Retention tool-chain api prefix : **/v1/retention/**

Authentication

2 API Keys, Public_key and Secret_key, are generated and sent to the account holder via email on the successful account creation. Requests are authenticated using HTTP basic access authentication. The Public Key must be provided as the basic authentication username and the Secret key must be provided as the basic authentication password. The Secret Key should be considered as a password as it allows full access to all account data and resource management and therefore must be kept secure and should only be shared with trusted, verified individuals/partners.

API Keys:

Public_key (username)
Secret_key (password)

Example API Keys

Public key
pk_9b2f17a3-4573-4a9b-9128-53ee910ef2

Secret key
sk_d93f42b9-b752-484f-9d5c-dafz98462c

Example Basic Auth token

-H Authorization :
Basic cGtfMmM5ZGU2YjNiYzQ3YjJiN2ZmNDBjYTA0NWJlNzY4YTY0ZjMwNDEyMDAzY2ZmMDQ0OTU0OWNiYjE1YTdjMjYxMGRkZjA6c2tfZjVhOTAxNjYzYjhkYzMyNDgyMDk5OTcwMjJlMGE2NTQxMjQ1NmVmNzM5NzA2YmE5NzQyYjk0YWUwZjI4MWEyNDUyOWQ=

🖥️ CLI Command

Errors

The Octy API returns errors with the relevant standard HTTP error status code (see below), a JSON encoded body describing the known errors and, where applicable, a link to find extended help for the error encountered. In most cases, resources can be created, updated, or deleted in batches.

To ensure single instances of invalid objects do not void the entire request, valid objects will be processed as expected. However, an error message, with the invalid object’s identifier, will be returned within one of the following lists, with the relevant response object.

Example:

"failed_to_create" :	[{"identifier" : "id_1234", "error_message": ""}]
"failed_to_update" :	[{"identifier" : "id_1234", "error_message": ""}]
"failed_to_delete" :	[{"identifier" : "id_1234", "error_message": ""}]

Error status codes:

400 Bad request

This error will be returned by the server due to user error or a malformed request.

401 Unauthorized

This error will be returned by the server if the request can not be authenticated or authorized due to invalid credentials or the account does not have the required permissions.

403 Forbidden

The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server.

404 Not found

The server can not find the requested resource. This means the URL is not recognized. This can also mean that the endpoint is valid but the resource itself does not exist.

405 Method not allowed

The request method is known by the server but is not supported by the target resource. For example, you may have attempted to make a GET request to a resource that supports POST requests only.

411 Length required

Server rejected the request because the Content-Length header field is not defined and the server requires it.

413 Entity too large

Request entity is larger than limits defined by server.

415 Unsupported media type

The media format of the requested data is not supported by the server, so the server is rejecting the request.

429 rate limit

Each resource on the Octy API has a fair usage limit applied restricted the total number of requests any single client can make per minute.

500 server error

From time to time, our servers may behave in an unexpected way. In the event that this happens the server will return a 500 server error. If you experience this frequently, please contact us [email protected]

501 Not implemented

The request method is not supported by the server and cannot be handled.

503 Service unavailable

The server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded.

Example Error object response

{
	"request_meta": {
	"request_status": "Failure",
	"message": "Bad Request"
	},
		"error": {
		"code": "400",
		"reason": "Invalid customer identifier provided",
		"errors": [
			{
				"error_message": "No customer profiles were found.",
				"extended_help": "<https://octy.ai/docs/profiles>"
			}
		]
	}
}

Pagination

To effectively reduce response times and object sizes for GET requests, the API utilizes pagination.

Currently, pagination is available on the following raw data objects & Octy object definition resources requests:

**GET** Profiles
**GET** Items
**GET** Event type definitions
**GET** Segment definitions
**GET** Message Template definitions

If no "?id" query string parameter is provided with any one of the above requests, a pagination cursor of type ‘string’, must be supplied within the header of the request. Requests that have a pagination cursor provided, will return up to 500 results in the response body along with the response header '-H cursor' containing the pagination cursor's current position to be used as the subsequent request’s '-H cursor' value.

Example:

'-H cursor : 0' - returns the first 499 results found
'-H cursor: 500' - returns all results between 500 and 999

Example pagination request

**GET** /v1/retention/profiles HTTP/1.1
Host: api.octy.ai
cursor: 0
Authorization: Basic ...