Skip to main content

API Reference


The Pangea service APIs are oriented around a JSON-RPC-like call. While not exactly mirroring JSON-RPC entirely, some general design philosophies are followed. A JSON-RPC-like request paradigm was chosen to ensure our APIs have a predictable, easy-to-understand, and secure method of use.

We have chosen to diverge from JSON-RPC for ease of use. Our specific differences are as follows:

  1. The action name and version are part of the URI and not a parameter in the JSON body.
  2. If only one record is requested, by ID, from a specified service, a GET request can be made with a REST-style request.

URI Structure

The Pangea URIs are designed to be predictable and easy to read.

POST: https://<service>.<csp>.<geo><version>/<resource>/<action>

  • <service>
    • The name of the Pangea service (for example, redact, audit, intelligence)
  • <csp>
    • The name of the CSP with which your Pangea project is configured (for example, aws, gcp)
  • <geo>
    • The geo with which your Pangea project is configured (for example, us, eu)
  • <version>
    • The version number of the API being called.
  • <resource>
    • optional The name of the resource against which action will be called (for example, user, IP, URL). Sometimes a resource is unnecessary to specify, in which case no resource will be provided and only action will be provided (see: audit:/log).
  • <action>
    • The action requested against the specified service (for example, create, geolocate, reputation)

Examples of URIs are:

  • Redact Text
  • Record an Audit Log event


Versioning is explicit in the URI path, as described in URI Structure.

Each Pangea service maintains its own version, and versions will only be changed when the new version is no longer backward-compatible with previous versions.


Pangea service APIs use service tokens to authenticate requests made. Each token can be limited to a specific service or can be enabled for use across multiple tokens. These tokens provide access to Pangea API services and data, so it is important to keep them secure. Never include your token in a publicly accessible repository, and be sure to rotate tokens regularly.

Authentication is performed via bearer auth.

-H "Authorization: Bearer <service_token>


Parameters are supplied via the POST body exception Requesting a single record. If a request is utilizing a provider-specific endpoint, a provider may be specified with provider-specific parameters.

"<parameter_name>": "<value>"
"providers": [
"name": "<provider_name>",
"<provider_specific_parameter>": "<value>"


Unless otherwise specified all requests will be first tried as synchronous requests. This means a request will be made against an endpoint and upon completion, a response will be returned containing the results of the request.

In some cases, an asynchronous request will be made. This means a request is made against an endpoint and an "in-progress" message will be returned to the client. The client will then need to use this request ID to check on the progress of the asynchronous request until it has been completed with a "success" or "failure" message.

There are two reasons for an asynchronous request.

  1. The response time has exceeded the response time threshold and has been converted to an asynchronous request.
  2. The endpoint has been specifically designated as an asynchronous endpoint. In this instance, all requests made to this endpoint will follow the asynchronous pattern.

All requests made for a single record using the record id will be performed as synchronous requests.

Status Codes

StatusStatus CodeDescription

An attempt was made to create a service config and it cannot be created.


An attempt was made to create an org and it cannot be created.


The provided IP Address was not found when accessing the resource


An operation completed successfully


The request has not yet completed. The result can be fetched from the async response endpoint when it is ready.


This indicates the resource should has moved temporarily


Token has multiple associated configs, config_id field is required.


The organization associated with this ID does not exist.


Project ID does not exist.


Tenant ID does not exist.


Invalid Token. Please regenerate the token for the project and service(s) if the error persists.


The provided config ID does not exist.


The operation failed


This indicates the config is missing an enable step or has a bad configuration that cannot lead to successful execution. Summary text should be provided


The provided config ID was not in the expected Pangea format.


Resource ID was not valid in the request.


Invalid JSON was passed. Pangea uses a format similar to JSON-RPC, and requires JSON for most requests.


Config ID is missing. Please regenerate the token for the project and service(s) if the error persists.


config_id parameter does not match configs associated with Token


A required header is missing. The summary field in the response will provide the specific header name.


Org ID is missing. Please regenerate the token for the project and service(s) if the error persists.


Project ID is missing. Please regenerate the token for the project and service(s) if the error persists.


Resource ID was not provided in the request.


The organization has not been initialized. Contact us at for more information.


The provided resource ID does not exist.


This route is not available on the pangea on-prem instance.


The service has not been enabled in the Pangea Console, so REST API access has been denied. Go to the [Pangea Console]({{ console_url }}) to enable the desired service.


The provided subscription ID does not exist.


Resource ID was not exepected in the request.


The provided request payload has validation errors. Look at the result in the payload for details.


You are out of credits for accessing the current endpoint.


You are forbidden from accessing this resource. Updating your tokens with the proper permissions may fix this problem.


You don’t have permission to access this resource. Updating your tokens with the proper permissions may fix this problem.


The URL passed in the request did not resolve to an existing resource.


The given HTTP Method was not allowed for this endpoint.


The resource is in conflict as it was modified elsehwere. Please refresh and try again.


The resource is in use and cannot be deleted.


An async response has been fetched more than the maximum amount of allotted times.


Your allowed number of requests exceeded within the given timeframe. This may vary from service to service.


There was an unexpected internal error in a Pangea service. This may be caused by an internal bug or outage. Contact us for support at


Some services use downstream third party providers that you can select to process data. There was an issue with the provider and not the Pangea service.


This indicates a Pangea service is experiencing an outage. Service should be restored quickly.

Synchronous Responses

A synchronous response will follow the structure shown below:

"request_id": "<request_id>",
"request_time": "<ISO 8601 timestamp>",
"response_time": "<ISO 8601 timestamp>",
"status": "<status>",
"summary": "<summary>",
"result": {
  • request_id
    • A unique id generated by Pangea to identify this request.
  • request_time
    • The time at which the request was received by Pangea.
  • response_time
    • The time at which Pangea sent a response back to the client.
  • status
    • The status of the request. If the request was successful "Success" is returned.
    • If the request failed, a short error code is returned (for example, "ValidationError").
  • summary
    • If the request was successful, the summary contains high-level details of the response.
    • If the request failed, the summary contains a more verbose error message.
  • result
    • If the request is successful, "result" contains all of the results data returned for this request.
    • If the request failed, the "result" will contain a detailed list of errors describing problems encountered with processing the request.

Asynchronous Responses

Asynchronous responses follow a similar structure to synchronous responses, but require an extra network request to get the result data.


Check out the asynchronous response page for an example of fetching asynchronous result data.

Was this article helpful?

Contact us