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)
• <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

Status	Status Code	Description
CantCreateConfig	200	An attempt was made to create a service config and it cannot be created.
CantCreateOrg	200	An attempt was made to create an org and it cannot be created.
IPNotFound	200	The provided IP Address was not found when accessing the resource
Success	200	An operation completed successfully
Accepted	202	The request has not yet completed. The result can be fetched from the async response endpoint when it is ready.
TemporaryRedirect	307	This indicates the resource should has moved temporarily
AmbiguousConfigID	400	Token has multiple associated configs, config_id field is required.
BadOrgID	400	The organization associated with this ID does not exist.
BadProjectID	400	Project ID does not exist.
BadTenantID	400	Tenant ID does not exist.
ConfigIDMismatch	400	Invalid Token. Please regenerate the token for the project and service(s) if the error persists.
ConfigNotExist	400	The provided config ID does not exist.
ConfigProjectMismatch	400	Config being used belongs to a different project.
Failure	400	The operation failed
InvalidConfig	400	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
InvalidConfigID	400	The provided config ID was not in the expected Pangea format.
InvalidResourceID	400	Resource ID was not valid in the request.
JSONDecodingError	400	Invalid JSON was passed. Pangea uses a format similar to JSON-RPC, and requires JSON for most requests.
MissingConfigID	400	Config ID is missing. Please regenerate the token for the project and service(s) if the error persists.
MissingConfigIDScope	400	config_id parameter does not match configs associated with Token
MissingHeader	400	A required header is missing. The summary field in the response will provide the specific header name.
MissingOrgID	400	Org ID is missing. Please regenerate the token for the project and service(s) if the error persists.
MissingProjectID	400	Project ID is missing. Please regenerate the token for the project and service(s) if the error persists.
MissingProjectSettings	400	Project settings missing.
MissingResourceID	400	Resource ID was not provided in the request.
MultipleProjectIDs	400	Configs belong to different projects. Please use configs belonging to the same project.
OrgNotInitialized	400	The organization has not been initialized. Contact us at support@pangea.cloud for more information.
PreferenceNotExist	400	The provided user ID preference does not exist.
ProjectSettingsNotEnabled	400	Project settings not enabled.
ResourceNotExist	400	The provided resource ID does not exist.
RouteNotAvailableOnPrem	400	This route is not available on the pangea on-prem instance.
ServiceNotEnabled	400	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.
SubscriptionNotExist	400	The provided subscription ID does not exist.
UnexpectedResourceID	400	Resource ID was not exepected in the request.
ValidationError	400	The provided request payload has validation errors. Look at the result in the payload for details.
NoCredit	402	You are out of credits for accessing the current endpoint.
Forbidden	403	You are forbidden from accessing this resource. Updating your tokens with the proper permissions may fix this problem.
Unauthorized	403	You don’t have permission to access this resource. Updating your tokens with the proper permissions may fix this problem.
NotFound	404	The URL passed in the request did not resolve to an existing resource.
MethodNotAllowed	405	The given HTTP Method was not allowed for this endpoint.
Conflict	409	The resource is in conflict as it was modified elsehwere. Please refresh and try again.
ResourceInUse	409	The resource is in use and cannot be deleted.
Gone	410	An async response has been fetched more than the maximum amount of allotted times.
TooManyRequests	429	Your allowed number of requests exceeded within the given timeframe. This may vary from service to service.
InternalError	500	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.
ProviderError	500	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.
ServiceNotAvailable	503	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