--- title: "Look-up" description: "Look images up, singly with POST /lookup or in batches through a look-up slot, and read the verdicts back." published: 2026-09-23T10:54:51.893037+00:00 updated: 2026-09-23T10:54:51.893037+00:00 tags: ["api", "parallax", "reference", "rest"] url: https://xiobjects.com/docs/xio/parallax/rest-api/reference/look-up source: XI Objects --- # Look-up Look-up comes in two forms: one image per request, or a slot that holds many query images and looks them all up on commit. Both answer the same verdict per image. ## POST /lookup Looks one image up. Accepts `multipart/form-data` carrying exactly one image file part and nothing else. **Parts:** | Field | Type | Required | Description | |-------|------|----------|-------------| | any file part | File part | Yes | Exactly one image. The part name carries no meaning. | No query-string parameter and no other form field is accepted. There is no top-K, threshold or options object. ```bash curl -sS -X POST "$BASE/lookup" \ -H "Authorization: Bearer $TOKEN" \ -F "image=@query.png;type=image/png" ``` **Response: 200 OK** | Field | Type | Description | |-------|------|-------------| | `matched` | `bool` | `true` when any account holds a live registration for this image. | | `matchedOriginalImageHashes` | `array` | The original image hashes this query matched. Each is a key for `GET /records/{originalImageHash}`. Empty for no match. | | `candidates` | `array` | Only your own matching registrations. Empty for a match you do not own, and empty for no match. | | `candidates[].registrationId` | `uuid` | Your registration for this image. | ```json { "matched": true, "matchedOriginalImageHashes": ["9f2c7a41e6b8d0532c1f4a9b7e0d8c6a53f1b2e4d7c0a9f8b6e3d1c4a7f0b2e5"], "candidates": [ { "registrationId": "6f0d4d6e-9a0b-4c2e-9b1a-2d3c4e5f6a7b" } ] } ``` No manifests are returned here, for your own match or anyone else's. Take a hash from `matchedOriginalImageHashes` to `GET /records/{originalImageHash}`. No score, rank or similarity value exists anywhere in this response. **Statuses:** | Status | Title | Meaning | |--------|-------|---------| | 400 | `Malformed request` | A query-string parameter, a wrong part count, an extra part, or a malformed body | | 413 | `Request too large` | Past the per-request cap | | 413 | `Image too large` | Past the per-image cap | | 422 | `Image could not be checked` | No verdict was produced. Nothing charged | | 429 | `Quota exceeded` | Carries both remaining counts | | 503 | `Image could not be checked yet` | The engine could not answer for this image yet. Nothing registered, answered or charged. `Retry-After` names the seconds to wait before sending the same request again | | 503 | `Engine not configured` | No engine is wired | See [Look up a single image](/docs/xio/parallax/rest-api/look-up-single-image). --- ## POST /lookup/slots Opens a look-up slot. Look-up slots have their own cap, counted separately from registration slots. ```bash curl -sS -X POST "$BASE/lookup/slots" -H "Authorization: Bearer $TOKEN" ``` **Response: 201 Created**, with a `Location` header pointing at the slot. | Field | Type | Description | |-------|------|-------------| | `lookupSlotId` | `string` | The slot's opaque id. | | `expiresAt` | `datetime` | When the slot dies, unless activity moves it. | ```json { "lookupSlotId": "sl_4d7h2j9k1m3n5p7q9r2s4t", "expiresAt": "2026-09-21T14:32:05.118Z" } ``` **Statuses:** | Status | Title | Meaning | |--------|-------|---------| | 409 | `Open-slot cap reached` | Carries `cap` | --- ## DELETE /lookup/slots/{lookupSlotId} Abandons the look-up slot. Every held query's pixels are deleted and every reservation comes back. Nothing was looked up, so nothing is charged. **Response: 204 No Content**, no body. **Statuses:** | Status | Title | Meaning | |--------|-------|---------| | 404 | `Slot not found` | Unknown, already gone, or not yours | | 409 | `Slot is no longer open` | The slot is committed | --- ## POST /lookup/slots/{lookupSlotId}/queries Uploads query images. No engine call happens here. Refreshes the slot's idle window. **Parts:** | Field | Type | Required | Description | |-------|------|----------|-------------| | any file part | File part | Yes, at least one | One query image per part. The part name carries no meaning. | A look-up request carries the image alone. No manifest part, no other form field and no query-string parameter is accepted. Any of them refuses the whole request, and a refused request holds nothing. ```bash curl -sS -X POST "$BASE/lookup/slots/$LOOKUP_SLOT_ID/queries" \ -H "Authorization: Bearer $TOKEN" \ -F "a=@first.png;type=image/png" \ -F "b=@second.png;type=image/png" ``` **Response: 200 OK** | Field | Type | Description | |-------|------|-------------| | `outcomes` | `array` | One [upload outcome](#upload-outcome) per image part, in request order. `registrationId` is never populated here. | ```json { "outcomes": [ { "partIndex": 1, "fileName": "first.png", "accepted": true, "imageHash": "3b8f1a...9e4c", "rejectionReason": null, "registrationRemaining": null, "lookupRemaining": null, "registrationId": null }, { "partIndex": 2, "fileName": "second.png", "accepted": false, "imageHash": null, "rejectionReason": "This lookup slot already holds the maximum number of query images.", "registrationRemaining": null, "lookupRemaining": null, "registrationId": null } ] } ``` **Statuses:** | Status | Title | Meaning | |--------|-------|---------| | 400 | `Malformed request` | A query-string parameter, a non-image part, more images than the per-request cap, or a malformed body | | 404 | `Slot not found` | Unknown, expired, or not yours | | 409 | `Slot is no longer open` | The slot is committed | | 413 | `Request too large` | Past the per-request cap | | 429 | `Quota exceeded` | No image in the request fit. Carries both remaining counts | | 503 | `Engine not configured` | No engine is wired | --- ## POST /lookup/slots/{lookupSlotId}/queries/missing Answers which of your declared hashes the look-up slot does not already hold. Refreshes the slot's idle window. **Request body:** | Field | Type | Required | Description | |-------|------|----------|-------------| | `hashes` | `string[]` | No | Image hashes, 64 lowercase hex characters each, no duplicates. | ```bash curl -sS -X POST "$BASE/lookup/slots/$LOOKUP_SLOT_ID/queries/missing" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"hashes":["3b8f1a...9e4c","ffff...ffff"]}' ``` **Response: 200 OK** | Field | Type | Description | |-------|------|-------------| | `missing` | `string[]` | The declared hashes the slot does not hold. | ```json { "missing": ["ffff...ffff"] } ``` **Statuses:** | Status | Title | Meaning | |--------|-------|---------| | 400 | `Too many declared hashes` | Past the declared-list cap | | 400 | `Invalid declared hash` | A value is not a unique 64-character lowercase hex hash | | 404 | `Slot not found` | Unknown, expired, or not yours | | 409 | `Slot is no longer open` | The slot is committed | --- ## GET /lookup/slots/{lookupSlotId}/manifest Reports the held queries. Does not refresh the idle window. **Response: 200 OK** | Field | Type | Description | |-------|------|-------------| | `entries` | `array` | One [slot entry](#slot-entry) per held query. | A query carries no manifest of its own, so `manifestsHash` and `notRegisteredReason` are always `null` here. ```json { "entries": [ { "imageHash": "3b8f1a...9e4c", "manifestsHash": null, "byteLength": 184320, "contentType": "image/png", "createdAt": "2026-09-21T14:12:41.882Z", "state": "held", "notRegisteredReason": null } ] } ``` **Statuses:** | Status | Title | Meaning | |--------|-------|---------| | 404 | `Slot not found` | Unknown, expired, or not yours | --- ## DELETE /lookup/slots/{lookupSlotId}/entries/{imageHash} Removes one held query, deletes its pixels and gives its reservation back. Idempotent. Refreshes the slot's idle window. **Response: 204 No Content**, no body. **Statuses:** | Status | Title | Meaning | |--------|-------|---------| | 404 | `Slot not found` | Unknown, expired, or not yours | | 404 | `Entry not found` | The hash is not a valid image hash | | 409 | `Slot is no longer open` | The slot is committed | --- ## POST /lookup/slots/{lookupSlotId}/commit Looks every held query up. This is the only call that triggers the engine's look-up, and it is terminal. It answers the results directly. ```bash curl -sS -X POST "$BASE/lookup/slots/$LOOKUP_SLOT_ID/commit" -H "Authorization: Bearer $TOKEN" ``` **Response: 200 OK** | Field | Type | Description | |-------|------|-------------| | `lookupSlotId` | `string` | The slot's id. | | `queries[].imageHash` | `string` | The query's hash. | | `queries[].state` | `string` | `answered`, `held`, `failed` or `retry`. | | `queries[].result` | `object?` | The verdict, when the query reached one. `matched` plus `candidates`, the same shape `POST /lookup` answers. | | `queries[].failureReason` | `string?` | Why the query could not be answered. | ```json { "lookupSlotId": "sl_4d7h2j9k1m3n5p7q9r2s4t", "queries": [ { "imageHash": "3b8f1a...9e4c", "state": "answered", "result": { "matched": true, "candidates": [ { "registrationId": "6f0d4d6e-9a0b-4c2e-9b1a-2d3c4e5f6a7b", "manifests": [] } ] }, "failureReason": null }, { "imageHash": "a17c05...2f91", "state": "answered", "result": { "matched": false, "candidates": [] }, "failureReason": null } ] } ``` A query the engine would not serve lands `failed`, never as no match, and is charged nothing. A query it could not answer yet lands `retry` instead: send that image again, in a new slot or through `POST /lookup`. **Statuses:** | Status | Title | Meaning | |--------|-------|---------| | 404 | `Slot not found` | Unknown, expired, or not yours | | 409 | `Slot is no longer open` | Already committed or abandoned | | 429 | `Quota exceeded` | Carries both remaining counts | | 503 | `Engine not configured` | No engine is wired | --- ## GET /lookup/slots/{lookupSlotId}/progress Reports the slot's state and each query's own, without the verdict bodies. Polling only. Does not refresh the idle window. **Response: 200 OK**, the [progress](#progress) shape. `counts.registered` and `counts.errata` are always `0` on a look-up slot. ```json { "slotId": "sl_4d7h2j9k1m3n5p7q9r2s4t", "status": "committed", "counts": { "total": 2, "held": 0, "registered": 0, "answered": 2, "failed": 0, "errata": 0 }, "entries": [ { "imageHash": "3b8f1a...9e4c", "state": "answered", "registrationId": null, "failureReason": null }, { "imageHash": "a17c05...2f91", "state": "answered", "registrationId": null, "failureReason": null } ] } ``` **Statuses:** | Status | Title | Meaning | |--------|-------|---------| | 404 | `Slot not found` | Unknown, expired, purged, or not yours | --- ## GET /lookup/slots/{lookupSlotId}/results Reads the verdicts back. Same shape the commit answered. Readable until the slot's `expiresAt`, then the slot is purged and this route answers `404`. ```bash curl -sS "$BASE/lookup/slots/$LOOKUP_SLOT_ID/results" -H "Authorization: Bearer $TOKEN" ``` **Response: 200 OK** | Field | Type | Description | |-------|------|-------------| | `lookupSlotId` | `string` | The slot's id. | | `queries` | `array` | One entry per query the slot holds, with its state, verdict and failure reason. | ```json { "lookupSlotId": "sl_4d7h2j9k1m3n5p7q9r2s4t", "queries": [ { "imageHash": "3b8f1a...9e4c", "state": "answered", "result": { "matched": true, "matchedOriginalImageHashes": ["9f2c7a...b2e5"], "candidates": [] }, "failureReason": null } ] } ``` **Statuses:** | Status | Title | Meaning | |--------|-------|---------| | 404 | `Slot not found` | Unknown, expired, purged, or not yours | See [Look up in batches](/docs/xio/parallax/rest-api/look-up-in-batches). ---