--- title: "Getting Started" description: "Authenticate with your beta token, check the service, read the error shape, and run a first registration, look-up and take-down against XI Parallax." published: 2026-09-21T23:43:27.981208+00:00 updated: 2026-09-21T23:43:27.981208+00:00 tags: ["getting-started", "parallax", "rest"] url: https://xiobjects.com/docs/xio/parallax/getting-started source: XI Objects --- # Getting Started Base URL: `https://api.parallax.xiobjects.com` ## Your token XI Parallax is a private beta. An operator creates your account, mints an API token for it and gives you the token once. Store it somewhere safe. There is no self-service route to create an account or mint a token, and no route to read a token back. Send it as a bearer token on every request: ```bash export TOKEN="your-beta-token" export BASE="https://api.parallax.xiobjects.com" curl -sS "$BASE/account/stats" -H "Authorization: Bearer $TOKEN" ``` Every route except `GET /health` requires the token. A missing, malformed, unknown or revoked token all answer the same `401 Unauthorized` with no detail about which it was. The token resolves to your account. Your account id is never a route parameter, a query-string value or a body field anywhere in this API. You can only ever act on your own registrations, slots, quotas and usage. ## Check the service ```bash curl -sS "$BASE/health" ``` ```json { "service": "Xio.Parallax.Rest", "version": "1.0.0" } ``` `GET /health` takes no token. It reports the service identity and the running version. ## The OpenAPI document The generated OpenAPI document is published at `https://api.parallax.xiobjects.com/openapi/v1.json`. It takes no token, and it is the one route that answers a cross-origin GET, so a browser based viewer can load it by URL. The document lists every route, method and security requirement, and declares the request body, every response schema and every refusal shape for each operation. It is the machine-readable contract. The [REST API reference](/docs/xio/parallax/api/rest) is the readable write-up alongside it. ## The error shape Every refusal answers `application/problem+json`, the standard problem details envelope. | Field | Type | Description | |-------|------|-------------| | `title` | `string` | A short name for the problem, stable per refusal kind. | | `status` | `int` | The HTTP status code, repeated in the body. | | `detail` | `string` | A fixed sentence saying what happened. It never quotes your image, your manifest or another account back at you. | | `traceId` | `string` | The request's trace identifier. Quote it when you ask for help. | | `type` | `string` | A URI naming the problem type. Present for the statuses the framework defines one for. | Some refusals add one or two extension fields. `cap` on an open-slot refusal, `registrationId` on an already-registered refusal that names your own registration, `registrationRemaining` and `lookupRemaining` on a quota refusal. A real quota refusal: ```json { "title": "Quota exceeded", "status": 429, "detail": "The account's remaining quota does not cover this request.", "registrationRemaining": 1, "lookupRemaining": 0, "traceId": "00-7f3a1c0d9b2e4a6f8c1d2e3f4a5b6c7d-1a2b3c4d5e6f7081-00" } ``` Every status and every refusal reason is listed in [Errors and refusals](/docs/xio/parallax/errors-and-refusals). ## Limits you will see There is no per-second request rate limit on this API. What bounds you is your grant and a set of size and count caps. You meet them as refusals, not as headers. | Limit | How you meet it | |-------|-----------------| | Per-request upload size | `413 Request too large`, on every route that reads a body. | | Per-image size | `413` with title `Image too large`, or a per-image rejection reading `Image exceeds the per-image size cap.` | | Accepted image media types | `415 Unsupported image content type`, or a per-image rejection reading `Unsupported image content type.` The beta deployment accepts `image/jpeg`, `image/png` and `image/webp`. | | Manifest part size | `413 Manifest too large`, or a per-image rejection reading `Manifest exceeds the size cap.` | | Manifests per image | A per-image rejection naming the cap, for example `An image carries at most 8 manifests.` | | Declared hashes per resume call | `400 Too many declared hashes`. | | Open slots per account | `409 Open-slot cap reached`, carrying a `cap` extension. | | Query images per look-up slot | A per-image rejection reading `This lookup slot already holds the maximum number of query images.` | | Registrations and look-ups granted | `429 Quota exceeded`, carrying both remaining counts. See [Quotas and stats](/docs/xio/parallax/quotas-and-stats). | ## A first pass Register one image, look it up, take it down. ### 1. Register ```bash curl -sS -X POST "$BASE/registrations" \ -H "Authorization: Bearer $TOKEN" \ -F 'manifest[xi-manifest]={"caption":"my first image"};type=application/json' \ -F "image=@photo.png;type=image/png" ``` ```json { "id": "6f0d4d6e-9a0b-4c2e-9b1a-2d3c4e5f6a7b", "imageHash": "3b8f1a...9e4c", "manifests": [ { "type": "xi-manifest", "form": "json", "payload": { "caption": "my first image" } } ], "engineRecord": "{\"originalImageHash\":\"...\",\"outcome\":\"Registered\",\"engine\":\"...\",\"engineVersion\":\"...\"}" } ``` `id` is your registration id. Keep it. `imageHash` is the SHA-256 of the bytes you sent, computed by the service. `engineRecord` is the engine's own provenance document, carried as an opaque string. ### 2. Look it up ```bash curl -sS -X POST "$BASE/lookup" \ -H "Authorization: Bearer $TOKEN" \ -F "image=@photo.png;type=image/png" ``` ```json { "matched": true, "candidates": [ { "registrationId": "6f0d4d6e-9a0b-4c2e-9b1a-2d3c4e5f6a7b", "manifests": [ { "type": "xi-manifest", "form": "json", "payload": { "caption": "my first image" } } ] } ] } ``` A look-up run immediately after a registration can answer `matched: false` for a short window, until the registration has propagated. Retry with a short backoff rather than treating the first answer as final. ### 3. Take it down ```bash curl -sS -i -X DELETE "$BASE/registrations/6f0d4d6e-9a0b-4c2e-9b1a-2d3c4e5f6a7b" \ -H "Authorization: Bearer $TOKEN" ``` `204 No Content`. The image stops matching. A later look-up of the same bytes answers `matched: false` with no candidates, and you are free to register those bytes again. ## Where to go next - One image at a time: [Register a single image](/docs/xio/parallax/register-single-image). - Many images: [Register in batches](/docs/xio/parallax/register-in-batches). - Searching: [Look up a single image](/docs/xio/parallax/look-up-single-image) and [Look up in batches](/docs/xio/parallax/look-up-in-batches).