> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signa.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Search by Image

> Find visually similar trademarks by logo/image similarity (beta — not yet generally available)

<Warning>
  **Beta — held until GA.** Image search is live only for internal and
  design-partner keys: it requires the dedicated `image-search:read` scope and
  is gated off on the free/starter/public plans. This page previews the endpoint
  so partners can design against it; shapes may still change before general
  availability. It is not yet part of the public API surface.
</Warning>

## Overview

Upload a logo or image and get back trademarks whose figurative marks look
similar — useful for clearance searches, logo lookalikes, and design-mark
screening. Works alongside text search ([Search Trademarks](/api-reference/trademarks/list-trademarks))
and autocomplete ([Suggest](/api-reference/trademarks/trademark-suggest)).

The endpoint accepts a multipart image upload, an `image_url` (https, SSRF-guarded),
or a `media_id` (reuse an existing mark's stored logo), and returns a ranked,
mark-level list. Each hit carries a named **signals** explanation block (visual,
logo\_text, exact\_dup, vienna\_overlap) and a thumbnail URL. Results are a bounded
top-K (`limit` ≤ 100, no deep pagination); the query image is never stored.

## Shape

```http theme={null}
POST /v1/trademarks/search/image
```

**Request (URL-based):**

```json theme={null}
{
  "image_url": "https://example.com/logo.png",
  "filters": {
    "offices": ["uspto", "euipo"],
    "nice_classes": [9, 42]
  },
  "channels": ["visual", "logo_text", "exact_dup"],
  "limit": 20
}
```

**Request (multipart upload):** `multipart/form-data` with an `image` file part
(≤ 8 MB, raster only — no SVG) and optional `filters` / `crop` / `channels` /
`limit` fields (the structured ones JSON-encoded).

**Request (existing logo):** `{ "media_id": "med_..." }` reuses that media's
stored vector — no re-embedding.

**Response:**

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "image_search_hit",
      "score": 0.94,
      "band": "strong",
      "signals": {
        "visual": { "score": 0.94, "band": "strong", "embedding_spec": "visual/…" },
        "logo_text": null,
        "exact_dup": { "checksum_match": false, "phash_distance": null },
        "vienna_overlap": null
      },
      "matched_image": {
        "image_id": "img_abc123",
        "checksum": "…",
        "office": "uspto",
        "jurisdiction": "US",
        "thumbnail_url": "/v1/trademarks/image-thumbnails/img_abc123"
      },
      "thumbnail_url": "/v1/trademarks/image-thumbnails/img_abc123",
      "trademark": {
        "id": "tm_abc123",
        "mark_text": "ACME",
        "mark_feature_type": "figurative",
        "office_code": "uspto",
        "status": { "primary": "active", "stage": "registered" }
      }
    }
  ],
  "has_more": false,
  "pagination": { "cursor": null },
  "search_meta": {
    "search_id": "imgsrch_…",
    "query_mode": "image_url",
    "channels": ["visual", "logo_text", "exact_dup"],
    "embedding_spec": "visual/…",
    "index_version": 1,
    "total_results": 1,
    "execution_time_ms": 42
  },
  "request_id": "req_xyz"
}
```

## Want Early Access?

If image search is on your roadmap, email [support@signa.so](mailto:support@signa.so) —
we'd like to hear what you need so the first version covers the right workflows.