Design Similarity Search

Find similar design-registration candidates from a product image with region, Locarno and legal-status filters. Review evidence through REST API or MCP.

CostRecent 11 credits / call

Try online

POST · https://api.nexscope.ai/ai/designSimilaritySearchMCP · nexscope_design_similarity_search

What this API does

Find similar design-registration candidates using exactly one imageUrl or imageBase64. Base64 accepts 16–20971520 encoded characters. Preserve source order, coverage and warnings. Use image_url only when actually returned; image_available alone does not provide a URL. Results support review and do not establish infringement or freedom to operate.

Design Similarity Search API use cases

Search from an image URL

Supply the actual user-selected imageUrl to find similar design registrations and omit imageBase64. Apply only the requested region, Locarno and legal-status filters.

Search from local image bytes

Encode the local image as pure Base64 and supply imageBase64 without imageUrl. Keep the encoded text within the documented 16–20971520 character limit.

Review registration candidates

Retain returned candidate IDs, source order, coverage and warnings. Use a returned image_url unchanged. If the user requests details, reuse actual design_registration_id values in the separate registration-details operation.

Design Similarity Search API FAQ

What does the Design Similarity Search API return?

Find similar design-registration candidates from a product image with region, Locarno and legal-status filters. Review evidence through REST API or MCP. The documented output includes candidates.applicant_addresses.address, candidates.applicant_addresses.name, candidates.application_date, candidates.application_number, candidates.design_registration_id, candidates.designer_names, candidates.estimated_expiration_date, candidates.expiration_date_basis. It corresponds to the supplied imageUrl, imageBase64, title, topK, regions. Optional fields can be absent; a missing value should not be interpreted as a measured zero. Example values illustrate the response shape, rather than live account results.

How many credits does the Design Similarity Search API cost?

The current documented cost is Recent 11 credits / call. This is the same cost shown at the top of this page. If a range or estimate is displayed, the final charge depends on the request. Review your available credits and the pricing page before calling the API, and check API usage records for the actual charge.

How do I call the Design Similarity Search API from my app or an MCP client?

Send a POST request to https://api.nexscope.ai/ai/designSimilaritySearch with your API key as a Bearer token and the JSON inputs shown in API integration. In a compatible MCP client such as Claude or Cursor, connect Nexscope and call nexscope_design_similarity_search. Use the MCP arguments shown in the MCP guide, or switch Online test to MCP to review its request before adding it to your app.

View plans and credits Connect this API with MCP

Try this API

Endpoint

https://api.nexscope.ai/ai/designSimilaritySearch

MCP method

nexscope_design_similarity_search

Step 1 of 3 · Authenticate

Authentication

All run endpoints require a user API key. Send it as a bearer token in the Authorization header.

Authorization: Bearer nk-xxxxxxxxxxxxxxxxx

Missing or invalid API keys return an authentication error. Manage keys from .

Step 2 of 3 · Send a request

POSThttps://api.nexscope.ai/ai/designSimilaritySearch

Run an API

Send a JSON request body using the parameters described below.

Example request

Replace YOUR_API_KEY, then run this command in your terminal.

curl -X POST 'https://api.nexscope.ai/ai/designSimilaritySearch' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "imageUrl": "https://example.com/product.png",
  "title": "Bottle",
  "topK": 20
}'

Code example

{
  "imageUrl": "https://example.com/product.png",
  "title": "Bottle",
  "topK": 20
}

Step 3 of 3 · Inspect the result

Check the response

Read code for the request status and data for the result. Open the parameter and response reference for the full field definitions.

HTTP status codes

Code	Description
200	Default HTTP response for both success and many business errors. Only outer JSON code 0 indicates success or asynchronous acceptance; inspect data for the result.
429	Execution admission rate limit; honor Retry-After when present.
503	Execution admission is temporarily unavailable; honor Retry-After when present.
Opt-in	X-Nexscope-Http-Status: semantic maps controller-handled business errors to HTTP status on run and task routes. Pre-authentication failures, such as a missing or invalid API key (code 11209, including an incomplete or corrupted copy) or an expired website login session (code 12001), may still return HTTP 200 before this mapping. Always check the outer JSON code; malformed requests and infrastructure failures may also return non-200 HTTP responses.

View parameters & response Try online

All categories/ Design Registration Research

POSThttps://api.nexscope.ai/ai/designSimilaritySearch

Run this API

Send a JSON request to execute this API and receive the documented response payload.

Open tester

Endpoint

Method	`POST`
Path	`https://api.nexscope.ai/ai/designSimilaritySearch`
Auth	`Bearer API key`
Content-Type	`application/json`

Request parameters

Name	Type	Required	Description
`imageBase64`	`string`	optional	Pure Base64 image bytes, 16–20971520 characters; omit imageUrl. Pattern: ^[A-Za-z0-9+/]+={0,2}$ Minimum length: 16 Maximum length: 20971520
`imageUrl`	`string`	optional	Public HTTP(S) image URL, 8–4096 characters; exactly one image source. Format: uri Pattern: ^https?:// Minimum length: 8 Maximum length: 4096
`jurisdictionCodes`	`array`	optional	Up to 32 distinct source codes of 2–8 letters; intersects regions when both are supplied. Maximum items: 32
`jurisdictionCodes[]`	`string`	required	Up to 32 distinct source codes of 2–8 letters; intersects regions when both are supplied. Pattern: ^[A-Za-z]{2,8}$
`locarnoClasses`	`array`	optional	Up to 64 distinct NN-NN Locarno classes. Maximum items: 64
`locarnoClasses[]`	`string`	required	Up to 64 distinct NN-NN Locarno classes. Pattern: ^[0-9]{2}-[0-9]{2}$
`patentStatus`	`array`	optional	One or two distinct integers: 0 inactive, 1 active; omit for no status preference. Minimum items: 1 Maximum items: 2
`patentStatus[]`	`integer`	required	One or two distinct integers: 0 inactive, 1 active; omit for no status preference. Allowed: 0, 1
`regions`	`array`	optional	Up to 64 distinct two-letter region codes, e.g. US or EM; use EM for EU. Maximum items: 64
`regions[]`	`string`	required	Up to 64 distinct two-letter region codes, e.g. US or EM; use EM for EU. Pattern: ^[A-Za-z]{2}$
`title`	`string`	optional	Optional image context, 1–4096 trimmed characters; not a standalone text query. Minimum length: 1 Maximum length: 4096
`topK`	`integer`	optional	Candidate limit, 1–200; default 20. Default: 20 Minimum: 1 Maximum: 200
`topLoc`	`array`	optional	Up to 32 distinct two-digit Locarno prefixes; preserve leading zeros. Maximum items: 32
`topLoc[]`	`string`	required	Up to 32 distinct two-digit Locarno prefixes; preserve leading zeros. Pattern: ^[0-9]{2}$

One of option 1 — requires imageUrl

One of option 2 — requires imageBase64

Response example

Platform response envelope. code 0 indicates success or acceptance; data contains the business result.

{
  "code": 0,
  "cost": "-1",
  "data": {
    "data": {
      "code": "OK",
      "data": {
        "candidates": [
          {
            "applicant_addresses": null,
            "application_date": "2010-04-13",
            "application_number": "001694860",
            "design_registration_id": "DSR:euipo_design:001694860-0001",
            "designer_names": null,
            "estimated_expiration_date": null,
            "expiration_date_basis": null,
            "holder_names": [
              "237302"
            ],
            "image_url": "https://example.com/design-1.png?signature=example%2Bsignature&expires=2000000000",
            "images": [
              "https://example.com/design-1.png?signature=example%2Bsignature&expires=2000000000",
              "https://example.com/design-2.png?signature=second&expires=2000000000"
            ],
            "jurisdiction_iso2": "EM",
            "locarno_classes": [
              "06.01"
            ],
            "locarno_details": [
              {
                "code": "06.01",
                "label_en": null,
                "label_zh": null,
                "parent_code": "06"
              }
            ],
            "novelty_statement": null,
            "primary_identifier": "001694860-0001",
            "protected_jurisdictions": [
              "EM"
            ],
            "publication_date": null,
            "publication_number": null,
            "registration_date": null,
            "registration_jurisdiction_code": "EU",
            "registration_number": "E077151-PC",
            "risk_level": "medium",
            "similarity": 99.88,
            "simple_legal_status": "inactive",
            "specification": null,
            "title": "E077151-PC",
            "title_en": "Chairs [seats]",
            "title_language": "unknown",
            "tro_cases": []
          }
        ],
        "total": 1
      },
      "message": "success",
      "request_id": "req_example"
    }
  },
  "msg": null,
  "time": "2026-01-01 00:00:00",
  "traceId": null,
  "ts": "0"
}

Response fields

Name	Type	Required	Description
`code`	`integer`	required	0 means accepted or successful; nonzero is a platform error.
`cost`	`string`	required	Elapsed milliseconds, never credits; -1 outside web requests.
`data`	`any`	required	Data value used by this API operation.
`msg`	`string \| null`	required	Msg value used by this API operation.
`time`	`string`	required	Server local time: yyyy-MM-dd HH:mm:ss.
`traceId`	`string \| null`	required	Trace id value used by this API operation.
`ts`	`string`	required	Epoch milliseconds.

Any of option 1 — requires data

Name	Type	Required	Description
`data`	`object`	required	Data value used by this API operation.
`data.costTime`	`any`	optional	Cost time value used by this API operation.
`data.costToken`	`any`	optional	Cost token value used by this API operation.
`data.data`	`object`	required	Source envelope inside the gateway payload. Example: {}
`data.data.code`	`string`	required	Success is OK. Errors include 400 DATA_IMAGE_DOWNLOAD_FAILED (no image substitution), 413 SYSTEM_PAYLOAD_TOO_LARGE (no automatic compression), 502 SR_QUERY_ERROR and 503 CAPABILITY_BACKEND_UNAVAILABLE (backend failure, not zero hits or insufficient credits). Preserve actual code and request identifiers; no automatic retries. Example: OK
`data.data.data`	`object`	required	Search result; preserve optional coverage and warnings when returned. Example: {}
`data.data.data.candidates`	`array`	required	Candidates in returned order; empty is not freedom to operate. Example: [{"applicant_addresses":null,"application_date":"2010-04-13","application_number":"001694860","design_registration_id":"DSR:euipo_design:001694860-0001","designer_names":null,"estimated_expiration_date":null,"expiration_date_basis":null,"holder_names":["237302"],"image_url":"https://example.com/design-1.png?signature=example%2Bsignature&expires=2000000000","images":["https://example.com/design-1.png?signature=example%2Bsignature&expires=2000000000","https://example.com/design-2.png?signature=second&expires=2000000000"],"jurisdiction_iso2":"EM","locarno_classes":["06.01"],"locarno_details":[{"code":"06.01","label_en":null,"label_zh":null,"parent_code":"06"}],"novelty_statement":null,"primary_identifier":"001694860-0001","protected_jurisdictions":["EM"],"publication_date":null,"publication_number":null,"registration_date":null,"registration_jurisdiction_code":"EU","registration_number":"E077151-PC","risk_level":"medium","similarity":99.88,"simple_legal_status":"inactive","specification":null,"title":"E077151-PC","title_en":"Chairs [seats]","title_language":"unknown","tro_cases":[]}]
`data.data.data.candidates[]`	`object`	required	Item in data data data candidates.
`data.data.data.candidates[].applicant_addresses`	`any`	optional	Applicant addresses value used by this API operation.
`data.data.data.candidates[].application_date`	`any`	optional	Application date value used by this API operation.
`data.data.data.candidates[].application_number`	`any`	optional	Application number value used by this API operation.
`data.data.data.candidates[].design_registration_id`	`any`	optional	Design registration id value used by this API operation.
`data.data.data.candidates[].designer_names`	`any`	optional	Designer names value used by this API operation.
`data.data.data.candidates[].estimated_expiration_date`	`any`	optional	Estimated expiration date value used by this API operation.
`data.data.data.candidates[].expiration_date_basis`	`any`	optional	Expiration date basis value used by this API operation.
`data.data.data.candidates[].holder_names`	`any`	optional	Holder names value used by this API operation.
`data.data.data.candidates[].image_url`	`any`	optional	Image url value used by this API operation.
`data.data.data.candidates[].images`	`any`	optional	Images value used by this API operation.
`data.data.data.candidates[].jurisdiction_iso2`	`any`	optional	Jurisdiction iso2 value used by this API operation.
`data.data.data.candidates[].locarno_classes`	`any`	optional	Locarno classes value used by this API operation.
`data.data.data.candidates[].locarno_details`	`any`	optional	Locarno details value used by this API operation.
`data.data.data.candidates[].novelty_statement`	`any`	optional	Novelty statement value used by this API operation.
`data.data.data.candidates[].primary_identifier`	`any`	optional	Primary identifier value used by this API operation.
`data.data.data.candidates[].protected_jurisdictions`	`any`	optional	Protected jurisdictions value used by this API operation.
`data.data.data.candidates[].publication_date`	`any`	optional	Publication date value used by this API operation.
`data.data.data.candidates[].publication_number`	`any`	optional	Publication number value used by this API operation.
`data.data.data.candidates[].registration_date`	`any`	optional	Registration date value used by this API operation.
`data.data.data.candidates[].registration_jurisdiction_code`	`any`	optional	Registration jurisdiction code value used by this API operation.
`data.data.data.candidates[].registration_number`	`any`	optional	Registration number value used by this API operation.
`data.data.data.candidates[].risk_level`	`any`	optional	Risk level value used by this API operation.
`data.data.data.candidates[].similarity`	`any`	optional	Similarity value used by this API operation.
`data.data.data.candidates[].simple_legal_status`	`any`	optional	Simple legal status value used by this API operation.
`data.data.data.candidates[].specification`	`any`	optional	Specification value used by this API operation.
`data.data.data.candidates[].title`	`any`	optional	Title value used by this API operation.
`data.data.data.candidates[].title_en`	`any`	optional	Title en value used by this API operation.
`data.data.data.candidates[].title_language`	`any`	optional	Title language value used by this API operation.
`data.data.data.candidates[].tro_cases`	`any`	optional	Tro cases value used by this API operation.
`data.data.data.coverage`	`any`	optional	Coverage value used by this API operation.
`data.data.data.total`	`any`	optional	Total value used by this API operation.
`data.data.data.warnings`	`any`	optional	Warnings value used by this API operation.
`data.data.message`	`any`	optional	Message value used by this API operation.
`data.data.request_id`	`any`	optional	Request id value used by this API operation.
`data.data.usage`	`any`	optional	Usage value used by this API operation.
`data.dataSnapshotMonth`	`any`	optional	Data snapshot month value used by this API operation.
`data.page`	`any`	optional	Page value used by this API operation.
`data.pageItemCount`	`any`	optional	Page item count value used by this API operation.
`data.pageSize`	`any`	optional	Page size value used by this API operation.
`data.requestId`	`any`	optional	Request id value used by this API operation.
`data.sourceTool`	`any`	optional	Source tool value used by this API operation.
`data.sourceType`	`any`	optional	Source type value used by this API operation.
`data.title`	`any`	optional	Title value used by this API operation.
`data.totalPage`	`any`	optional	Total page value used by this API operation.
`data.type`	`any`	optional	Type value used by this API operation.
`data.upstreamRequestId`	`any`	optional	Upstream request id value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.costTime`	`integer`	optional	Execution time reported by the upstream provider. Example: null

Any of option 2

Name	Type	Required	Description
`data.costTime`	`null`	optional	Cost time value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.costToken`	`integer`	optional	Token cost reported by the upstream provider. Example: null

Any of option 2

Name	Type	Required	Description
`data.costToken`	`null`	optional	Cost token value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].applicant_addresses`	`array`	optional	Source applicant objects with name and address; never infer protection jurisdictions. Example: null
`data.data.data.candidates[].applicant_addresses[]`	`object`	required	Item in data data data candidates[] applicant_addresses.
`data.data.data.candidates[].applicant_addresses[].address`	`string`	optional	Source address; not evidence of protected jurisdiction. Example: Example address
`data.data.data.candidates[].applicant_addresses[].name`	`string`	optional	Source applicant name. Example: Example applicant

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].applicant_addresses`	`null`	optional	Applicant addresses value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].application_date`	`string`	optional	Source application date, YYYY-MM-DD. Example: 2010-04-13

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].application_date`	`null`	optional	Application date value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].application_number`	`string`	optional	Source application number. Example: 001694860

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].application_number`	`null`	optional	Application number value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].design_registration_id`	`string`	optional	Exact registration ID for details; preserve unchanged. Example: DSR:euipo_design:001694860-0001

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].design_registration_id`	`null`	optional	Design registration id value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].designer_names`	`array`	optional	Source designers; missing or null means unknown. Example: null

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].designer_names`	`null`	optional	Designer names value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].estimated_expiration_date`	`string`	optional	Estimated date only, YYYY-MM-DD; not confirmed expiry or invalidity. Example: null

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].estimated_expiration_date`	`null`	optional	Estimated expiration date value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].expiration_date_basis`	`object \| array \| string \| number \| boolean \| null`	optional	Source JSON of any shape, or null; never invent an estimation basis. Example: null

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].expiration_date_basis`	`null`	optional	Expiration date basis value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].holder_names`	`array`	optional	Source holders; do not resolve numeric identifiers to invented names. Example: ["237302"]

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].holder_names`	`null`	optional	Holder names value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].image_url`	`string`	optional	Complete signed first-image URL; when images exist this equals images[0]. Never strip query parameters. Example: https://example.com/design-1.png?signature=example%2Bsignature&expires=2000000000

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].image_url`	`null`	optional	Image url value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].images`	`array`	optional	At most six complete signed image URLs in original order; empty means no available images. Example: ["https://example.com/design-1.png?signature=example%2Bsignature&expires=2000000000","https://example.com/design-2.png?signature=second&expires=2000000000"] Maximum items: 6
`data.data.data.candidates[].images[]`	`string`	required	Item in data data data candidates[] images.

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].images`	`null`	optional	Images value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].jurisdiction_iso2`	`string`	optional	Registration jurisdiction, distinct from protected jurisdictions. Example: EM

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].jurisdiction_iso2`	`null`	optional	Jurisdiction iso2 value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].locarno_classes`	`array`	optional	Preserve output codes such as 06.01 or 09-01; requests still require NN-NN. Example: ["06.01"]

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].locarno_classes`	`null`	optional	Locarno classes value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].locarno_details`	`array`	optional	Source code, parent_code, label_zh and label_en; missing labels stay unknown. Example: [{"code":"06.01","label_en":null,"label_zh":null,"parent_code":"06"}]
`data.data.data.candidates[].locarno_details[]`	`object`	required	Item in data data data candidates[] locarno_details.
`data.data.data.candidates[].locarno_details[].code`	`string`	optional	Unmodified source classification code. Example: 06.01
`data.data.data.candidates[].locarno_details[].label_en`	`string`	optional	Source English label; missing/null stays unknown. Example: null
`data.data.data.candidates[].locarno_details[].label_zh`	`string`	optional	Source Chinese label; missing/null stays unknown. Example: null
`data.data.data.candidates[].locarno_details[].parent_code`	`string`	optional	Source parent classification. Example: 06

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].locarno_details`	`null`	optional	Locarno details value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].novelty_statement`	`string`	optional	Source novelty statement; retain original text, not a legal conclusion. Example: null

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].novelty_statement`	`null`	optional	Novelty statement value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].primary_identifier`	`string`	optional	Primary display number; retain leading zeros. Example: 001694860-0001

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].primary_identifier`	`null`	optional	Primary identifier value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].protected_jurisdictions`	`array`	optional	HAGUE designated states or ordinary registration jurisdiction; null means unknown, never fill from regions. Example: ["EM"]

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].protected_jurisdictions`	`null`	optional	Protected jurisdictions value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].publication_date`	`string`	optional	Source publication date, YYYY-MM-DD. Example: null

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].publication_date`	`null`	optional	Publication date value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].publication_number`	`string`	optional	Source publication number; missing or null means unknown. Example: null

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].publication_number`	`null`	optional	Publication number value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].registration_date`	`string`	optional	Source registration date, YYYY-MM-DD. Example: null

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].registration_date`	`null`	optional	Registration date value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].registration_jurisdiction_code`	`string`	optional	Source jurisdiction code such as EU, EMID or USID; do not rewrite as ISO-2. Example: EU

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].registration_jurisdiction_code`	`null`	optional	Registration jurisdiction code value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].registration_number`	`string`	optional	Source registration number. Example: E077151-PC

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].registration_number`	`null`	optional	Registration number value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].risk_level`	`string`	optional	Source risk hint, separate from score and legal status; not an infringement verdict. Example: medium

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].risk_level`	`null`	optional	Risk level value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].similarity`	`number`	optional	Final 0-100 score, not a probability. Preserve returned order; never multiply by 100 or sort again. Example: 99.88 Minimum: 0 Maximum: 100

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].similarity`	`null`	optional	Similarity value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].simple_legal_status`	`string`	optional	Source legal status; do not infer it from similarity. Example: inactive

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].simple_legal_status`	`null`	optional	Simple legal status value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].specification`	`object \| array \| string \| number \| boolean \| null`	optional	Source JSON of any shape, or null; preserve actual structure without filling gaps. Example: null

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].specification`	`null`	optional	Specification value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].title`	`string`	optional	Source title, which may be a number. Example: E077151-PC

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].title`	`null`	optional	Title value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].title_en`	`string`	optional	Source English title; do not translate missing values. Example: Chairs [seats]

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].title_en`	`null`	optional	Title en value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].title_language`	`string`	optional	Source title language; may be unknown. Example: unknown

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].title_language`	`null`	optional	Title language value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.candidates[].tro_cases`	`array`	optional	Current TRO corpus associations; empty is not confirmation of no TRO. Example: []

Any of option 2

Name	Type	Required	Description
`data.data.data.candidates[].tro_cases`	`null`	optional	Tro cases value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.coverage`	`object`	optional	Optional source coverage; do not infer completeness. Example: {}

Any of option 2

Name	Type	Required	Description
`data.data.data.coverage`	`null`	optional	Coverage value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.total`	`integer`	optional	Returned candidate count, not corpus size or user billing units. Example: 1

Any of option 2

Name	Type	Required	Description
`data.data.data.total`	`null`	optional	Total value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.data.warnings`	`array`	optional	Optional source limitations. Example: []

Any of option 2

Name	Type	Required	Description
`data.data.data.warnings`	`null`	optional	Warnings value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.message`	`string`	optional	Source status message. Example: success

Any of option 2

Name	Type	Required	Description
`data.data.message`	`null`	optional	Message value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.request_id`	`string`	optional	Upstream request identifier; keep separate from requestId. Example: req_example

Any of option 2

Name	Type	Required	Description
`data.data.request_id`	`null`	optional	Request id value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.data.usage`	`object`	optional	Source-account usage; not user debit or balance. Example: {}

Any of option 2

Name	Type	Required	Description
`data.data.usage`	`null`	optional	Usage value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.dataSnapshotMonth`	`string`	optional	Data snapshot month returned by the upstream provider. Example: null

Any of option 2

Name	Type	Required	Description
`data.dataSnapshotMonth`	`null`	optional	Data snapshot month value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.page`	`integer`	optional	Current page returned by the upstream provider. Example: null

Any of option 2

Name	Type	Required	Description
`data.page`	`null`	optional	Page value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.pageItemCount`	`integer`	optional	Item count on the current page returned by the upstream provider. Example: null

Any of option 2

Name	Type	Required	Description
`data.pageItemCount`	`null`	optional	Page item count value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.pageSize`	`integer`	optional	Page size returned by the upstream provider. Example: null

Any of option 2

Name	Type	Required	Description
`data.pageSize`	`null`	optional	Page size value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.requestId`	`string`	optional	Gateway/service error request identifier; distinct from upstream request_id. Example: gateway_example

Any of option 2

Name	Type	Required	Description
`data.requestId`	`null`	optional	Request id value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.sourceTool`	`string`	optional	Provider-specific source tool name. Example: null

Any of option 2

Name	Type	Required	Description
`data.sourceTool`	`null`	optional	Source tool value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.sourceType`	`string`	optional	Provider-specific source platform type. Example: null

Any of option 2

Name	Type	Required	Description
`data.sourceType`	`null`	optional	Source type value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.title`	`string`	optional	Provider-specific response title. Example: null

Any of option 2

Name	Type	Required	Description
`data.title`	`null`	optional	Title value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.totalPage`	`integer`	optional	Total page count returned by the upstream provider. Example: null

Any of option 2

Name	Type	Required	Description
`data.totalPage`	`null`	optional	Total page value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.type`	`string`	optional	Provider-specific render or payload type. Example: null

Any of option 2

Name	Type	Required	Description
`data.type`	`null`	optional	Type value used by this API operation.

Any of option 1

Name	Type	Required	Description
`data.upstreamRequestId`	`string`	optional	Extracted upstream request identifier. Example: req_example

Any of option 2

Name	Type	Required	Description
`data.upstreamRequestId`	`null`	optional	Upstream request id value used by this API operation.

Any of option 2

Name	Type	Required	Description
`data`	`null`	required	Data value used by this API operation.

Responses

Code	Description
200	Default HTTP response for both success and many business errors. Only outer JSON code 0 indicates success or asynchronous acceptance; inspect data for the result.
429	Execution admission rate limit; honor Retry-After when present.
503	Execution admission is temporarily unavailable; honor Retry-After when present.
Opt-in	X-Nexscope-Http-Status: semantic maps controller-handled business errors to HTTP status on run and task routes. Pre-authentication failures, such as a missing or invalid API key (code 11209, including an incomplete or corrupted copy) or an expired website login session (code 12001), may still return HTTP 200 before this mapping. Always check the outer JSON code; malformed requests and infrastructure failures may also return non-200 HTTP responses.

Data source, freshness, and limitations

Source, freshness, coverage, rate limits, and estimation notes are not specified in this API definition unless they appear in the request or response field documentation above. Do not assume official marketplace data or real-time freshness when it is not explicitly documented.

Step 1 of 2 · Connect your MCP client

MCP

V2 recommended

Connect remote agents through the standard MCP 2025-11-25 Streamable HTTP endpoint. Use OAuth 2.1 Authorization Code with PKCE, or an API key for compatibility.

POST https://api.nexscope.ai/mcp
MCP-Protocol-Version: 2025-11-25
Content-Type: application/json

Authentication

OAuth clients request the mcp:tools scope. The endpoint's 401 response advertises protected-resource metadata for authorization discovery.

Step 2 of 2 · Call the tool

Call a tool

{
  "jsonrpc": "2.0",
  "id": "tool-call-1",
  "method": "tools/call",
  "params": {
    "name": "nexscope_design_similarity_search",
    "arguments": {
      "imageUrl": "https://example.com/product.png",
      "title": "Bottle",
      "topK": 20
    }
  }
}

Legacy MCP v1

Existing API-key clients can continue using the compatibility endpoint. New integrations should use MCP v2.

GET / POST /mcp/legacy

What can you do with this API?

Data explained and practical use cases

AI Guide

Question

What results can Design Similarity Search provide, and how might I use them?

AI answer

Submit one image URL or Base64 image to find visually similar design-registration candidates. The result is a review list with similarity scores and available registration details, not a legal determination.

Data category	Documented fields	What the values mean
Candidate identity	`design_registration_id`, `primary_identifier`, `title_en`	Identifies a returned registration candidate and its available English title.
Similarity and review signal	`similarity`, `risk_level`	A reported similarity score and risk label to help prioritize review; neither establishes infringement.
Jurisdiction and classification	`jurisdiction_iso2`, `registration_jurisdiction_code`, `protected_jurisdictions`, `locarno_classes`	Reported jurisdictions and design classifications for the candidate.
Ownership and status	`holder_names`, `designer_names`, `simple_legal_status`	Available holder, designer, and simplified status information; values may be null.
Dates and images	`application_date`, `registration_date`, `image_url`, `images`	Available dates and image links. Use `image_url` or `images` only when links are actually returned.
Result size	`total`, `candidates`	The reported candidate count and candidate list.

Upload a product image and review the highest-scoring design candidates alongside their registration identifiers.
- Prompt example: “I am researching products for an online store. I can provide a product image URL or Base64 value. Could you review the highest-scoring design candidates alongside their registration identifiers? Show the relevant returned evidence and tell me what input you need from me.”
Limit a search to selected regions or Locarno classes to focus a design research queue.
- Prompt example: “I am researching products for an online store. Could you limit a search to selected regions or Locarno classes to focus a design research queue? Show matching records and source links where the API provides them; ask me for any required identifier or filter.”
Open returned candidate image links to compare specific visual features with the submitted image.
- Prompt example: “I am researching products for an online store. Could you open returned candidate image links to compare specific visual features with the submitted image? Show the returned values behind the comparison, and mark missing data.”
Use holder, status, and jurisdiction fields to decide which candidates need deeper registration review.
- Prompt example: “I am researching products for an online store. Could you use holder, status, and jurisdiction fields to decide which candidates need deeper registration review? Show the relevant returned evidence and tell me what input you need from me.”

A match, score, or risk label does not establish infringement or freedom to operate. Coverage and missing values should be considered when interpreting the results.

Related APIs

Design Registration Details

Retrieve design-registration holders, designers, legal status, dates and classifications by exact IDs or primary number through the Nexscope REST API or MCP.