---
title: "REST API Reference"
description: "HTTP endpoint reference for XI Parallax: registration, slots, look-up, published records, manifests, take-down and account stats."
published: 2026-09-23T10:54:42.924706+00:00
updated: 2026-09-23T10:54:42.924706+00:00
tags: ["api", "parallax", "reference", "rest"]
url: https://xiobjects.com/docs/xio/parallax/rest-api/reference
source: XI Objects
---

<!-- xion:doctype xion+markdown -->
<!-- xion:metadata
{
  "version": "1.0",
  "content_type": "application/xion\u002Bmarkdown",
  "source_type": "xi-content/doc",
  "generator": "xio-content-publisher/1.0.0",
  "generated": "2026-09-23T10:54:38.0129319\u002B00:00",
  "encoding": "utf-8",
  "render_intent": "markdown",
  "title": "REST API Reference",
  "slug": "xio/parallax/rest-api/reference",
  "copyright": "\u00A9 2026 XI Objects Inc"
}
-->

# REST API Reference

Every endpoint XI Parallax publishes to an account holder, with its request fields, its response shape and the statuses it answers.

## Setup

Base URL: `https://api.parallax.xiobjects.com`

Authenticate with the beta token an operator minted for your account:

```bash
export BASE="https://api.parallax.xiobjects.com"
export TOKEN="your-beta-token"

curl -sS "$BASE/account/stats" -H "Authorization: Bearer $TOKEN"
```

Every route except `GET /health` requires `Authorization: Bearer <token>`. Missing, malformed, unknown and revoked tokens all answer `401 Unauthorized` with no detail about which it was. The token resolves to your account, which is never expressible as a route parameter, a query-string value or a body field.

Check the service with `GET /health`. It takes no token.

The generated OpenAPI document is published at `https://api.parallax.xiobjects.com/openapi/v1.json`. It takes no token and answers a cross-origin GET, so a browser based viewer can load it by URL.

Every refusal answers `application/problem+json`. See [Errors and refusals](/docs/xio/parallax/rest-api/errors-and-refusals) for the envelope, every status, and every refusal reason.


## GET /health

Service identity and version. Takes no token.

**Response: 200 OK**

```json
{
  "service": "Xio.Parallax.Rest",
  "version": "1.0.0"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `service` | `string` | The service's own name. |
| `version` | `string` | The running build's version. |

---

## Endpoints

### Service

GET /health is described above, under Setup.

| Method | Route | Scope | Description |
|--------|-------|-------|-------------|
| `GET` | `/health` | none | Service identity and version |

### Registrations

Endpoint detail: [Registrations](/docs/xio/parallax/rest-api/reference/registrations).

| Method | Route | Scope | Description |
|--------|-------|-------|-------------|
| `POST` | `/registrations` | account token | Register one image synchronously |
| `DELETE` | `/registrations/{registrationId}` | account token | Take one of your registrations down |

### Registration slots

Endpoint detail: [Registration slots](/docs/xio/parallax/rest-api/reference/registrations).

| Method | Route | Scope | Description |
|--------|-------|-------|-------------|
| `POST` | `/slots` | account token | Open a registration slot |
| `GET` | `/slots/{slotId}` | account token | Report one slot |
| `DELETE` | `/slots/{slotId}` | account token | Abandon a slot and everything in it |
| `POST` | `/slots/{slotId}/uploads` | account token | Upload images into the slot |
| `POST` | `/slots/{slotId}/uploads/missing` | account token | Resume: which declared hashes the slot lacks |
| `GET` | `/slots/{slotId}/manifest` | account token | Report the slot's entries |
| `PUT` | `/slots/{slotId}/entries/{imageHash}/manifests` | account token | Replace one entry's manifest list |
| `DELETE` | `/slots/{slotId}/entries/{imageHash}` | account token | Remove one entry |
| `POST` | `/slots/{slotId}/commit` | account token | Register everything held. Terminal |
| `GET` | `/slots/{slotId}/progress` | account token | Per entry state and the poll counts |

### Look-up

Endpoint detail: [Look-up](/docs/xio/parallax/rest-api/reference/look-up).

| Method | Route | Scope | Description |
|--------|-------|-------|-------------|
| `POST` | `/lookup` | account token | Look one image up synchronously |

### Look-up slots

Endpoint detail: [Look-up slots](/docs/xio/parallax/rest-api/reference/look-up).

| Method | Route | Scope | Description |
|--------|-------|-------|-------------|
| `POST` | `/lookup/slots` | account token | Open a look-up slot |
| `DELETE` | `/lookup/slots/{lookupSlotId}` | account token | Abandon a look-up slot and everything in it |
| `POST` | `/lookup/slots/{lookupSlotId}/queries` | account token | Upload query images into the slot |
| `POST` | `/lookup/slots/{lookupSlotId}/queries/missing` | account token | Resume: which declared hashes the slot lacks |
| `GET` | `/lookup/slots/{lookupSlotId}/manifest` | account token | Report the slot's held queries |
| `DELETE` | `/lookup/slots/{lookupSlotId}/entries/{imageHash}` | account token | Remove one held query |
| `POST` | `/lookup/slots/{lookupSlotId}/commit` | account token | Look every held query up. Terminal |
| `GET` | `/lookup/slots/{lookupSlotId}/progress` | account token | Per query state and the poll counts |
| `GET` | `/lookup/slots/{lookupSlotId}/results` | account token | Read the verdicts back |

### Published records

Endpoint detail: [Published records](/docs/xio/parallax/rest-api/reference/records).

| Method | Route | Scope | Description |
|--------|-------|-------|-------------|
| `GET` | `/records/{originalImageHash}` | account token | Recover one image's manifests and its verification material |
| `POST` | `/records` | account token | Recover the records for a list of original image hashes |

Any token holder may read any image's record, whoever registered it.

### Account

Endpoint detail: [Account](/docs/xio/parallax/rest-api/reference/account).

| Method | Route | Scope | Description |
|--------|-------|-------|-------------|
| `GET` | `/account/stats` | account token | Grants, consumed, held, remaining, and lifetime call count |

Administrative routes under `/admin` are not part of this collection. An operator uses them to create your account and mint your token.

## Shared shapes

The manifest, the published record, the upload outcome, the slot entry and the progress report are described once, on [Shared Shapes](/docs/xio/parallax/rest-api/reference/shapes).
<!-- xion:trust
{
  "v": 1,
  "canon_v": 1,
  "ctx": "xiobjects.com/content",
  "hash_blake3_hex": "7f8543117a74b0e024b7a84184ce604a65578ec793631149447fec03dbaf7cc9",
  "hash_sha256_hex": null,
  "sig_alg": "ed25519",
  "sig_b64": "XED0afCYzUWgvO9-P4XpXsCoBc119Ibd85iMajlMXjVavZudFcZhXtEsOI2ccMpfuDBHtbdNP1q_zzHHYrKCCg",
  "pubkey_b64": "qvdEfSxeAWQCSmFhYZ6YX5kI935su0PASlrB7Yi2nJ8",
  "x509_chain_pem": [
    "-----BEGIN CERTIFICATE-----\r\nMIIB9TCCAaegAwIBAgIRAMAcad\u002BzF5t\u002B/s4nONSc6aAwBQYDK2VwMC4xLDAqBgNV\r\nBAMMI1hJIE9iamVjdHMgSW5jIENvbnRyb2wgSW50ZXJtZWRpYXRlMB4XDTI2MDky\r\nMzA0MTAzMFoXDTI2MTAyMzA0MTAzMFowSzEeMBwGA1UEAwwVeGlvLWNvbnRlbnQt\r\ncHVibGlzaGVyMRcwFQYDVQQKDA5YSSBPYmplY3RzIEluYzEQMA4GA1UECwwHQ29u\r\ndGVudDAqMAUGAytlcAMhAKr3RH0sXgFkAkphYWGemF\u002BZCPd\u002BbLtDwEpawe2Itpyf\r\no4G8MIG5MAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoG\r\nCCsGAQUFBwMkMGUGA1UdIwReMFyAFDspt5hZsP6rNX4Cq7owpMYa05OyoS6kLDAq\r\nMSgwJgYDVQQDDB9JbnN0aXR1dGUgb2YgUHJvdmVuYW5jZSBSb290IENBghRSYDf4\r\nsUJ\u002B9h\u002Bod0\u002BZRK/X/JSUBTAdBgNVHQ4EFgQUg7Gut2vWupuiLVcKgZt1GwdYmggw\r\nBQYDK2VwA0EA1cI0DTLhDQyTflrGrMlnMT/3Iw2c1OXVYphjr0uXnCmX1Dt5sNYT\r\niTgydyG3BPQqqiZ253V1ltTxT68ZA2gNAg==\r\n-----END CERTIFICATE-----\r\n",
    "-----BEGIN CERTIFICATE-----\r\nMIIByDCCAXqgAwIBAgIUUmA3\u002BLFCfvYfqHdPmUSv1/yUlAUwBQYDK2VwMCoxKDAm\r\nBgNVBAMMH0luc3RpdHV0ZSBvZiBQcm92ZW5hbmNlIFJvb3QgQ0EwHhcNMjUxMTAy\r\nMDMxNzEyWhcNMzAxMTAxMDMxNzEyWjAuMSwwKgYDVQQDDCNYSSBPYmplY3RzIElu\r\nYyBDb250cm9sIEludGVybWVkaWF0ZTAqMAUGAytlcAMhAFSS/pggSRmTcAMko7uc\r\nATH8OHgxVymd5mBFlPXbJkgio4GtMIGqMBIGA1UdEwEB/wQIMAYBAf8CAQAwDgYD\r\nVR0PAQH/BAQDAgEGMB0GA1UdDgQWBBQ7KbeYWbD\u002BqzV\u002BAqu6MKTGGtOTsjBlBgNV\r\nHSMEXjBcgBQAZRTDswSVORu\u002BkUOKX6WvrOvmQKEupCwwKjEoMCYGA1UEAwwfSW5z\r\ndGl0dXRlIG9mIFByb3ZlbmFuY2UgUm9vdCBDQYIUJqoJlpiSFg\u002B7W5IJLMrLttgR\r\nQp4wBQYDK2VwA0EA5FOht7YOsVRPp/FOKMQ\u002B3Mo9JxrvGR3ylKWAWNm6OUV7N3DB\r\nI9cD62wU5I0d0EKDBy0CX9DnoqUyxv5yguraAA==\r\n-----END CERTIFICATE-----\r\n",
    "-----BEGIN CERTIFICATE-----\r\nMIIBaTCCARugAwIBAgIUJqoJlpiSFg\u002B7W5IJLMrLttgRQp4wBQYDK2VwMCoxKDAm\r\nBgNVBAMMH0luc3RpdHV0ZSBvZiBQcm92ZW5hbmNlIFJvb3QgQ0EwHhcNMjUxMTAy\r\nMDMwNTEyWhcNMzUxMDMxMDMwNTEyWjAqMSgwJgYDVQQDDB9JbnN0aXR1dGUgb2Yg\r\nUHJvdmVuYW5jZSBSb290IENBMCowBQYDK2VwAyEAEWNZl\u002Br3IC7\u002BgBh90Yo1kWk1\r\npZCVzVuFdFT7qBBU8W2jUzBRMB0GA1UdDgQWBBQAZRTDswSVORu\u002BkUOKX6WvrOvm\r\nQDAfBgNVHSMEGDAWgBQAZRTDswSVORu\u002BkUOKX6WvrOvmQDAPBgNVHRMBAf8EBTAD\r\nAQH/MAUGAytlcANBAO6QeydOFNrN75qNyftggYudsxMyl4w9qWkSdZ6hlhrRcbSr\r\niG9Si0kbrIJOwYB/LTBU0RM4Rl\u002Bo9PM3Qp0mPwo=\r\n-----END CERTIFICATE-----\r\n"
  ],
  "key_id": "i1xUjBgnfprOkR49BjDnH_u3g5aYtfteENcAGMjJGlA",
  "created_at": "2026-09-23T10:54:38Z"
}
-->