API Information

This reference is essential for understanding and integrating with Specter. Specter is the decision engine of the Hellgate Cloud Platform, built for pre-authorization fraud decisions and for rules over any payload you declare. 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.

Empty Strings and Omitted Fields

The empty string is not a value. A string field is either omitted or present with a real value — and where a field is nullable, an explicit null unsets it. Never send "". Where a field is validated as a string, "" is rejected with 422 Unprocessable Entity and a field error on that path (see Request Errors for the response format). Not every field carries that validation, so do not treat the rejection as a safety net: where it is absent, "" is accepted and then stored or forwarded verbatim — an empty string travels further into a request than a missing field ever does. In Specter, omission also shapes the evaluation itself. A field you omit — or send as null — resolves to absent in $.-path rule conditions: every predicate over it abstains, neq and not_in included, so a “not equal” rule never fires on data you never sent. An empty string or empty array counts as present. Omission also changes derived values: a masked_pan credential sent without expiry_month and expiry_year yields a different credential_fingerprint than the same card sent with them, so velocity counts and blacklist entries keyed on $.credential_fingerprint do not line up across the two.

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 IDs

Every response carries an x-request-id header. Send your own UUID in the same header to correlate requests with your logs, and include the ID when you contact support. See Request IDs.

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 never persisted. It is used for evaluation and fingerprinting and forwarded to the backends your rulesets invoke — see what a backend receives.

Data Classification

Fields that carry regulated data are marked with a classification pill next to the parameter name in this reference. The marker tells you what kind of data the field holds, so you can see at a glance which parts of a payload attract handling obligations before you write any code against them.

Marker	The field carries
pci-pan	The primary account number — a card number, or a value from which one can be reconstructed.
pci-sad	Sensitive authentication data — security codes and the equivalent authentication values issued for a token.
pii	Personal data under the GDPR — any information relating to an identified or identifiable person, not only the cardholder.

Most fields carry no marker at all. The absence of one is a statement that the field holds none of the categories above — not that the field has yet to be reviewed. Masked and truncated card numbers are the common example: 411111 •••••• 1111 identifies nobody on its own, so it carries no marker. The marker is also a gate, not just a label. Sending values into pci-pan or pci-sad fields requires your PCI DSS certification on file at SAQ-D or a full Report on Compliance (RoC). Sending personal data into pii fields requires a data processing agreement (DPA) between us. Contact support@hellgate.io to put either in place or to learn more.

Getting Started

Decisions

Lifecycle Events

Admin