Skip to main content

API Reference

Overview

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>.pangea.cloud/<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
    • https://redact.aws.us.pangea.cloud/v1/redact
  • Record an Audit Log event
    • https://audit.aws.us.pangea.cloud/v1/log

Versioning

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.

Authentication

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

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>"
}
]
]

Responses

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
CantCreateConfig200

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

CantCreateOrg200

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

IPNotFound200

The provided IP Address was not found when accessing the resource

Success200

An operation completed successfully

Accepted202

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

TemporaryRedirect307

This indicates the resource should has moved temporarily

AmbiguousConfigID400

Token has multiple associated configs, config_id field is required.

BadOrgID400

The organization associated with this ID does not exist.

BadProjectID400

Project ID does not exist.

BadTenantID400

Tenant ID does not exist.

ConfigIDMismatch400

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

ConfigNotExist400

The provided config ID does not exist.

Failure400

The operation failed

InvalidConfig400

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

InvalidConfigID400

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

InvalidResourceID400

Resource ID was not valid in the request.

JSONDecodingError400

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

MissingConfigID400

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

MissingConfigIDScope400

config_id parameter does not match configs associated with Token

MissingHeader400

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

MissingOrgID400

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

MissingProjectID400

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

MissingResourceID400

Resource ID was not provided in the request.

OrgNotInitialized400

The organization has not been initialized. Contact us at support@pangea.cloud for more information.

ResourceNotExist400

The provided resource ID does not exist.

RouteNotAvailableOnPrem400

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

ServiceNotEnabled400

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.

SubscriptionNotExist400

The provided subscription ID does not exist.

UnexpectedResourceID400

Resource ID was not exepected in the request.

ValidationError400

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

NoCredit402

You are out of credits for accessing the current endpoint.

Forbidden403

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

Unauthorized403

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

NotFound404

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

MethodNotAllowed405

The given HTTP Method was not allowed for this endpoint.

Conflict409

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

ResourceInUse409

The resource is in use and cannot be deleted.

Gone410

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

TooManyRequests429

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

InternalError500

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 support@pangea.cloud.

ProviderError500

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.

ServiceNotAvailable503

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": {
<result_data>
}
}
  • 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.

tip

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

Was this article helpful?

Contact us