Covenant Eyes Developer Portal

Getting Started

Getting Started Directory

  1. Introduction
  2. Terminology
  3. Client Keys vs. User Keys
  4. Converting to JSON and XML


Here are some things that you might want to know as you start looking into Covenant Eyes APIs.


Covenant Eyes APIs are built in REST format.


  • All API access is over HTTPS and is accessed from the domain.
  • Responses are sent and received through JSON and XML (unless otherwise noted).
  • Payloads are presented in Python for conversion into JSON and XML.
  • All timestamps are returned in ISO 8601 format.


Our apis use the HTTP Basic authentication method. Before transmitting your request, append the username with a colon and concatenate it with the password. This string is encoded with the Base64 algorithm, which is transmitted in the HTTP header and then decoded by the receiver.

Example: curl

Client keys are required to get keys for specific users.

How do I get client keys?

Contact us at to get client keys.

HTTP Verbs

Valid HTTP methods are GET, POST, PUT and DELETE.

For more information on keys, visit the Client Keys vs. User Keys section.

Common Calls

  • GET: Used for information gathering.
  • POST: Used for calls that change the state of the system.

Default Response Structure

Sample responses are shown in Python object templates.

{'result': {'records': '<[records]|record|[]>', 'meta': {
'message': ('Optional', '<error message if any>'),
'status': '<Success|Failure> OR <a descriptive identifier of the error>',
'executionTime': ('Optional', '<hh:mm:ss.uuuuuu>')}}}

Client Errors

Error messages are found in the response under ‘message’ and ‘status’.

Here is an example of a error that came back as a 403:

{"result": {"records": null, "meta": {"status": "Failure", "executionTime": "0:00:00.017605", "message": "FORBIDDEN"}}}

While a success message that comes back as a 200 will look like so in the “meta” section:

"meta": {"status": "Success", "executionTime": "0:00:00.029015"}}}

Next: Terminology