nyris API Documentation

Integrating nyris? It takes two steps: import your product data into the nyris index (Product Data & Images), then integrate nyris into your website or app (Integration (for humans)). No data in nyris yet? Ask support@nyris.io for an API key to a demo index and start with the frontend.

For AI coding agents. Use the Agent Guide section, or download it as Markdown. That file is the spec for endpoints, image handling, and request formats. Do not invent endpoints from the rest of this page.

Search UI assets. Icons for camera, drop zone, upload, crop, search, and the controls around results are free to reuse. They are one color (currentColor) on a 24 × 24 canvas. Download the asset pack, or use a single file from search-ui/.

Welcome to nyris' API Documentation. nyris is a high performance visual product search, object detection and visual recommendations engine for retail and industry. This documentation covers our visual product search engine and the visual recommendations engine.

The implementation in your website or app comprises three steps.

1. Submit your product & image data
In order to recognize your products, we need to know your products. The product feed section covers all details how to submit your product data to us and the specifications for your product or object images.

2. Implement nyris API in your app, website or messenger bot
The nyris engine can be integrated in your app, website, messenger bots, BI solutions - wherever you want to make your customers happy or optimize your data management process. We provide you with code examples on how to query our Find API and Regions API and have ready to go SDKs for iOS and Android.

3. Implement automated feedback in your app, website or messenger bot
By tying user interactions to automated feedback in our Feedback API, you allow for automatic statistic generation and continuous improvement of the search results.

To get started, email us at mailto:support@nyris.io. Our team will provision API keys to access our API. Always feel free to contact us should you have questions or suggestions for our service or this documentation. In addition, you can always find our open source code github.com/nyris.

Try it with Postman — You can explore and test the nyris API directly using our public Postman workspace. It includes ready-to-use collections for Find, Recommend, Regions, and Images APIs.

Thank You & happy coding!
Markus (CTO / Founder)

Agent Guide: implement nyris visual search

Download this guide as Markdown. The chapters below are the same guide, formatted for this site.

You are implementing visual search against the nyris Find API. Follow this file. Do not invent endpoints. Do not call the Data Management API (/manage/v1) unless the user explicitly asked to edit the catalog.

Scope: adding nyris takes two steps, and this file covers only the second.

1. Import the product data into the nyris index. Not your task. See Product Data & Images. Do not upload data yourself.
2. Integrate nyris into a user-facing frontend: the website or app where users search. A thin backend that only forwards requests is in scope too.

The steps are independent. Do not stop if the user's data is not in nyris yet. Build against a demo index instead: the user can ask support@nyris.io for an API key to a demo index with sample products. Keep the key in configuration so it can be swapped for the production key later. Tell the user that step 1 is still open.

Reference implementation: the nyris example web app. Where this file says "the example web app" or "the example client", it means that app.

The human version of this guide is Integration (for humans). This file is enough on its own.

Inputs you must have

Ask before coding if any of these are missing:

Never hard-code the key. Never print it. Never commit it.

The key is sent from the client as X-Api-Key. It must be a Find key. Refuse to embed a Data Management key in a client app.

Endpoints

Filters: use /find/v1/filters. The response is a JSON array of { "key": "color", "values": ["Red", "Blue"] } (empty if the index has no filters). To search the values of one key, call GET {base}/find/v1/filters/{key}/{value}?limit=100, where {value} is the search term; it returns string[].

CAD search (POST {base}/cad/find/v0.2, multipart field file) is not part of the public API reference. Use it only if the user confirms that nyris enabled CAD search for their account.

Request body formats

Find and Regions accept the image in three formats. The results are the same.

JSON body schema:

Regions JSON takes only image.

Base64 makes the request about 33% larger. The 2 MB limit applies to the decoded image, not the encoded body. Still resize before encoding exactly as in step 4. Default to multipart. Use JSON when the user asks for it or the platform cannot send multipart or binary bodies.

Do the base64 encoding in code. If you are an agent that can call HTTP tools, never put image base64 into your own output or tool arguments by hand. It wastes tokens and gets corrupted.

Normative steps

Implement in this order.

1. Capture. User picks a file or a camera frame. Show that image immediately. Do not wait for the network to show the preview.
2. Normalize and keep. Decode the bitmap. Apply EXIF orientation. Flatten transparency onto white (rgb(255,255,255)). Keep this normalized original at full resolution in memory until the user removes the image. Show a screen-sized preview derived from it. Never crop the preview or the step 4 JPEG; crops come from this original only.
3. Convert formats.
   • JPEG, PNG, WebP, GIF first frame, AVIF, BMP: decode as a bitmap.
   • HEIC/HEIF: decode with the platform, createImageBitmap, or heic-to / libheif, then continue as a bitmap.
   • TIFF: first page only. If pixels are 3-channel RGB, append alpha 255. Most browsers cannot decode TIFF natively; on the web, add a TIFF decoder or reject TIFF with a clear message. Do not list it in the file picker if you cannot decode it.
   • PDF: rasterize page 1, then continue as a bitmap.
   • Extensions .stp, .step, .stl, .obj, .glb, .gltf: do not send them to /find/v1.1. If CAD search is enabled for the account, POST the original file to /cad/find/v0.2 as field file. Otherwise treat it as unsupported.
   • Try the native decoder first for every other file. Route by extension only for CAD. Do not reject HEIC, AVIF, or other image types by name; the platform may already decode them.
   • Anything that still fails to decode: stop and tell the user the format is unsupported.
   • Always send JPEG. The API itself accepts only JPEG, PNG, and WebP; anything else returns 415 (binary or multipart) or 400 (JSON base64). Base64 does not change this: the bytes inside must still be JPEG.
4. Resize. Check the source (or the crop) in original pixels. If its shortest edge is under 100 px, still search, but show a non-blocking hint that results may be less accurate. Scale with the area formula below so the output area is 1024 * 1024 (the example client always does this, including small sources). Encode JPEG at quality 0.9. Target size is about 100 kB; keep it at most 1 MB for latency. If the blob is still above ~200 kB, re-encode at 0.8. The API rejects images over 2 MB (2,097,152 bytes) with 413.
5. Regions. POST /find/v2/regions with Content-Type: image/jpeg and the raw JPEG as the body. Multipart (part image) and JSON base64 also work; see Request body formats. Map pixel boxes to normalized 0..1 coordinates. If the list is empty, the crop is the full frame. If Regions fails, continue with the full frame; never block Find on Regions. As soon as Regions returns, auto-select the best region, mark its marker active, and run step 6 with that crop without waiting for a click. Draw the overlay as specified in Region overlay.
6. Find. POST /find/v1.1 as multipart/form-data (or binary / JSON base64, see Request body formats). Field image is the JPEG. If there is a selected region that is not the full frame, crop the normalized original from step 2 (not the step 4 JPEG), then resize per step 4, then send that JPEG. Header Accept: application/items.complete+json for product fields; without it you get the minimal { sku, score } format. Header X-Api-Key.
7. Text. If the user typed a query, append multipart field text (or JSON field text). Keep it under 512 characters. Do not put text in the query string; a query-string text returns results: []. Exception: with an existing text search engine that handles the keyword, do not send text to nyris (see Existing text search).
8. Render. Read results[]. Identity is sku, else key, else objectID. Show a skeleton list while the request is in flight. On a new search, clear the previous list. HTTP 200 with an empty list is an empty state, not an error. Keep the order of results[]; it is the visual similarity order. Do not show score (or a percentage) on result cards. It is an internal ranking signal and misleads users. If the site already has a text search results page, render there; see Existing text search.
9. Stale responses. If the user searches again, ignore or abort the older request.
10. Session (optional). If the Find response has session, send it as header X-Session (or query ?session=) on follow-up searches, for example a crop search after a full-frame search. Only send ids the API returned; an invented value returns HTTP 400.
11. Feedback (optional). POST /feedback/v1 with Content-Type: application/json. Required: request_id (Find id), timestamp (ISO 8601 UTC), event (click, conversion, feedback, or region). Optional: session_id (Find session) and an event-specific data object. See Feedback event. The ids are also in the response headers X-Matching-Request and X-Session, but browsers may not expose those headers, so read the body.

Without an existing text search engine, you may start Find (full frame) and Regions in parallel after step 4. When the user changes the box, run step 6 again with the crop. Cancel the in-flight Find first.

Feedback event

{
  "request_id": "<id from find>",
  "session_id": "<session from find>",
  "timestamp": "2026-09-29T12:00:00.000Z",
  "event": "click",
  "data": { "positions": [0], "product_ids": ["ABC-100"] }
}

data by event:

A valid event returns HTTP 2xx.

Resize formula

aspect = width / height
targetArea = 1024 * 1024
outWidth = sqrt(targetArea * aspect)
outHeight = outWidth / aspect

Round to integers. Crop in normalized coordinates before this resize:

sx = originalWidth * x1
sy = originalHeight * y1
sw = originalWidth * (x2 - x1)
sh = originalHeight * (y2 - y1)

x1,y1 is top-left, x2,y2 is bottom-right, each in 0..1.

Regions come back in pixels of the JPEG you posted:

x1 = left / sentWidth
x2 = right / sentWidth
y1 = top / sentHeight
y2 = bottom / sentHeight

Region overlay

Do not draw every detected rectangle at once. Overlapping boxes make the photo unreadable. A row of "Object 1 / Object 2" buttons under the image is useless: those labels have no spatial link to the photo.

Required UI:

1. Auto-select the highest-confidence region (full frame if none). Mark that object's center marker as active immediately, then search that crop. Do not wait for another click.
2. Place a small dot at the center of every detected box: ((x1+x2)/2, (y1+y2)/2).
3. Draw a bounding box only for the selected region (auto-selected, or the one the user last chose by clicking a dot or dragging a crop).
4. Dim the rest of the image with a semi-transparent black overlay outside that box so the selected object is the focus. If the selection is the full frame, do not dim.
5. Clicking a dot selects that object and re-runs Find with its crop. Dragging on the image may set a custom crop. Do not add object-index buttons.

Existing text search

If the site already has a search results page backed by a text search engine (Algolia, Elasticsearch, OpenSearch, Typesense, ...), do not build a second results page. Full guide: Combine with your text search. Rules:

1. One results page. The query image becomes a removable chip in the search box, and the region preview sits on the same results page. Facets, filters, product cards, and pagination are the existing components.
2. nyris order is final. Visual search is exact search; the most similar product comes first. Do not let the engine re-rank: turn off merchandising rules, pinned or promoted items, personalization, dynamic re-ranking, and variant grouping for visual queries. Do not boost or sink by stock, margin, or popularity. Out-of-stock products stay visible in their position. The only sort is "Most similar"; hide the sort dropdown while an image is active. Never interleave recommendations or sponsored items.
3. One search chain. Regions, auto-select, then one Find with the crop and X-Options: limit=100. Do not run a parallel full-frame Find. Treat nyris plus the engine query as one search for stale-response handling.
4. Join by SKU. Query the engine with an empty text query, restricted to the returned SKUs, plus the user's facet filters and the page's fixed filters (market, visibility; AND them, never replace them). Fetch all of them in one page with facet counts. Then sort the records by nyris position in your own code. Engine order is never trusted. Paginate in the client.
5. Facets narrow, never reorder. Changing a facet re-queries the engine with the same SKUs and does not call nyris again. Changing the crop calls nyris again and clears facets.
6. Missing products are dropped, not replaced. A nyris SKU the engine does not return is removed and reported as a sync problem. Never backfill with text results or bestsellers.
7. A keyword narrows. Pick one approach per site: use the keyword as the engine query inside the SKU restriction (and do not send text to nyris), or send it to nyris as text. Either way keep the nyris order. Do not merge a separate full-catalog text search.
8. Feedback positions are the zero-based index in the nyris results list, not the filtered page position. Always include product_ids.
9. Engine failure shows an error with retry. Show nyris products directly only if the shop has no per-market or per-customer visibility rules.

Demo styling

For a demo or test site, match the layout and density of test.nyris.app: white header, light gray page (#fafafa), Source Sans 3, compact drop zone. Palette is white, black, and one or two neutrals (borders, muted text). Buttons may be black-on-white or the inverse. Do not use decorative colored page backgrounds.

Find request

POST /find/v1.1 HTTP/1.1
Host: api.nyris.io
X-Api-Key: $NYRIS_API_KEY
Accept: application/items.complete+json
Content-Type: multipart/form-data; boundary=----nyris

------nyris
Content-Disposition: form-data; name="image"; filename="query.jpg"
Content-Type: image/jpeg

<jpeg bytes>
------nyris
Content-Disposition: form-data; name="text"

optional query
------nyris--

Filters, when used (AND across keys, OR across values):

filters[0].filterType = category
filters[0].filterValues[0] = pumps

Do not set Content-Type: multipart/form-data manually if the HTTP client generates the boundary (browser FormData, OkHttp MultipartBody). Set it only when you build the body yourself (curl, raw sockets).

Same request as JSON (base64)

POST /find/v1.1 HTTP/1.1
Host: api.nyris.io
X-Api-Key: $NYRIS_API_KEY
Accept: application/items.complete+json
Content-Type: application/json

{
  "image": "/9j/4AAQSkZJRg...",
  "text": "optional query",
  "filters": [{ "key": "category", "values": ["pumps"] }]
}

Encode the resized JPEG bytes, not the original file. Omit text and filters when unused.

Same request as binary (image only)

POST /find/v1.1 HTTP/1.1
Host: api.nyris.io
X-Api-Key: $NYRIS_API_KEY
Accept: application/items.complete+json
Content-Type: image/jpeg

<jpeg bytes>

Example success body (items.complete)

{
  "results": [
    {
      "sku": "ABC-100",
      "score": 0.91,
      "title": "Example",
      "images": ["https://img.nyris.io/..."]
    }
  ],
  "id": "request-id",
  "session": "session-id"
}

Product fields besides sku and score depend on the index. Do not require a field the index does not have. For a thumbnail, use image if present, else images[0]. session may be missing; treat it as optional.

Regions request

POST /find/v2/regions HTTP/1.1
X-Api-Key: $NYRIS_API_KEY
Content-Type: image/jpeg

<jpeg bytes>

JSON alternative: Content-Type: application/json with body {"image": "<base64>"}.

{
  "regions": [
    {
      "confidence": 0.9,
      "region": { "left": 10, "top": 20, "right": 200, "bottom": 300 }
    }
  ]
}

Coordinates are floats. Ignore fields not shown here.

Errors

If the key is missing locally, do not call the API. Show a configuration error.

Language notes

TypeScript (browser)

const body = new FormData();
body.append("image", jpegBlob, "query.jpg");
if (text) body.append("text", text);

const response = await fetch(`${baseUrl}/find/v1.1`, {
  method: "POST",
  headers: {
    "X-Api-Key": apiKey,
    Accept: "application/items.complete+json",
  },
  body,
  signal,
});

JSON variant, Node.js only (Buffer does not exist in browsers or most edge runtimes):

const image = Buffer.from(jpegBytes).toString("base64");
const response = await fetch(`${baseUrl}/find/v1.1`, {
  method: "POST",
  headers: {
    "X-Api-Key": apiKey,
    Accept: "application/items.complete+json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(text ? { image, text } : { image }),
});

In the browser, FileReader.readAsDataURL(jpegBlob) gives a data URI that you can send as image unchanged.

Python

Build the multipart body yourself or use requests / httpx files={"image": ("query.jpg", jpeg_bytes, "image/jpeg")} and data={"text": text}. Header X-Api-Key. Do not pass text as a URL query parameter.

JSON variant:

payload = {"image": base64.b64encode(jpeg_bytes).decode("ascii")}
if text:
    payload["text"] = text
response = httpx.post(f"{base_url}/find/v1.1", json=payload, headers=headers)

Swift

Draw UIImage into an opaque renderer filled white, jpegData(compressionQuality: 0.9), upload with URLSession multipart part name image.

Kotlin

BitmapFactory with inSampleSize, EXIF rotate, draw onto a white Canvas, compress(JPEG, 90), OkHttp part name image.

Edge cases

Acceptance checklist

All of these must pass before you claim the integration is done:

• Key is read from the environment or a config file that is gitignored.
• A text search uses multipart field text and returns HTTP 200.
• An image search sends a JPEG scaled with the area formula (about 1024×1024 pixels of area).
• If the JSON base64 body is used, it encodes the resized JPEG and returns HTTP 200.
• Transparent PNG becomes a JPEG on a white background.
• EXIF orientation is applied so a portrait phone photo stays portrait.
• JPEG, PNG, WebP, GIF, AVIF, and HEIC uploads all reach Find as JPEG (HEIC also in Chrome).
• Regions response boxes are stored as normalized 0..1. The preview shows a center dot per region and a rectangle only on the selected region, with the rest of the image dimmed. No object-index buttons.
• The auto-selected region's marker is active as soon as Regions returns, before Find responds.
• Result cards show no score or percentage, and appear in the order of results[].
• Changing the box sends a new Find with the cropped JPEG.
• The crop is cut from the full-resolution original, then resized. A crop of a 4000 × 3000 photo is not cut from the 1024² JPEG or the preview.
• A second search does not show the first search’s products after the second response arrives.
• HTTP 200 with results: [] renders an empty state.
• Missing API key does not call the network.
• 401 and 413 each show a distinct message.
• A source under 100 px still searches and shows the small-image hint.
• No Data API write calls were added.
• If an existing text search engine is used: visual results render on the existing results page; the rendered order equals the nyris order (tested); rules, personalization, re-ranking, and variant grouping are off for visual queries only; the page's fixed filters still apply; facets narrow without calling nyris; missing SKUs are dropped, never backfilled. Full list: Combine with your text search.

Test images

Use a photo of a product that is in the index behind the key. With a demo index key, ask the user which sample products it contains. If you have no photo, ask the user for one. Do not download random images from the web.

Expected: HTTP 200 from Find. The number of products depends on the index behind the key, so assert the status and that results is an array, not a specific SKU.

Out of scope

• Creating or deleting index items.
• Tuning X-Options unless the user named a threshold or a limit, or you combine with a text search engine (then limit=100). Index defaults are already applied server-side.
• Reading response headers that echo resolved options. Do not depend on them. (X-Matching-Request and X-Session are fine to read.)

Add nyris visual search

For humans. If you are an agent, you are in the wrong section: yours is above, and it does not include this sentence.

This guide is for developers who want to add nyris visual search to a website or a mobile app.

Adding nyris takes two steps:

1. Import your product data into the nyris index. See Product Data & Images.
2. Integrate nyris into a user-facing frontend: the screen where your users take a photo and see products. That is this guide. A thin backend that forwards requests works the same way.

The steps are independent. If your data is not in nyris yet, you do not have to wait: ask support@nyris.io for an API key to a demo index with sample products, build the frontend against it, and switch the key once your own index is ready.

The nyris example web app is a working reference. The same steps apply in any language.

An AI coding agent should start with Agent Guide. That file is self-contained.

What you build

1. The user picks or captures an image.
2. You normalize it (decode, rotate, convert odd formats) and resize it.
3. You ask nyris which objects are in the image.
4. You search with the full image, or with the box the user selected.
5. You show the products in the order nyris returns them and, if you want analytics, send a feedback event.

If your site already has a text search results page, show visual results there instead of on a separate screen. See Combine with your text search.

Keep the normalized original at full resolution for the whole session. Everything the user sees, and the full-frame JPEG for Regions, can be small. The crop for Find is always cut from the original and resized afterwards. Cropping the small preview or the full-frame JPEG throws away detail: a part a tenth as wide as a 4000 × 3000 photo has 400 × 300 px in the original but only about 118 × 89 px in the 1024² JPEG.

API

Auth is the header X-Api-Key. Use a Find key. A Data Management key will not search.

Public API reference: API Endpoints.

Key in the client

This guide calls the Find API from the app, the same way the example web app does. The key ships in the client, so treat it as a search-only key:

• It can run searches against your index.
• It should not be a Data Management key, and it should not be able to change the catalog.
• Rotate it if it leaks.
• Put a small backend in front of the API when you need to hide the key, add your own auth, or rate-limit per user. See Errors and keys.

Chapters

1. Quickstart — first search with curl, JavaScript, and Python.
2. Image pipeline — formats, EXIF, resize, crop, size limits.
3. Object detection — regions, normalized boxes, re-search.
4. Find API — image, text, filters, response, feedback.
5. Speed — payload size, overlap, perceived speed.
6. Mobile apps — Swift, Kotlin, React Native, Flutter.
7. Errors and keys.
8. Combine with your text search — one results page with Algolia, Elasticsearch, and others, keeping the nyris order.

Runnable samples are in Examples.

Defaults used by the example web app

Quickstart

You need a Find API key. Request one from support@nyris.io. Put it in the environment. Do not commit it.

export NYRIS_API_KEY="your-find-key"
export NYRIS_BASE_URL="https://api.nyris.io"

Text search

Text goes in the multipart body, not the URL.

curl -sS -X POST "$NYRIS_BASE_URL/find/v1.1" \
  -H "X-Api-Key: $NYRIS_API_KEY" \
  -H "Accept: application/items.complete+json" \
  -F "text=hydraulic pump"

The JSON body has results (products), id (this request), and session.

Image search

Resize first when you can. A phone photo of several megabytes is slower and can be rejected. The samples below send a file as-is so you can see the contract; production code should follow Image pipeline.

curl -sS -X POST "$NYRIS_BASE_URL/find/v1.1" \
  -H "X-Api-Key: $NYRIS_API_KEY" \
  -H "Accept: application/items.complete+json" \
  -F "image=@query.jpg;type=image/jpeg"

JavaScript (browser or Node 18+)

async function findByText(apiKey, text) {
  const body = new FormData();
  body.append("text", text);

  const response = await fetch("https://api.nyris.io/find/v1.1", {
    method: "POST",
    headers: {
      "X-Api-Key": apiKey,
      Accept: "application/items.complete+json",
    },
    body,
  });

  if (!response.ok) {
    throw new Error(`Find failed: ${response.status}`);
  }
  return response.json();
}

Do not set Content-Type yourself when using FormData. The runtime must add the multipart boundary.

Python

import os
import urllib.request

boundary = "----nyrisboundary"
text = "hydraulic pump"
payload = (
    f"--{boundary}\r\n"
    f'Content-Disposition: form-data; name="text"\r\n\r\n'
    f"{text}\r\n"
    f"--{boundary}--\r\n"
).encode()

request = urllib.request.Request(
    os.environ.get("NYRIS_BASE_URL", "https://api.nyris.io") + "/find/v1.1",
    data=payload,
    method="POST",
    headers={
        "X-Api-Key": os.environ["NYRIS_API_KEY"],
        "Accept": "application/items.complete+json",
        "Content-Type": f"multipart/form-data; boundary={boundary}",
    },
)
print(urllib.request.urlopen(request, timeout=60).read().decode()[:500])

Full scripts: examples/curl/find.sh, examples/python/find.py, examples/node/find.mjs.

What to build next

A useful product flow is: normalize and resize the image, call regions, let the user adjust the box, then search again with the crop. That is Object detection plus Find API.

Image pipeline

The Find API accepts JPEG, PNG, and WebP. Your app should turn every user file into one JPEG before upload. The example web app does this in @nyris/nyris-api (prepareImage) and in useImageSearch.

file → decode + EXIF rotate → optional format conversion → crop → resize → JPEG

Decode and orientation

Phone cameras store rotation in EXIF. If you ignore it, the search image is sideways and results get worse.

• Web: decode with a loader that applies EXIF (the example web app uses blueimp-load-image with orientation: true in @nyris/nyris-api), or draw through createImageBitmap and respect the orientation.
• iOS: UIImage already applies orientation when you draw it.
• Android: read ExifInterface.TAG_ORIENTATION and rotate the bitmap before you scale it.

Fill transparent pixels with white before you encode JPEG. PNG and WebP transparency otherwise becomes black, and black backgrounds hurt matching. The example client does this:

fill the destination canvas with rgb(255, 255, 255)
draw the source image on top
encode JPEG

Formats

Try the native decoder first. Do not reject a file by its extension unless it is CAD; browsers increasingly decode HEIC and AVIF themselves. Skip or reject anything that still fails to decode, with a clear message.

The API accepts only JPEG, PNG, and WebP. Other formats come back as HTTP 415 (binary or multipart) or 400 "Invalid image format" (JSON base64). Base64 is only the transport; the image inside must still be one of those formats. Converting everything to JPEG on the client avoids all of this and gives the smallest upload.

Resize

Default used by the example web app:

• maxWidth = 1024
• maxHeight = 1024
• jpegQuality = 0.9

The scaler keeps the aspect ratio and targets a pixel area of maxWidth * maxHeight, not “longest edge ≤ 1024”. Extreme panoramas stay sharper this way.

targetArea = maxWidth * maxHeight
width  = sqrt(targetArea * aspectRatio)
height = width / aspectRatio
aspectRatio = originalWidth / originalHeight

Examples with 1024 × 1024:

Round to integers. If you prefer a hard box, fit the longest edge inside 1024 instead (getThumbSizeLongestEdge in @nyris/nyris-api). Area-based sizing is what the example app sends.

The example client always scales to that area, so a very small image is enlarged. Enlarging does not add detail. If the source (or the crop) is under 100 px on its shortest edge, the search still runs, but results get worse. Show the user a hint such as "This image is small; results may be less accurate."

Keep the original

After decode, EXIF rotation, and flattening, keep that bitmap at full resolution for as long as the user works with this image. Derive everything else from it:

Never crop the preview or the full-frame JPEG. A 4000 × 3000 photo resized to about 1182 × 887 keeps only about 9% of its pixels. An object 400 × 300 px in the original (a tenth of the width and height) would become a crop of roughly 118 × 89 px. nyris then sees an enlarged, blurry part instead of real detail.

Release the original when the user removes the image or picks a new one.

Crop

Regions and the user box use normalized coordinates in 0..1. Because they are relative, the same box applies to the preview, the full-frame JPEG, and the original:

x1, y1 = top-left
x2, y2 = bottom-right

Pixel crop on the original image:

sx = originalWidth  * x1
sy = originalHeight * y1
sw = originalWidth  * (x2 - x1)
sh = originalHeight * (y2 - y1)

Resize after the crop, using the crop’s aspect ratio, so the object fills the JPEG you upload.

Limits

With a JSON base64 body, the 2 MB limit applies to the decoded image, not the encoded request.

Aim for about 100 kB after JPEG encode. Quality 0.9 at the sizes above usually lands there. If the blob is still large, lower quality toward 0.8 before you shrink the pixel size further.

Pseudocode

original = flattenOnWhite(decode(file))   # apply EXIF; keep this for the session
preview  = resizeForScreen(original)      # display only

def searchJpeg(normalizedRect = None):
    bitmap = crop(original, normalizedRect) if normalizedRect else original
    bitmap = resizeArea(bitmap, 1024, 1024)   # always the target area
    return encodeJpeg(bitmap, quality=0.9)

Object detection

Regions tell you which objects are in the photo so the user can search one of them instead of the whole frame. The example web app calls this before the product search when the user uploads an image.

Request

Send the same resized JPEG you will use for search (or the full-frame JPEG before a user crop).

POST /find/v2/regions
X-Api-Key: <find-key>
Content-Type: image/jpeg

<raw jpeg bytes>

The example sends the raw image as the body. Two alternatives return the same result:

• Multipart: Content-Type: multipart/form-data with the image in a part named image.
• JSON: Content-Type: application/json with body {"image": "<base64 or data URI>"}.

Regions response

{
  "regions": [
    {
      "confidence": 0.92,
      "region": { "left": 120, "top": 40, "right": 640, "bottom": 700 }
    }
  ]
}

left, top, right, bottom are floating-point pixels of the image you sent, not of the original camera file. The response can contain more fields; ignore them.

Normalize

Store boxes in 0..1 so they survive another resize and map onto the preview:

x1 = left  / sentWidth
x2 = right / sentWidth
y1 = top    / sentHeight
y2 = bottom / sentHeight

Clamp each value to 0..1. Drop boxes whose width or height is below a few percent of the frame; they are rarely useful.

Which box to select

1. If the list is empty, search the full image (x1=0, y1=0, x2=1, y2=1).
2. Otherwise select the highest confidence, or the box closest to the center if several are close.
3. Overlay the photo as in Preview. The user changes the selection by clicking a center dot or dragging a crop, not by a list of "Object N" buttons.
4. When the box changes, crop the full-resolution original (not the preview, not the JPEG you sent to Regions), resize the crop, and call Find again. Do not send the regions response to Find; send the cropped JPEG. See Keep the original.

Order of calls

Two valid orders:

The example web app runs regions first, then Find. Parallel calls are a speed option; see Speed. If results render on an existing text search page, use regions first: see Combine with your text search.

Preview

Show an EXIF-correct preview immediately, scaled down for the screen. Do not wait for the network to show the photo. The preview is for display only; crops always come from the original.

Do not stroke every region. That crowds the image. For each detected box:

dotX = ((x1 + x2) / 2) * frameW
dotY = ((y1 + y2) / 2) * frameH

Draw a small marker at (dotX, dotY). Draw a rectangle only for the selected region:

boxLeft   = x1 * frameW
boxTop    = y1 * frameH
boxWidth  = (x2 - x1) * frameW
boxHeight = (y2 - y1) * frameH

Dim everything outside that rectangle (semi-transparent black). The auto-selected object's marker must look active as soon as Regions returns. Clicking a marker selects that object. Do not add object buttons below the image; they are disconnected from the photo. For layout and a black/white test-site palette, follow test.nyris.app. See also Agent Guide.

Search with the Find API

POST /find/v1.1
X-Api-Key: <find-key>
Accept: application/items.complete+json
Content-Type: multipart/form-data; boundary=...

application/items.complete+json returns product fields (title, image, sku, filters, and so on). Without Accept (or with application/minimal+json) you get a minimal { sku, score } list. The example web app sends application/offers.complete+json, an older name that returns the same fields.

Body formats

The API accepts the image three ways:

Image

image = <jpeg file>

Field name is image. Filename can be query.jpg.

Text

text = hydraulic pump

With multipart/form-data, text must be a form field. A query string ?text= is ignored and you get empty results. Text-only search sends no image part.

Keep text under 512 characters.

Image and text together

Two options. Pick one and keep it consistent:

• Combined on the server: send image and text in the same request and let the API combine them.
• Visual search, then local filter (what the example web app does): when there is an image, the app sends only image and filters the returned titles with the keyword on the client.

Client-side title filter (what the example does after a visual search): case-insensitive match on the product title, with prefix matching so BOL still matches BOLLSIDAN.

If the site has its own text search engine (Algolia, Elasticsearch, ...), use that engine for the keyword and facets, restricted to the nyris SKUs, and keep the nyris order. See Combine with your text search.

Filters

AND across filter types, OR across values of one type.

filters[0].filterType = category
filters[0].filterValues[0] = pumps
filters[0].filterValues[1] = valves
filters[1].filterType = brand
filters[1].filterValues[0] = acme

Catalog of filter keys: GET /find/v1/filters?limit=100 with the same X-Api-Key. It returns an array of { "key": "color", "values": ["Red", "Blue"] }. Search values of one key with GET /find/v1/filters/{key}/{value}?limit=100, which returns string[]. {value} is the search term. Filters are on /find/v1, not /find/v1.1.

JSON body (base64)

Use this when your platform works with JSON end to end and cannot easily send multipart or binary bodies: low-code tools, serverless functions, tool-calling backends, or a gateway that only forwards JSON.

POST /find/v1.1
X-Api-Key: <find-key>
Accept: application/items.complete+json
Content-Type: application/json

{
  "image": "/9j/4AAQSkZJRg...",
  "text": "hydraulics",
  "filters": [
    { "key": "MachineSerial", "values": ["SN-40821"] },
    { "key": "Assembly", "values": ["Hydraulics", "Pneumatics"] }
  ]
}

• image is plain base64 or a data URI (data:image/jpeg;base64,...). Leave it out only for a text-only search ({"text": "..."}).
• text is optional, max 512 characters.
• filters is optional. Each entry is { key, values }, with the same AND/OR rules as multipart.

printf '{"image":"%s"}' "$(base64 < query.jpg | tr -d '\n')" > body.json
curl -sS -X POST "https://api.nyris.io/find/v1.1" \
  -H "X-Api-Key: $NYRIS_API_KEY" \
  -H "Accept: application/items.complete+json" \
  -H "Content-Type: application/json" \
  --data-binary @body.json

Writing the body to a file avoids the shell's argument-length limit for large images.

Base64 adds about 33% to the request. The 2 MB limit applies to the decoded image, not the encoded body. Resize first (see Image pipeline) and encode the resized JPEG, not the camera original. When you control the client, multipart or binary is smaller and faster.

Sessions

Every response carries a request id (id in the body, header X-Matching-Request) and usually a session id (session, header X-Session). Treat the session as optional. To group related searches (for example a crop search after the full-frame search), send the session from the previous response:

X-Session: <session from previous response>

or POST /find/v1.1?session=<session>. Only send session ids the API returned; an invented value returns HTTP 400. Browsers may not expose the response headers to your code, so read id and session from the body.

Geolocation header

If your products have coordinates (WGS84), limit results by distance from the user:

With multipart, send them as form fields. Otherwise use query parameters: POST /find/v1.1?lat=52.52&lon=13.405&dist=10000. Field names follow docs.nyris.io; the example web app sends latitude / longitude form fields instead.

Search response

{
  "results": [
    {
      "sku": "ABC-100",
      "score": 0.91,
      "title": "Hydraulic pump",
      "image": "https://..."
    }
  ],
  "id": "request-id",
  "session": "session-id"
}

Field names on each product depend on the index. Always read sku (fall back to key or objectID if you see those). Keep id and session for feedback.

results is already sorted by visual similarity. Keep that order; do not re-sort by stock, popularity, or recommendations. score is an internal ranking signal. Do not show it as a percentage or confidence on result cards. Users treat that number as accuracy, and it is misleading.

results: [] with HTTP 200 means the search ran and nothing matched. It does not mean the request was malformed. An empty result after a text search is often the text query-string mistake above.

Feedback

Optional. Improves analytics in the portal.

On a website that calls the Find API from the browser, the nyris events tracking script can send clicks and conversions for you. See Events tracking script in Analytics & Feedback. Use the raw API below for mobile apps, backends, or custom tracking.

POST /feedback/v1
X-Api-Key: <find-key>
Content-Type: application/json

{
  "request_id": "<id from find>",
  "session_id": "<session from find>",
  "timestamp": "2026-09-28T12:00:00.000Z",
  "event": "click",
  "data": { "positions": [0], "product_ids": ["ABC-100"] }
}

timestamp is ISO 8601 UTC and required. A valid event returns HTTP 2xx.

Recommend by SKU

When the user is already on a product page:

GET /recommend/v1/{sku}
X-Api-Key: <find-key>
Accept: application/items.complete+json

Returns visually similar products. The SKU itself is not in the results.

Product images by SKU

GET /find/v1.1/images/{sku}
X-Api-Key: <find-key>
Accept: application/items.complete+json

Returns { "images": ["https://img.nyris.io/..."] }.

Speed

Most of the wait is upload plus the model, not your UI. Shrink the JPEG on the device, show the photo immediately, and do not block the screen on a spinner.

Shrink before upload

A 4000×3000 camera JPEG is several megabytes. The area resize in Image pipeline usually produces about 100 kB. That is the single biggest win.

• Resize on the device, not on a server round-trip you control.
• Use JPEG quality 0.9, then 0.8 if you are still over ~200 kB.

Show something before the response

The example web app:

1. Navigates to the results route as soon as the user drops a file.
2. Shows the preview from the local file.
3. Renders skeleton cards while results is empty and the request is in flight.
4. Clears the previous product list when a new search starts, so stale products do not flash.

Do not cover the page with a full-screen blocking overlay.

Overlap network calls

Regions and the first Find call both need the resized JPEG. Start them together:

original = normalize(image)          # decoded, EXIF-rotated, flattened
jpeg = resize(original)
start find(jpeg)                     # full frame, show these products first
start regions(jpeg)                  # when this returns, draw boxes
# if the user changes the box:
start find(resize(crop(original)))   # crop the original, then resize

Skip the parallel full-frame Find when results go through an existing text search engine. Each Find there also costs an engine query, and the page would flip when the crop result arrives. See Combine with your text search.

Cancel the previous Find if the user fires another search before it finishes (AbortController, URLSession task cancel, OkHttp Call.cancel()). Ignore responses that are not the latest request id you stored.

Text input: debounce about 300 ms so you do not search on every keystroke.

Connection setup

• preconnect to https://api.nyris.io (and https://img.nyris.io for product images) on the page that can start a search: <link rel="preconnect" href="https://api.nyris.io">.
• Reuse HTTP connections. Browsers do this for fetch. On mobile, use one URLSession / one OkHttp client, not a new client per request.
• Prefer multipart or raw bytes over the JSON base64 body when you can choose. Base64 adds about 33% to the upload. If your platform needs JSON, it works fine; just resize first.

What not to do

• Do not upload the original camera file “and let the API resize it”.
• Do not wait for regions before showing the preview.
• Do not run region detection again when only the text query changed.

Mobile apps

The HTTP contract does not change. Only capture, decode, and resize change.

Snippets: examples/swift/Find.swift, examples/kotlin/Find.kt.

nyris also publishes native SDKs with camera UI and API client: SDK.Android and Nyris.IMX.iOS. Use them if you want a ready-made flow; use this chapter if you build your own.

iOS (Swift)

1. UIImagePickerController or PHPickerViewController for the library. AVCaptureSession for the camera.
2. Draw the UIImage into a new bitmap. UIKit applies EXIF orientation when you draw.
3. Flatten, crop, area-resize, jpegData(compressionQuality: 0.9).
4. URLSession upload task, multipart body, header X-Api-Key.

func jpegForSearch(image: UIImage, maxSide: CGFloat = 1024, quality: CGFloat = 0.9) -> Data? {
    let aspect = image.size.width / image.size.height
    let area = maxSide * maxSide
    let width = max(1, (area * aspect).squareRoot().rounded())
    let height = max(1, (width / aspect).rounded())
    let format = UIGraphicsImageRendererFormat.default()
    format.scale = 1 // default() uses the screen scale; sizes here are pixels
    format.opaque = true
    let renderer = UIGraphicsImageRenderer(size: CGSize(width: width, height: height), format: format)
    let rendered = renderer.image { ctx in
        UIColor.white.setFill()
        ctx.fill(CGRect(x: 0, y: 0, width: width, height: height))
        image.draw(in: CGRect(x: 0, y: 0, width: width, height: height))
    }
    return rendered.jpegData(compressionQuality: quality)
}

Store the key in the app target as a build setting or remote config, not in a screenshot in the repo. A Find-only key in the binary is the model this guide uses.

Android (Kotlin)

1. Photo Picker or CameraX.
2. Decode with BitmapFactory.Options.inSampleSize so you never allocate the full 12 megapixel bitmap.
3. Rotate using ExifInterface before the exact scale.
4. Draw on a white canvas, compress(JPEG, 90, stream).
5. OkHttp MultipartBody.FORM, part name image. execute() blocks, so call it off the main thread.

fun jpegForSearch(source: Bitmap, maxSide: Int = 1024, quality: Int = 90): ByteArray {
    val aspect = source.width.toFloat() / source.height
    val area = maxSide * maxSide.toFloat()
    val width = kotlin.math.sqrt(area * aspect).roundToInt().coerceAtLeast(1)
    val height = (width / aspect).roundToInt().coerceAtLeast(1)
    val out = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888)
    val canvas = Canvas(out)
    canvas.drawColor(Color.WHITE)
    val paint = Paint(Paint.FILTER_BITMAP_FLAG) // smooth downscaling
    canvas.drawBitmap(source, null, RectF(0f, 0f, width.toFloat(), height.toFloat()), paint)
    val stream = ByteArrayOutputStream()
    out.compress(Bitmap.CompressFormat.JPEG, quality, stream)
    return stream.toByteArray()
}

HEIC from the camera is already a Bitmap after ImageDecoder / BitmapFactory on current Android. You do not upload the HEIC container.

React Native

Use the system picker (expo-image-picker or react-native-image-picker). Ask the picker to resize (quality: 0.9, maxWidth / maxHeight around 1024) or resize yourself so you match the area formula.

Send with FormData:

const body = new FormData();
body.append("image", {
  uri: asset.uri,
  name: "query.jpg",
  type: "image/jpeg",
});
await fetch("https://api.nyris.io/find/v1.1", {
  method: "POST",
  headers: {
    "X-Api-Key": apiKey,
    Accept: "application/items.complete+json",
  },
  body,
});

On React Native, do not set Content-Type: multipart/form-data by hand; the boundary would be missing.

Flutter

image_picker returns a file. Package image can decode, bake orientation, resize, and encodeJpg(quality: 90). Upload with package:http MultipartRequest and MultipartFile.fromBytes.

Shared UI

• Full-screen camera is optional. A gallery button plus a camera button is enough.
• Show the captured photo immediately, then skeleton results.
• One box overlay using normalized coordinates. Pinch-to-zoom on the preview is optional.
• Read the key from configuration (build setting or remote config). Do not ask users to paste a key. The example web app reads it from settings.js or from the signed-in user.

Errors and keys

Status codes

The example client throws if apiKey is empty before the request (The api-key is not set.). Surface that as “search is not configured”, not as “no products”.

Retries

Retry only idempotent search POSTs that failed on the network or with 5xx. Do not retry 400, 401, or 413 without changing the request, the key, or the image.

Images under 100 px on the shortest edge are not an error. The API accepts them, but results deteriorate, so show the user a hint instead of blocking the search.

If the user already started a newer search, drop the old response even if it succeeds later.

Key in the app

This guide sends X-Api-Key from the website or the mobile app.

• Use a Find key. Anyone with the app can extract it and run searches on your index.
• Do not ship a Data Management key in a client. That key can change the catalog.
• If it leaks, ask support@nyris.io to rotate the Find key, then ship an app update. Loading the key from your own config endpoint avoids the app update.
• Do not log the key, do not put it in analytics, and do not commit it. Samples read NYRIS_API_KEY.

Add a backend proxy when at least one of these is true:

• You must not expose a key at all.
• You already have user login and want per-user quotas.
• You need to attach prices or stock that must not be guessed from the client.

The proxy is a thin POST forwarder: the app uploads the JPEG to you, you add X-Api-Key, you call https://api.nyris.io/find/v1.1, you return the JSON. Keep the resize on the device so your server does not receive multi-megabyte photos.

Request options

X-Options is an optional request header of space-separated key=value flags. The public ones are limit (1 to 100, default 20) and threshold (minimum score), for example X-Options: limit=10 threshold=0.5. The index already has server-side defaults. Leave the header unset until you have a reason to change ranking. See Find API.

Combine with your text search

Most shops already have a search results page powered by a text search engine (Algolia, Elasticsearch, OpenSearch, Typesense, Meilisearch, Coveo, Bloomreach, and so on). Do not build a second results page for visual search. Use the existing one and add the image as a new kind of query.

nyris decides which products match and in which order. Your text search engine supplies everything else: the product records, the product cards, facets, filters, pagination, prices, stock, visibility rules, and analytics.

Rule 1: one results page

Visual search is a query mode of the normal search results page, not a separate screen.

• The search box shows the query image as a thumbnail chip with a remove (×) button. Removing it returns to normal text search.
• The image preview with region markers sits above the results, or in a side column on wide screens. It collapses on small screens. It follows the Region overlay rules: a dot per object, a box only on the selected object, the rest dimmed.
• Facets, filters, product cards, badges, and pagination are the same components the text search uses.
• Clicking another object or dragging a new crop runs a new visual search and refreshes the same page.
• When the user adds an image, clear the typed text query and the selected facets. The image is a new search.

Rule 2: nyris order is final

Visual search is exact search. The user photographed a specific item and expects the most visually similar product first. Keep the order nyris returns. Nothing may reorder it.

For visual search queries:

• No relevance re-ranking by the text engine.
• No merchandising rules, pinned or promoted items, or banners inserted into the result list.
• No personalization, dynamic re-ranking, or "AI ranking" features.
• No boosting or sinking by stock, margin, popularity, rating, or newness.
• No recommendations or sponsored products mixed into the list. Recommendation carousels may appear below the results, clearly separate, never interleaved.
• Out-of-stock products stay in their position and stay visible. Show the normal out-of-stock badge.
• The only sort is "Most similar". Hide or disable the sort dropdown while an image is active.
• Do not show the nyris score or a percentage. See Find API.

Filters and facets may remove products. The remaining products keep their nyris order.

Rule 3: same product IDs in both systems

The join works only if a nyris sku identifies the same product in your text search index, for example the Algolia objectID or an sku attribute. Agree on this mapping before you write code.

• nyris returns a product that the text index does not have: drop it and report it as a catalog sync problem. Do not log every miss from every browser; sample or aggregate.
• The text index hides a product (unpublished, wrong market, not visible to this customer group): drop it. Keep the order of the rest.
• Never backfill missing positions with text search results, bestsellers, or recommendations.
• If the index groups variants (one record per product, many SKUs), decide whether nyris SKUs are variant or parent IDs and map them accordingly. Turn off result grouping (distinct in Algolia, collapse in Elasticsearch) for visual queries, or the engine may return a different variant than the one nyris matched.

How it works

1. Run the nyris image pipeline as in Agent Guide: normalize, resize, Regions, auto-select the best object, then one Find with that crop. With a text engine, do not also run a full-frame Find in parallel. That would cost a second engine query and make the results page flip.
2. Ask nyris for enough candidates for facets to be useful: X-Options: limit=100, the maximum (see Errors and keys). The default of 20 is fine for a plain list, but facets over 20 products are thin.
3. Take results[].sku in order. Build a rank map sku → position. If a SKU appears twice, keep the first position.
4. Query the text engine with an empty text query, restricted to those SKUs, plus whatever facet filters the user selected and the filters the page always applies (market, visibility, customer group). Ask for all of them in one page and request facet counts.
5. Sort the returned records by the nyris rank map. Records the engine did not return are gone (filtered or missing).
6. Render with the existing product cards. Paginate over the reordered list in the client; with at most 100 products this is one engine request.

When the user changes a facet, repeat steps 4 and 5 with the same SKU list. Do not call nyris again; the image did not change. When the user changes the crop, start again at step 1 and clear the selected facets.

Treat the whole chain (nyris, then the engine) as one search for stale-response handling. If the user changes the crop or a facet while a request is in flight, abort it or ignore its result.

Why reorder in your code

Text engines rank by their own criteria: text relevance, custom ranking, rules, personalization. Even with an empty query, the order they return is not the nyris order. Reordering by the rank map in your code is the only engine-independent way to guarantee it. Also switch off engine features that add, pin, or remove items (see the engine notes below), because reordering cannot undo an inserted or hidden product.

Elasticsearch can also return documents in a given ID order with a pinned query (at most 100 IDs; OpenSearch has no pinned query). That is optional. Keep the client-side reorder anyway as the final guarantee.

Known limitation: facets see only the candidates

Facets narrow the up to 100 products nyris returned. A product of the selected brand at nyris position 150 will not appear, and facet counts describe the candidates, not the catalog. If a facet also exists as a nyris filter (GET /find/v1/filters), you may re-run Find with that filter instead, so nyris searches within the brand. See Find API.

Text and image together

If the user types a keyword while an image is active, the keyword narrows the visual results. It does not re-rank them. Pick one approach for the whole site:

• Keyword in the engine: send the keyword to the text engine as the query, still restricted to the nyris SKUs. Do not send text to nyris. Reorder by the nyris rank map as usual; the engine's relevance order is discarded.
• Keyword in nyris: send text to nyris together with the image (see Find API), then continue at step 3 with the new nyris order.

Do not run a separate full-catalog text search and merge the two lists.

Example: Algolia

Shown with the algoliasearch v5 JavaScript client and a search-only key.

import { algoliasearch } from "algoliasearch";

const algolia = algoliasearch(ALGOLIA_APP_ID, ALGOLIA_SEARCH_KEY);
const LAST = Number.MAX_SAFE_INTEGER;

interface ProductHit {
  objectID: string;
  [field: string]: unknown;
}

function quoteFilterValue(value: string): string {
  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
}

function skuFilter(skus: string[]): string {
  return skus.map((sku) => `objectID:${quoteFilterValue(sku)}`).join(" OR ");
}

function rankMap(skus: string[]): Map<string, number> {
  const rank = new Map<string, number>();
  skus.forEach((sku, index) => {
    if (!rank.has(sku)) rank.set(sku, index);
  });
  return rank;
}

export async function visualResults(
  nyrisSkus: string[],
  facetFilters: string[][],
  pageFilters: string,
) {
  if (nyrisSkus.length === 0) return { hits: [], facets: {} };

  const rank = rankMap(nyrisSkus);
  const skuRestriction = `(${skuFilter(nyrisSkus)})`;

  const response = await algolia.searchSingleIndex<ProductHit>({
    indexName: "products",
    searchParams: {
      query: "",
      filters: pageFilters ? `(${pageFilters}) AND ${skuRestriction}` : skuRestriction,
      facetFilters,
      facets: ["*"],
      hitsPerPage: rank.size,
      distinct: false,
      enableRules: false,
      enablePersonalization: false,
      enableReRanking: false,
      analyticsTags: ["visual-search"],
    },
  });

  const hits = [...response.hits].sort(
    (a, b) => (rank.get(a.objectID) ?? LAST) - (rank.get(b.objectID) ?? LAST),
  );
  return { hits, facets: response.facets ?? {} };
}

Notes:

• enableRules: false stops Query Rules from pinning, hiding, or inserting items. enablePersonalization: false and enableReRanking: false stop personalization and Dynamic Re-Ranking from changing the order. distinct: false stops variant grouping. Use these settings for visual queries only; text search keeps its normal settings.
• pageFilters are the filters your page always applies (market, visibility). Combine them with the SKU restriction using AND; never replace them.
• If the SKU is stored in another attribute than objectID, filter on that attribute and sort by it (hit.sku). It must be in attributesForFaceting, for example as filterOnly(sku).
• A single searchSingleIndex call returns conjunctive facet counts: after the user picks one brand, the other brands drop out of the brand facet. The existing results page usually shows disjunctive counts. Get those from InstantSearch or the Algolia helper, which send the extra queries for you, or send one extra query per refined facet yourself.
• Use analyticsTags so visual searches do not distort text search analytics. If you also send Algolia Insights events, set clickAnalytics: true to get a queryID, and tag the events as visual search so they do not train the text ranking.

With InstantSearch

Keep the existing facet, refinement, and hits widgets. While an image is active:

• Add the SKU restriction and the settings above through the Configure widget. If the page already sets filters there, AND the SKU restriction onto the existing value instead of replacing it.
• Set hitsPerPage to the number of SKUs and reorder in the hits widget's transformItems with the rank map.
• Hide the stock pagination widget and paginate the reordered hits in the client. Server-side pages would split the nyris order across requests.
• If URL routing is on, keep the SKU list out of the URL (exclude it in stateMapping). Otherwise a reload restores the SKU restriction without the image.

Remove all of this when the user removes the image.

Example: Elasticsearch / OpenSearch

Restrict with a terms filter on the SKU field (mapped as keyword). Put the page's fixed filters in query, and the user's facet selections in post_filter, so facet counts stay disjunctive like on the normal results page:

{
  "size": 3,
  "query": {
    "bool": {
      "filter": [
        { "terms": { "sku": ["ABC-100", "XYZ-7", "QRS-55"] } },
        { "term": { "market": "de" } }
      ]
    }
  },
  "post_filter": { "term": { "brand": "norelem" } },
  "aggs": {
    "brand": { "terms": { "field": "brand", "size": 50 } }
  }
}

Set size to the number of SKUs. Do not wrap this in a function_score, add collapse, or apply learning-to-rank for visual queries. Then sort the hits by the nyris rank map before rendering.

Where to run the join

Either way, the image pipeline (normalize, resize, crop) runs on the device before upload. See Image pipeline.

When the engine renders the product cards, nyris only needs to return SKUs. You may request Accept: application/minimal+json to make the response smaller, but then you cannot show nyris products on their own (see the text engine failure row below).

Analytics and feedback

• Send nyris feedback (POST /feedback/v1) for clicks and conversions with the nyris request id. Set positions to the product's zero-based index in the nyris results list, not its position on the filtered page, and always include product_ids. See Find API.
• If the text engine records clicks, tag them as visual search (see the Algolia notes).

Empty states and errors

Checklist

• Visual search uses the existing search results page, with the image as a removable chip and the region preview on the same page.
• nyris sku maps to a product ID in the text index, and the mapping was tested on real products, including variants.
• Results appear in exactly the nyris order. A test compares the rendered order with the nyris response.
• Merchandising rules, personalization, re-ranking, result grouping, and promoted items are off for visual queries only.
• The page's fixed filters (market, visibility) still apply to visual queries.
• Out-of-stock products keep their position and show the normal badge.
• There is no sort option other than "Most similar" while an image is active.
• Selecting a facet narrows the list without reordering it, and does not call nyris again.
• Changing the crop calls nyris again, clears facets, and resets the list.
• Products missing from the text index are dropped and reported, never backfilled.
• No score or percentage is shown.
• Recommendations, if any, are below the results and visually separate.

Examples

Runnable clients for the Find API. They read NYRIS_API_KEY from the environment. Download them all as nyris-examples.zip, or one at a time:

• curl/find.sh
• python/find.py
• node/find.mjs
• swift/Find.swift
• kotlin/Find.kt

Run them from the examples folder:

export NYRIS_API_KEY="your-find-key"

sh curl/find.sh text "chair"
python3 python/find.py text "chair"
node node/find.mjs text "chair"

Image search expects a JPEG. The scripts label every upload image/jpeg, so convert PNGs first (the API accepts PNG, but these scripts do not detect it). Resize in your app first; these scripts upload the file as given so you can see the HTTP contract.

image-json sends the same image as a JSON body with base64, for platforms that only speak JSON:

python3 python/find.py image-json ./query.jpg

resize-check prints the area-based output size and does not call the network:

python3 python/find.py resize-check 3000x2000
node node/find.mjs resize-check 3000x2000

Swift and Kotlin files are reference snippets. They are not a full Xcode or Gradle project.

Authentication

All nyris API requests require an API key passed in the X-Api-Key header.

How do I get an API key?

To get started, email us at support@nyris.io. Our team will provision an API key for you.

You can call the API from a website or app. A key shipped in frontend code can be read from the page source or from the requests the browser sends, so treat it as public. If you want the key to stay on your server, send requests through your own backend, which then calls the nyris API.

Find API

Send an image to the Find API and receive a JSON object with metadata for the identified items. You can optionally pass a session ID to correlate multiple requests.

POST https://api.nyris.io/find/v1.1

To search with filters, send the image and filter fields as multipart/form-data. Filtered responses include only items matching the given filter types and values. You can also append a session ID as a query parameter: POST https://api.nyris.io/find/v1.1?session=xxxxxx.

Request Headers

If no value is provided for X-Session (or the session query argument), a new session is started and its ID is returned with the response. Front-ends are encouraged to pass the session ID returned by the previous request to the next request, thereby linking requests together.

Request Body

• Image only (binary): send the raw image bytes as the request body with Content-Type: image/jpeg or image/png.
• Image with filters (multipart): use multipart/form-data and include the image plus the filter fields described below. An optional text form field sends a text query.
• JSON body (base64): send Content-Type: application/json with a JSON object. The image is a base64-encoded string. You can also send text without an image for a text-only search.

JSON Body Schema

With a JSON (base64) body, the 2 MB limit applies to the decoded image. The encoded request is about 33% larger than the image.

Filter Schema (multipart)

When sending filters via multipart/form-data, include one or more filter type/value pairs. The AND operator is used between filter types; OR is used between values of the same type.

Form field names are indexed: filters[0].filterType, filters[0].filterValues[0], filters[0].filterValues[1], filters[1].filterType, and so on.

Send text as a form field, not as a query parameter. A text query parameter is ignored.

Search Parameters (X-Options)

Control result count and score thresholds via the X-Options header. Parameters are key=value pairs separated by a space, e.g. X-Options: limit=10 threshold=0.5.

Response Headers

Requests are automatically tagged with a Request ID and a Session ID:

Both headers are exposed to browsers via CORS. The same values are in the body as id and session.

Response Format

By default, a minimal response is returned. Use the Accept header to request the full format:

We guarantee that existing fields will not be removed or have their type changed. Additional fields can be added at any point; application code should gracefully ignore unknown fields.

Image Requirements

Convert other formats (HEIC from iPhones, TIFF, BMP, GIF, PDF pages) to JPEG on the client before sending. Base64 is only a transport encoding: the image inside a JSON body must still be JPEG, PNG, or WebP.

Resize and crop on the client before sending. Apply cropping to the original image first, then resize.

With a JSON (base64) body, the 2 MB limit applies to the decoded image. The encoded request is about 33% larger than the image.

A binary body with Content-Type: image/webp is not accepted. Send WebP as multipart or JSON.

Error Responses

Additional fields may appear. Application code should ignore fields it does not use.

Geolocation

If products have geolocation data, you can narrow results by distance. Coordinates must be in WGS84 format.

When using multipart/form-data (for filters), pass geolocation as form fields. Otherwise, use query parameters: POST https://api.nyris.io/find/v1.1?lat=LAT&lon=LON&dist=DIST.

Regions API

The Find API matches on the entire image. For images containing multiple objects, you may want to detect and crop to specific areas first. The Regions API identifies parts of the image likely to contain relevant objects, allowing your UI to propose sections of the image for the user to search with.

POST https://api.nyris.io/find/v2/regions

Request Headers

Request Body

• Binary: send the raw image bytes as the request body with Content-Type: image/jpeg, image/png, or image/webp.
• Multipart: use multipart/form-data and include the image as a file field named image.
• JSON body (base64): send Content-Type: application/json with a JSON object containing the image as a base64-encoded string.

JSON Body Schema

Response Format

The response contains a regions array. Each region has a confidence score (0–1) and a bounding box with pixel coordinates relative to the submitted image.

The response may contain additional fields, including modelName and modelVersion at the top level. Ignore fields you do not use.

Recommend API

Get visually similar items for a product in your catalogue by submitting its SKU. Since we already have your product data (from the feed import), we perform a visual similarity search based on the main image of the given product. The submitted SKU itself is excluded from results.

GET https://api.nyris.io/recommend/v1/{sku}

Request Headers

Path Parameters

Images API

Retrieve the public images associated with a product by its SKU.

GET https://api.nyris.io/find/v1.1/images/{sku}

Request Headers

Path Parameters

Filter API

Retrieve the available filter attributes that can be used with the Find API.

GET https://api.nyris.io/find/v1/filters

Request Headers

An optional limit query parameter is accepted, for example GET https://api.nyris.io/find/v1/filters?limit=100.

To look up values for one filter key, call GET https://api.nyris.io/find/v1/filters/{key}/{value}?limit=100. The response is a JSON array of strings.

Widget (JS)

The fastest and easiest way to integrate visual search to your website is using our Javascript Widget. All you have to do is to add some lines of code to a runtime file of your website and you are ready to start using visual search.

What I need to start using this code?

You need to follow these steps:

1. Copy the script into a text editor and configure the settings parameters.

2. After making the necessary updates, copy all the lines and add to the runtime file (ex. index.html) to embed the visual search widget into your platform.

Done. You are ready to use visual search on your website!

Sample

See the nyris demo widget in action: https://widget.nyris.app/

Where is the source code? Can I change it

The code is on github. Follow the readme file to build the project. You can change or adjust the JS / CSS files according to your needs and host them on your server as well.

Android SDK

You can find the latest Android SDK including the implementation documentation on github:

https://github.com/nyris/SDK.Android

iOS SDK

You can find the latest iOS SDK including the implementation documentation on github:

https://github.com/nyris/Nyris.IMX.iOS

Should you have any questions, please send an e-mail to support@nyris.io

Submit your product data

There are several ways to submit your product and image data to us. You can provide any kind of structured file that we can pull (xml, csv, txt, json, etc.), or use the Data Management API to programmatically manage your items and images. If you are already providing your data to an affiliate network like Affilinet, Awin or Google Shopping, you are probably all set for the start. In this case we just need access to your feed URL. Please be aware that those feeds usually only include the link to the main product image. As image recognition works best the more images of a specific product we have, you might need to adjust those feeds to include all your product images. Please find more details below.

Feed Format & Updates

• The feed can be submitted as csv, xml, txt or json file
• Preferred encoding for the files is UTF-8
• For csv, please use if possible "," as delimiter and '"' (double quote) for enclosing text
• Please provide us with a link to your feed. If the access to the feed is secured with username/password, please also provide us those credentials
• Please revise your server settings in order to ensure that the IP address we use to access your server remains unblocked at all times in spite of frequent accessing
• Your feed will be imported daily. Should you need shorter import cycles, please contact support@nyris.io

If you don't have a product feed, we can also directly access your product data through an API for the following systems:

Shop Systems

• BigCommerce
• Magento 1.x SOAP
• PrestaShop
• Shopify
• WooCommerce

PIM

• Akeneo
• hybris

You can also create a data feed using Google Sheets. Details on how to use Google Sheets and an example file can be found in a section below.

Data Management API

The Data Management API lets you programmatically manage items and images in your nyris index. Use it to create, update, list, and delete product data and associated images.

The Data Management API requires a separate API key. For security, the keys used for the Find API and Recommend API do not work with the Data Management API, and vice versa. Contact mailto:support@nyris.io to obtain your Data API key.

The full OpenAPI reference is available at api.nyris.io/manage/swagger.

Authentication

All Data Management API requests require an API key passed via the X-Api-Key header. This key is different from the one used for the Find and Recommend APIs.

Create an Item

Creates a new item in your index. The key field is required and must be unique within your index.

Upsert an Item

Creates an item if the key does not exist yet, or updates the existing item. This is the recommended way to keep your index in sync with your product catalog.

The request body is the same as for creating an item. Returns 201 if a new item was created, 200 if an existing item was updated.

List Items

Returns a paginated list of items in your index.

Get Item by Key

Retrieves a single item using your unique key.

Delete an Item

Deletes an item by its unique key. All associated images are also removed.

Add an Image to an Item

Adds an image to an existing item, identified by its key. You can provide the image as a URL (JSON body) or upload it directly (multipart/form-data or raw image bytes).

Get Images for an Item

Returns all images belonging to an item.

Delete an Image

Removes a specific image by its ID.

Full API Reference

The complete OpenAPI specification, including all endpoints, schemas, and error codes, is available in the interactive Swagger documentation:

api.nyris.io/manage/swagger

You can also import the OpenAPI spec directly into Postman or other API tools using the JSON URL:

https://api.nyris.io/manage/swagger/v1/swagger.json

Available Feed Attributes

The bare minimum is a unique ID (sku) and the main_image_link. To get a full list of possible attributes please download the following sheet or use a copy of it as base for your item or product feed. When gathering your data, please keep always in mind that all submitted information will be used for improving your search results. Completeness and quality of data often makes the difference:

Download Feed Example and full attribute description (google sheets)

Required Fields

Optional Fields

Image Links

To improve the search, additional images can be provided. All referenced images (main, additional and recognition types) are used for search. main and additional images are treated identically, with the main image being the designated reference to be shown e.g. in the Portal. If requested, these image links can be returned as part of the response. recognition image links, on the other hand, are purely used for recognition and are never returned as part of any response.

Textual description

Providing these values will enable both OCR (text matching) functionality, finer grained recognition of results and item class distribution results. While optional, providing these values is thus strongly recommended.

Key-value pairs

By providing custom key-value pairs, we are able to improve detection in combination with text matching functionality, and/or will be able to return named IDs as part of the response. If your system requires multiple IDs or custom data pairs, use these fields.

Catalog numbers

These values are mainly used for identifying products within catalogs, and catalogs by IDs.

Keywords

These values are used for exactly matching keywords, such as item materials, colors, etc., with text found during OCR; thus, providing these values improves text matching. Keywords are treated as a set, so values specified multiple times would be considered identical.

To simplify specification of keywords, you can specify keywords in a delimiter-separated list via the configurable keywords column. By default, keywords are split at the , (comma) delimiter:

To provide single keywords or individual keywords per column, use the keyword / keyword_N variant instead. Here, values are not split:

Geolocation Fields

If provided, the coordinates can be used to narrow down the search by the location of the product. The provided coordinates have to be in the WGS84 format with signed decimal numbers as the notation.

Item relations

Some items are related to other entries, and some IDs may have different meaning across logical separations of feeds (e.g. when there is a feed per country).

Item URLs

PreFilter Attributes

Other Optional Fields

Visual search analytics show how customers interact with search results and help improve search performance over time.

Nyris provides two levels of analytics:

This document covers click & conversion analytics — how to send customer events to the Nyris Feedback API.

1. Recommended: Events tracking script

For most commerce stores, use the Nyris events tracking script — a single drop-in snippet that captures searches, clicks, and conversions automatically.

What the script does

Once embedded, the script:

• intercepts Nyris Find API responses and captures the request_id of each search,
• detects clicks on search-result cards and CTA buttons,
• detects add-to-cart actions by configurable button labels,
• forwards conversions declared via HTML attributes, JavaScript, or your GA4 dataLayer,
• and posts events to the Feedback API, keyed to the originating search.

It requires no changes to your store's source code in the typical case and is built so it cannot break the host page (all logic is error-isolated).

Quick start

Place the tag in the <head>. async is recommended.

Minimal — only the API key is required:

Typical commerce setup — configure result cards, product ids, and add-to-cart labels:

With this markup, a click on the card (or its link) is reported as a click, and a click on the add-to-cart button is reported as a conversion — both carrying the product id:

Prerequisites

The script works when the browser calls the Nyris Find API directly (https://api.nyris.io/find/...). It intercepts those responses to obtain the request_id.

If your store proxies search through your own backend and never calls the Find API from the browser, inject the request id into the results container instead:

Without a request_id (from interception or data-nyris-request-id), click and conversion events are not sent.

Product id resolution

The tracker resolves the product id for each result card in this order:

1. Attribute — value of data-product-id-attr on (or inside) the card (default: data-product-id).
2. Text — trimmed text of data-product-text-selector, if configured.
3. Position — SKU at the same zero-based position in the Find API response (no DOM markup required).

For most stores the position fallback works out of the box when result order matches the API response.

Button label matching

Add-to-cart and support requests are detected from the text of the button that was clicked. The same matcher backs data-cart-button-labels and data-support-button-labels.

Multilingual stores: list every language in the same attribute. Labels are comma-separated and there is no locale detection — a click counts when any label matches:

Matching rules:

• Case-insensitive. ADD TO CART and in den warenkorb both match.
• Setting the attribute replaces the defaults (Add to cart, Add to basket, In den Warenkorb) rather than adding to them, so list every label you need. Clicks that match no label are reported as an ordinary click.
• Exact or prefix. Add to cart also matches Add to cart – €49.99, which is useful for buttons that include a price. A very short label such as Add will over-match — keep labels specific.
• Ancestor walk. Matching starts at the clicked element and walks up to 6 ancestors, skipping any whose combined text exceeds 60 characters. This lets a click on an icon or <span> inside the button register, without a whole card counting as a button.

For support requests, pair the labels with data-support-button-scope so only clicks inside your inquiry dialog qualify — see below.

Declaring purchases and support requests

Add-to-cart is detected automatically from button labels. Purchases and support requests must be declared when they happen.

Supported conversion subtypes (fixed): add_to_cart, purchase, support_request. Unknown values are ignored by the tracker.

Purchase — HTML attributes:

Support request — script tag only (preferred for inquiry Send):

No button markup. Matching label clicks inside the scope fire support_request. Omit scope only for intentional page-wide matching.

Or mark a specific button with data-nyris-conversion="support_request".

JavaScript API:

Custom DOM event (useful with tag managers):

If you already send GA4 e-commerce events to window.dataLayer, enable the GA4 bridge (default) to mirror add_to_cart and purchase events automatically. Support requests are not a standard GA4 ecommerce event — declare them via HTML, JS, or the custom DOM event.

Configuration reference

Set options as data-* attributes on the script tag, or as window.nyrisTrackerConfig before the script loads.

window.nyrisTrackerConfig example:

JavaScript API

GDPR modes

The default cookiefree mode uses no cookies and no cross-session identifier. Confirm with your DPO whether a consent banner is required for your jurisdiction.

Debugging

Enable debug output while integrating:

Then open the browser console and look for [NyrisTracker] initialized, search captured, click, and add_to_cart / conversion messages.

When the script is not enough

Use the raw Feedback API implementation below if you:

• cannot call the Find API from the browser,
• need full control over event timing and payloads,
• integrate from a mobile app or server-side system, or
• already have your own analytics pipeline and only need to forward events.

2. Alternative: Raw Feedback API implementation

Implement click and conversion analytics yourself by POSTing JSON events to the Feedback API. Use this path when you cannot embed the tracking script or need a custom integration.

Overview

Every Find API response includes a unique request id and optionally a session id:

Store the request id when you receive search results. Attach it to every subsequent click or conversion event for that search.

Perform a Find API search first (see Find API documentation), then POST events to the Feedback API using the same API key.

Endpoint

Request headers

Request body

Every event is a JSON object with these fields:

A successful POST returns HTTP 2xx. Invalid JSON or missing required fields may return an error.

Event types

Click events

Tracks which result the user interacted with.

data properties:

Provide product ids where possible — they remain accurate even if the frontend reorders or filters results.

Example:

Conversion events

Tracks that a search result led to a conversion (add to cart, purchase, support request, etc.).

data properties:

The data field is optional. A conversion with no data still marks the request as successful if a prior click event was sent for the same request_id.

The API accepts any non-empty subtype string. For consistent analytics, use these fixed values:

Omit subtype for legacy undifferentiated conversions.

Example — add to cart:

Example — purchase:

Example — support request:

Example (minimal — relies on prior click):

Feedback events

End-user feedback on the overall result set, e.g. from a "Did we find what you were looking for?" prompt.

data properties:

Where possible, also send click and conversion events — they provide automatic, behaviour-based feedback.

Example:

Region events

Tracks the image region the user selected before searching (crop / object proposal mode).

data properties:

rect properties (all fractions in the range 0..1):

A region covering the full image: "x": 0.0, "y": 0.0, "w": 1.0, "h": 1.0.

Example:

Implementation checklist (raw)

1. Capture ids — On every Find API response, read X-Matching-Request / X-Session (or id / session from the JSON body if headers are not exposed).
2. Store ids — Keep the request id available for the user's session (in memory, session storage, or your backend).
3. Send click — When the user clicks a result, POST a click event with product_ids and positions.
4. Send conversion — When the user converts (cart, purchase, etc.), POST a conversion event with the same request_id and relevant product_ids.
5. Send feedback / region — If your UI collects explicit feedback or region selection, POST those event types as applicable.

Product ids must match the SKUs in your product data and Find API results, or Nyris cannot correlate events with your catalogue.

Example: end-to-end with curl

All event types should return HTTP 2xx when the payload is valid.