Search

This page covers the public search workflow:

GET /api/Search
PUT /api/Search
GET /api/Image
PUT /api/SearchFeedback

The most important legacy rule: `filterStr`

filterStr is not a normal field. It is its own mini query string, sent as the value of a query parameter. That means:

Build the inner filter string first, for example fileUID=<guid> or FT=pump housing.
URL-encode the entire inner string before appending it as filterStr=....
If the FT= value itself contains = or &, encode the FT value first, then encode the whole filterStr.

Example: plain text search

Decoded inner filter string: FT=pump housing
Encoded filterStr: FT%3Dpump%20housing

Example: attribute text search

If the logical search text is document_type=Assembly&material=Stainless Steel:

Encode the FT value: document_type%3DAssembly%26material%3DStainless%20Steel
Build the decoded filterStr: FT=document_type%3DAssembly%26material%3DStainless%20Steel
Encode the whole filterStr: FT%3Ddocument_type%253DAssembly%2526material%253DStainless%2520Steel

Example: repeated `FT=` filters for metadata-style narrowing

Decoded inner filter string: FT=document_type=[Assembly]&FT=material=[Stainless Steel]&FT=region=[North America]
Encoded filterStr: FT%3Ddocument_type%3D%5BAssembly%5D%26FT%3Dmaterial%3D%5BStainless%20Steel%5D%26FT%3Dregion%3D%5BNorth%20America%5D

Attribute-match conventions

The current search parser treats the following forms differently:

Regular metadata search: FT=document_number=AX-1000
Exact attribute match: FT=document_number=[AX-1000]
Wildcard attribute search: FT=document_number=AX-*

`GET /api/Search`

Use this when the search input already exists in VizSeek, or when you want a pure text/attribute search.

Item	Value
Method	`GET`
Path	`/api/Search`
Auth	User bearer token
Response	`SearchResultSummary` JSON

Query parameters

Parameter	Required	Format	Notes
`filterStr`	Yes	URL-encoded nested query string	See the encoding rules above.
`includeShapelets`	No	`true` or `false`	Adds shapelet detail for applicable results.
`customAPI`	No	Integer	Deprecated legacy switch. Do not use for new integrations.
`searchAssemblyComponents`	No	`true` or `false`	For assembly input, return component-level matches instead of only whole-assembly matches.
`accountName`	No	String	Only use if VizSeek explicitly tells you to use it.

Public `filterStr` keys

Key inside `filterStr`	Meaning
`fileUID`	Search by an existing uploaded file UID.
`FT`	Free-text or attribute-text search term. Repeat `FT=` when you want multiple text or metadata refinements.
`resultFileType`	Restrict results to `Image`, `ThreeD`, `TwoD`, or `Text`.
`v`	Volume tolerance for 3D-to-3D matching.
`bbv`	Bounding-box volume tolerance for 3D-to-3D matching.
`sa`	Surface-area tolerance for 3D-to-3D matching.

Additional public refinement keys may appear in SearchFilters[].QueryString in the response. When you want to refine a search, prefer reusing the QueryString values the API returns instead of inventing your own filter names.

Tolerance format

For v, bbv, and sa, the current public format is a decimal percentage string:

.1 means +/-10%
+.2 means +20%
-.5 means -50%
+0.3/-0.4 means +30% and -40%

Python example: search by existing file UID

import urllib.parse
import requests

server = "https://your-server.example.com"
token = "USER_BEARER_TOKEN"
file_uid = "11c20df1-8d84-418d-93ae-db3abb5d4d14"

filter_str = urllib.parse.quote(f"fileUID={file_uid}", safe="")

resp = requests.get(
    f"{server}/api/Search?filterStr={filter_str}",
    headers={"Authorization": f"Bearer {token}"},
)
resp.raise_for_status()
print(resp.json())

Python example: search by attribute text

import urllib.parse
import requests

server = "https://your-server.example.com"
token = "USER_BEARER_TOKEN"

inner_ft = urllib.parse.quote("document_number=[AX-1000]", safe="")
filter_str = urllib.parse.quote(f"FT={inner_ft}", safe="")

resp = requests.get(
    f"{server}/api/Search?filterStr={filter_str}",
    headers={"Authorization": f"Bearer {token}"},
)
resp.raise_for_status()
print(resp.json())

Raw HTTP example: simple text search

GET /api/Search?filterStr=FT%3Dpump%20housing HTTP/1.1
Host: your-server.example.com
Authorization: Bearer USER_BEARER_TOKEN

`PUT /api/Search`

Use this when you want to upload one or more temporary search-input files and search immediately.

Item	Value
Method	`PUT`
Path	`/api/Search`
Auth	User bearer token
Content-Type	`application/json`
Response	`SearchResultSummary` JSON

Query parameters

Parameter	Required	Format	Notes
`fileExtension`	Yes	URL-encoded extension such as `.png` or `.stp`	Include the leading dot.
`filterStr`	No	URL-encoded nested query string	Same rules as `GET /api/Search`.
`isGZipCompressed`	No	`true` or `false`	Legacy. Only use if the uploaded bytes are actually gzipped.
`cropX`, `cropY`, `cropW`, `cropH`	No	Integer	Deprecated crop parameters.
`includeShapelets`	No	`true` or `false`	Include shapelet detail in response.
`customAPI`	No	Integer	Deprecated.
`crawl_parameter`	No	String	Deprecated.
`accountName`	No	String	Only use if VizSeek directs you to.
`targetFids`	No	Comma-delimited file UID list	Restrict search targets to those files.

Request body format

The request body is a JSON string whose contents are a JSON array of base64-encoded file byte arrays.

That means the wire body looks like this:

"[\"BASE64_FILE_1\",\"BASE64_FILE_2\"]"

Do not send a raw JSON array like ["BASE64_FILE_1"]. The controller receives a string and then deserializes that string into byte[][].

Other important limits and quirks:

Maximum 10 input files per request.
The endpoint rejects obviously invalid or very short payloads before deserialization.
fileExtension applies to the uploaded files in this request.

Python example: visual search from one file

import base64
import json
import requests
import urllib.parse

server = "https://your-server.example.com"
token = "USER_BEARER_TOKEN"
filename = "example-input.dxf"

with open(filename, "rb") as f:
    b64_file = base64.b64encode(f.read()).decode("ascii")

body = json.dumps(json.dumps([b64_file]))
filter_str = urllib.parse.quote(
    "FT=pump housing&FT=document_type=[Assembly]",
    safe="",
)

resp = requests.put(
    f"{server}/api/Search?fileExtension=.dxf&filterStr={filter_str}",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    data=body,
)
resp.raise_for_status()
print(resp.json())

Python example: metadata narrowing with repeated `FT=` clauses

metadata_filter = (
    "FT=document_type=[Assembly]"
    "&FT=material=[Stainless Steel]"
    "&FT=region=[North America]"
)
encoded_filter = urllib.parse.quote(metadata_filter, safe="")

Raw HTTP example

PUT /api/Search?fileExtension=.stp&filterStr=FT%3Dpump%20housing HTTP/1.1
Host: your-server.example.com
Authorization: Bearer USER_BEARER_TOKEN
Content-Type: application/json

"[\"BASE64_FILE_1\"]"

Search response format

Typical top-level fields:

Field	Meaning
`InputFileUID`	UID of the temporary input file when a file-based search was used
`InputThumbnail`	Thumbnail URL for the input file
`TotalResults`	Number of returned results
`ResultsList`	Result objects
`SearchFilters`	Refinement filters you can feed back into a future `filterStr`
`SearchTime`	Search duration
`Message`	Extra message, often used for assembly-component cases

Typical result fields:

Field	Meaning
`FileUID`	Result file UID
`FileName`	Result file name
`CompanyName`	Owning company
`ThumbnailURL`	Thumbnail or shape image URL
`ShapeResult.Score`	Lower is better; `0.0` means exact match
`ShapeResult.ViewerUrl`	Viewer URL when available
`ShapeResult.LargeFileUrl`	Large image URL
`ShapeResult.Attributes`	Result attributes shown with the match

Example response:

{
  "InputFileUID": "example-uid",
  "TotalResults": 2,
  "ResultsList": [
    {
      "ShapeResult": {
        "Score": 3.22989,
        "Volume": 0.0,
        "SurfaceArea": 0.0,
        "ViewerUrl": "https://hoops.vizseek.com/view/viewer.html?...",
        "DetailsUrl": "https://www.vizseek.com/ViewFile?...",
        "LargeFileUrl": "https://viewfiles.vizseek.com/vizseek/.../lg.png?ver=3",
        "Attributes": [
          "document_type=Assembly",
          "region=North America"
        ],
        "FileHasThumbnail": true,
        "FirstShapeMatchIndex": "1",
        "FirstShapeMatchPageNum": "0",
        "MatchPosition": "0,0,0.785398,0.472566",
        "Name": "example-assembly.step"
      },
      "CompanyName": "Example Manufacturing",
      "FileName": "example-assembly.step",
      "FileUID": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

`GET /api/Image`

Use this to fetch the binary image or original file referenced by search results.

Item	Value
Method	`GET`
Path	`/api/Image`
Auth	No bearer token. Requires the query-string `token` returned by search URLs.
Response	Raw binary bytes with the file/image content type

Query parameters

Parameter	Required	Notes
`fid`	Yes	File UID to read from
`token`	Yes	Short-lived image token returned by search URLs
`type`	No	`0` = small thumbnail, `1` = large thumbnail, `2` = extracted shape, `3` = original/public file
`shapeIndex`	No	Shape or page index for `type=1` or `type=2`

Python example

resp = requests.get(
    f"{server}/api/Image?fid={file_uid}&type=1&token={image_token}"
)
resp.raise_for_status()
with open("result.png", "wb") as f:
    f.write(resp.content)

`PUT /api/SearchFeedback`

Use this to send explicit feedback about search quality.

Item	Value
Method	`PUT`
Path	`/api/SearchFeedback`
Auth	User bearer token
Content-Type	`application/json`
Response	Plain feedback ID string

Query parameters

Parameter	Required	Notes
`found`	No	`true` or `false`
`rank`	No	Rank of the expected result if found
`expectation`	No	URL-encoded text, max 100 chars
`helpfulness`	No	Integer `1` to `5`
`user`	No	URL-encoded external user identifier, max 100 chars
`inputFileUID`	No	Search input file UID from the search response
`inputFileName`	No	URL-encoded file name
`otherInput`	No	URL-encoded extra search context
`feedbackId`	No	Optional GUID you want to control

Request body format

The body is a JSON string containing a comma-separated result list in this format:

result_file_uid_1_score,result_file_uid_2_score

Example:

"17bc1ed1-1939-425f-bdfe-e59cbffaea16_1.05,10a5ba67-abfe-4b15-a085-e9f9a9952104_1.89"

Python example

import json
import requests

server = "https://your-server.example.com"
token = "USER_BEARER_TOKEN"

results_body = json.dumps(
    "17bc1ed1-1939-425f-bdfe-e59cbffaea16_1.05,"
    "10a5ba67-abfe-4b15-a085-e9f9a9952104_1.89"
)

resp = requests.put(
    f"{server}/api/SearchFeedback?found=true&rank=1&helpfulness=5",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    data=results_body,
)
resp.raise_for_status()
print(resp.text)

Search

The most important legacy rule: filterStr

Example: plain text search

Example: attribute text search

Example: repeated FT= filters for metadata-style narrowing

Attribute-match conventions

GET /api/Search

Query parameters

Public filterStr keys

Tolerance format

Python example: search by existing file UID

Python example: search by attribute text

Raw HTTP example: simple text search

PUT /api/Search

Query parameters

Request body format

Python example: visual search from one file

Python example: metadata narrowing with repeated FT= clauses

Raw HTTP example

Search response format

GET /api/Image

Query parameters

Python example

PUT /api/SearchFeedback

Query parameters

Request body format

Python example

The most important legacy rule: `filterStr`

Example: repeated `FT=` filters for metadata-style narrowing

`GET /api/Search`

Public `filterStr` keys

`PUT /api/Search`

Python example: metadata narrowing with repeated `FT=` clauses

`GET /api/Image`

`PUT /api/SearchFeedback`