--- title: "Look Up a Single Image" description: "Send one image to XI Parallax and learn whether it is registered, plus your own registration and manifests when the match is yours." published: 2026-09-21T23:43:41.538853+00:00 updated: 2026-09-21T23:43:41.538853+00:00 tags: ["lookup", "parallax", "rest"] url: https://xiobjects.com/docs/xio/parallax/look-up-single-image source: XI Objects --- # Look Up a Single Image `POST /lookup` answers one question about one image: is it registered. ## The request `multipart/form-data` carrying exactly one image file part and nothing else. ```bash curl -sS -X POST "$BASE/lookup" \ -H "Authorization: Bearer $TOKEN" \ -F "image=@query.png;type=image/png" ``` The part name carries no meaning on this route. Any file part is the query image. There are no other inputs. No top-K, no threshold, no options object, no query-string parameter, no second form field. A request carrying any of them is refused before the image is read. The image is bounded by the same per-image and per-request size caps a registration image is, and its content type must be one the deployment accepts. ## The verdict `200 OK`. | Field | Type | Description | |-------|------|-------------| | `matched` | `bool` | `true` when any account holds a live registration for this image. | | `candidates` | `array` | Only your own matching registrations. Empty when the match is not yours, and empty when there is no match. | Each candidate: | Field | Type | Description | |-------|------|-------------| | `registrationId` | `uuid` | Your registration for this image. | | `manifests` | `array` | The manifests you registered with it, exactly as registered. Each is `{ type, form, payload }`. | ### Your own image ```json { "matched": true, "candidates": [ { "registrationId": "6f0d4d6e-9a0b-4c2e-9b1a-2d3c4e5f6a7b", "manifests": [ { "type": "xi-manifest", "form": "json", "payload": { "owner": "me" } } ] } ] } ``` ### Someone else's image ```json { "matched": true, "candidates": [] } ``` The image is registered. Nothing about whose registration it is, what it is called, or what manifests it carries is returned. `matched: true` with an empty `candidates` array is the whole answer. ### Nobody's image ```json { "matched": false, "candidates": [] } ``` ## No score, no ranking There is no score, rank or similarity value anywhere in the response, and no way to ask for one. The answer is binary. `candidates` is the set of your own registrations the match resolved to, not a ranked list. ## Timing 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. A registration you have [taken down](/docs/xio/parallax/take-down) stops matching. A later look-up of those bytes answers `matched: false` with no candidates. ## What it costs One look-up from your look-up grant, per call that produces a verdict. A call refused before a verdict costs nothing. See [Quotas and stats](/docs/xio/parallax/quotas-and-stats). ## Refusals | Status | Title | `detail` | |--------|-------|----------| | `400` | `Malformed request` | `POST /lookup accepts no query-string parameters.` | | `400` | `Malformed request` | `POST /lookup requires exactly one well-formed multipart image file part.` | | `400` | `Malformed request` | `POST /lookup requires a well-formed multipart body.` | | `400` | `Malformed request` | `POST /lookup accepts exactly one image file part and no other part.` | | `400` | `Malformed request` | `POST /lookup requires exactly one image file part.` | | `413` | `Request too large` | `The request exceeds the configured per-request upload size cap.` | | `413` | `Image too large` | `The image exceeds the configured per-image size cap.` | | `422` | `Image could not be checked` | The engine would not check this image, or the image could not be stored for look-up. No verdict was produced and nothing was charged. Retry. | | `429` | `Quota exceeded` | Your look-up grant does not cover this call. Carries `registrationRemaining` and `lookupRemaining`. | | `503` | `Engine not configured` | The deployment has no engine wired. | ## Your pixels The query image's bytes are held only for as long as the engine needs to answer. They are then deleted and their absence is verified. See [Custody and privacy](/docs/xio/parallax/custody-and-privacy). ## Many images at once Use the look-up slot conversation. See [Look up in batches](/docs/xio/parallax/look-up-in-batches).