Skip to main content

Aware App REST API Concepts

Aware has multiple, external APIs that allow customers to integrate their new and existing systems with Aware application capabilities. These are REST APIs that are targeted toward backend integrations for adding, querying, updating, and deleting Aware data.

Aware’s APIs are built around its main architectural components. The APIs are designed to be independently extendable, with more APIs added as needed; and each having one or more endpoints. Aware currently supports an API for the following functional areas or apps:

  • Data Hold
  • Search (User Content Exports only)
  • Signal
  • Audit Logs
  • Platforms

This guide describes the general formats of Aware’s REST API requests and responses, how to use their endpoints, and common behaviors and responses. It is intended for use by software developers and managers who develop applications and systems that access Aware’s features and data. Specific details, for any given API endpoint, are described in an endpoint-specific reference guide.

note

We assume that you are at least somewhat familiar with REST APIs and with Aware’s security concepts and data. For completeness, this guide assumes that you have access to all Aware APIs, features, and data, although this may not be true for all consumers or users.

Aware API architectural model​

The Aware platform currently supports several risk and business intelligence applications, with others planned for the future. These apps use REST APIs to interact with the Aware backend that ingests, normalizes, enriches, analyzes, and securely stores message content, and makes message contents, properties, and conversation context available to authorized consumers.

Three of these apps--Signal, Data Hold, and Audit Logs--use backend REST APIs that complement the user interface capabilities so customers can integrate them into their systems and applications. These APIs are new and evolving; new APIs and endpoints are being developed for these and other Aware applcations.

In addition to application APIs, Aware has two other types of APIs in the planning and design stages: a meta-level API for accessing enriched data, and an ingestion-level API to facilitate importing new sources of data.

API tokens​

All API endpoints are protected by a customer-specific API token (or just token for short) that you provide in the request header. You use the same token to access all API endpoints your organization is authorized to use.

Any given organization can have only one API token, for a given environment, that must be shared by all authorized applications. If a token is replaced (for example, when an admin leaves the organization, or as part of a routine security procedure), the new token must be used for subsequent API calls.

Tokens do not expire; they persist until they are manually replaced or revoked. They can only be created, retrieved, replaced, or revoked by an Aware Administrator using the Aware GUI. If a token is replaced, it becomes obsolete and the new token must be used. If a token is revoked, it immediately becomes obsolete and cannot be used. API requests that use a replaced or revoked token receive a 403 (Forbidden) response.

The Aware GUI does not rely on API tokens for its interactions with the server; API tokens are only used for API requests sent by applications.

Creating and managing a token​

Only an Aware Admin can perform these functions.

To get an existing token​
  1. Navigate to https://aware.work and select System Settings > Integrations to open a System Settings page.
  2. Scroll down to the API Token section near the bottom of the page, and click Copy Token.
To create a token​
  1. Navigate to https://aware.work and select System Settings > Integrations to open a System Settings page.
  2. Scroll down to the API Token section near the bottom of the page, and click + API Token.
  3. Select the APIs you would like the token to have access to.
  4. Press Add API Token.
To revoke a token​
  1. Navigate to https://aware.work and select System Settings > Integrations to open a System Settings page.
  2. Scroll down to the API Token section near the bottom of the page, and click the X button to the right of the token you wish to revoke.

Using a token​

Anyone who has your organization’s token can use it.

Include your organization’s token in the HTTP X-Aware-Api-Key header, for each API request, to authenticate your request and authorize access to your resources. For example, this statement calls the Signal Event list endpoint to get recent events.

curl -X POST --location "https://api.aware.work/external/signal/events/v1 \
    -H "X-Aware-Api-Key: ${API_TOKEN}" \
    -H "Content-Type: application/json" \
    -d "{}"

Token-specific errors:

  • 401 Unauthorized: Invalid, replaced, or revoked API token

Aware URLs​

Common responses​

Common success responses​

  • 200 (OK) - The requested operation was successful. (Note: This doesn’t necessarily mean that it returned meaningful results. For example, GET requests return 200 even if they return no results.)

Common error responses​

  • 400 (Bad Request) - The request was invalid, corrupted, or timed out.
  • 401 (Unauthorized) - The specified API token is invalid, replaced, or revoked.
  • 403 (Forbidden) - The specified API token is invalid, replaced, or revoked.
  • 404 (Not Found) - The version, API, or endpoint is invalid. (Programming error)
  • 405 (Method Not Allowed) - The method is not supported by the endpoint, such as PUT used for a read-only endpoint. (Programming error)
  • 415 (Unsupported Media Type) - The payload is in an unsupported format, or the specified Content-Type or Content-Encoding is not supported. (Programming error)
  • 429 (Too Many Requests) - The rate at which API requests are being received, for the current organization, is too high. See Request timeouts below for recovery suggestions.
  • 500 (Internal Server Error) - The server encountered an unexpected condition.
  • 502 (Bad Gateway) - The server failed to receive a successful response from an upstream server.
  • 503 (Service Unavailable) - The server is down for maintenance or is overloaded. See System unavailable below for recovery suggestions.
  • 504 (Gateway Timeout) - The server did not receive a response from an upstream server.

System unavailable​

Aware periodically takes the system down, for short periods of time, for maintenance and upgrades. During these times, it cannot accept or process incoming requests.

If the system is temporarily unavailable, Aware responds with an HTTP 503 (Service Unavailable) status. It continues this until it is available again.

If your application receives a 503 response, it should delay 30-60 seconds and then retry the request (to help prevent swamping the server with retry requests). It should repeat this sequence until it receives a different response.

If the system is taken down after a request is submitted, the server typically responds with an HTTP 500 (Internal Server Error) or 503 (Service Unavailable), depending on whether the request had been authenticated and was in progress at the time (500), or had not yet been authenticated (503).

If your application receives a 500 response, there is no obvious way for it to find out what happened. It is always safe to retry a GET request, and generally safe to retry a POST and PUT request (again after a 30-60 second delay).

Periods of unavailability typically last only a few minutes. However, applications should be capable of handling longer periods of unavailability. The most appropriate strategy for lengthy outages depends on the application.

Request timeouts​

All API endpoints are subject to max duration limits to protect customers from adversely impacting each other, and to protect users from runaway processes. Max durations limit the time for an endpoint request to complete (such as a call cannot exceed 3 seconds).

Max durations may vary per endpoint, and will be adjusted over time as the system is tuned, based on API usage patterns and API evolution.

If a request times out, Aware responds with a 400 (Bad Request) error.

Resource not found​

If an endpoint is not recognized, Aware returns a 404 (Not Found) response. Individual endpoints may return a 404 if a referenced object (such as a referenced Data Hold ID) does not exist. See individual API endpoint reference guides for more information.

Internal server error​

If a request fails due to an unspecified processing error, Aware returns a 500 (Internal Server Error) response. One cause of this can be if the system is taken down while a long-running request is active (see System unavailable), but there can be others. Aware can also return 502 (Bad Gateway) and 504 (Gateway Timeout) errors.

The correct response for all of these is to delay for 30-60 seconds, and then retry. If the problem persists for longer than 15 minutes, contact your Customer Success representative.