> ## 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.

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](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.

## Authentication

Unlike the API-key based products of the platform, Specter authenticates every request with a signed JSON Web
Token (JWT) passed as a bearer token in the `Authorization` header. This OAuth2 bearer scheme complements the
API keys used elsewhere today and is set to become the platform-wide standard — 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.