API Information

This reference is essential for understanding Specter — the pre-authorization fraud decision service of the Hellgate Cloud Platform — and integrating with it successfully. Specter APIs make use of RESTful conventions where it makes sense. All calls use the standard HTTP verbs to express access semantics, like GET, POST, PATCH, and DELETE. Other related conventions are described below.

JSON Conventions

Resources are addressable by a UUID id property.
Property names are always in snake_case.
Temporal data is encoded in ISO 8601 strings.
Monetary amounts are integers in the minor units of the transaction currency (e.g. 14999 = €149.99).
Currencies are ISO 4217 codes.

Authentication

Specter authenticates every request with a signed JSON Web Token (JWT) passed as a bearer token in the Authorization header. This OAuth2 bearer scheme is the standard across the Hellgate Cloud Platform services — see Authentication.

curl --header 'Authorization: Bearer <token>' \
  --request POST 'https://my-instance.eu1.on-hellgate.cloud/api/decisions'

Tokens carry scopes that gate access to individual endpoints, and are validated against your instance’s audience on each request. See Authentication for the full scope reference. Tokens must be handled with care and kept secure. Never hardcode them in your source code — keep them solely on your backend systems.

API Use

Instance URL

Specter is provided as a service of the Hellgate Cloud Platform implementing the Composable Payment Architecture (CPA). Each instance is accessible at a unique host:

https://{instance}.eu1.on-hellgate.cloud

{instance} is your unique instance slug and eu1 is the current environment; both are provided during onboarding.

Pagination

Endpoints that return lists of objects support pagination. Specter uses cursor-based pagination with the following query parameters:

Parameter	Type	Description
`limit`	`integer`	The maximum number of objects returned per request. Default is 20.
`after`	`string`	A pagination cursor. Pass the cursor from the previous page to fetch the next one.

Example request:

curl --header 'Authorization: Bearer <token>' \
  'https://my-instance.eu1.on-hellgate.cloud/api/admin/rulesets?limit=10&after=08f4b968-259a-4989-b5ab-09ef9414f983'

The response wraps the results in data and includes a links object for paging forward:

{
  "data": [],
  "links": {
    "next": "https://my-instance.eu1.on-hellgate.cloud/api/admin/rulesets?limit=10&after=605d229d-fc8a-4017-b115-2e606031bd79"
  }
}

When there are no further pages, links.next is null.

Request Errors

Specter uses standard HTTP status codes to indicate client errors on the API level.

Errors - HTTP 4xx
Validation Errors - HTTP 422

The response payload for processing errors follows a standard format.

{
  "classifier": "NOT_FOUND",
  "code": 404,
  "message": "The requested resource does not exist"
}

Field	Description
`classifier`	A machine-readable classifier for the error.
`code`	The HTTP status code, repeated in the body.
`message`	A human-readable description.

Validation errors follow a standard format that includes the individual field errors.

{
  "classifier": "VALIDATION_ERROR",
  "code": 422,
  "validation_errors": [
    {
      "path": "limit",
      "message": "must be a positive integer"
    }
  ]
}

Common classifiers:

Status	Classifier	When
`401`	`UNAUTHORIZED`	No valid authentication was provided.
`403`	`FORBIDDEN`	The token lacks the scope required for the operation.
`404`	`NOT_FOUND`	The requested resource does not exist.
`409`	`CONFLICT`	The request conflicts with the current state (e.g. resolving an already-resolved decision).
`422`	`VALIDATION_ERROR`	The request failed validation.

Security Considerations

Specter evaluates sensitive payment data and requires strict security practices:

All communication must use HTTPS.
Bearer tokens must be stored securely and never exposed to clients.
The full PAN supplied in a decision request is used only for evaluation and fingerprinting — it is never persisted.

Getting Started

Decisions

Lifecycle Events

Admin

JSON Conventions

Authentication

API Use

Instance URL

Request Errors

Security Considerations

​JSON Conventions

​Authentication

​API Use

​Instance URL

​Pagination

​Request Errors

​Security Considerations

JSON Conventions

Authentication

API Use

Instance URL

Pagination

Request Errors

Security Considerations