> ## Documentation Index
> Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Information

> Essential information for using the Specter API.

export const RunInPostman = ({uid, title, workspace, children}) => <Card title={title || "Run in Postman"} icon="right-from-bracket" href={`https://www.postman.com/sf-hellgate/${workspace}/collection/${uid}`}>
    {children}
  </Card>;

This reference is essential for understanding Specter — the pre-authorization fraud decision service of the
Hellgate Cloud Platform — and integrating with it successfully.

<RunInPostman uid="32200380-116c0b86-f275-46b5-9392-e3d3028e68d8" workspace="hellgate-documentation" title="Specter API in Postman">
  Every endpoint on this reference, generated from the same OpenAPI specification and grouped exactly as the
  navigation here. Duplicate the **Dedicated instance — template** environment and set `instance` and `env`.
  The Authorization tab is pre-configured for the OAuth2 client-credentials grant, so add `clientId`,
  `clientSecret`, `audiences` and `scopes` to the environment and hit **Get New Access Token**. Both
  `audiences` and `scopes` are space-delimited lists — name every instance the token may call. See
  [Authentication](/platform/authentication).
</RunInPostman>

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](https://en.wikipedia.org/wiki/ISO_8601) strings.
* Monetary amounts are integers in the **minor units** of the transaction currency (e.g. `14999` = €149.99).
* Currencies are [ISO 4217](https://en.wikipedia.org/wiki/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](#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. An omitted field resolves to `null` in `$.`-path
[rule conditions](/products/specter/concepts/rule-engine): `eq`, `in`, and the ordering comparisons are all
false against it, but `neq` and `not_in` are **true** — a "not equal" rule fires on data you never sent.
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](/platform/authentication).

```bash theme={null}
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](/products/specter/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)](/platform/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:

```bash theme={null}
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:

```json theme={null}
{
  "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.

<Tabs>
  <Tab title="Errors - HTTP 4xx">
    The response payload for processing errors follows a standard format.

    ```json theme={null}
    {
      "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.                |
  </Tab>

  <Tab title="Validation Errors - HTTP 422">
    Validation errors follow a standard format that includes the individual field errors.

    ```json theme={null}
    {
      "classifier": "VALIDATION_ERROR",
      "code": 422,
      "validation_errors": [
        {
          "path": "limit",
          "message": "must be a positive integer"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

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.