Skip to content
Blue Dots EconomyBlue Dots EconomyDocumentation
search

Search items by meaning, location, and/or structured filters

POST
/v1/search
curl --request POST \
  --url https://search.example.com/v1/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{ "context": { "version": "1.0.0", "messageId": "example", "timestamp": "example", "networkId": "example", "domain": "example", "itemType": "example" }, "message": { "intent": { "textSearch": "example", "item": { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }, "spatial": [ { "op": "s_dwithin", "geometry": { "type": "Point", "coordinates": [ "example" ] }, "distanceMeters": 1 } ], "filters": [ { "op": "eq", "target": "example", "value": "example" } ] }, "pagination": { "limit": 20, "offset": 0 } } }'

Beckn-aligned envelope. Provide any combination of textSearch, an anchor item.id, spatial, and filters. Ranking: cosine similarity (text/anchor) → distance (spatial) → recency.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
context
required
object
version
string
default: 1.0.0
messageId
required
string
>= 1 characters
timestamp
string
networkId
required
string
>= 1 characters
domain
required
string
>= 1 characters
itemType
required
string
>= 1 characters
message
required
object
intent
required
object
textSearch
string
>= 1 characters
item
object
id
required
string format: uuid
spatial
Array<object>
<= 1 items
object
op
required
string
Allowed values: s_dwithin
geometry
object
type
required
string
Allowed values: Point
coordinates
required
Array
>= 2 items <= 2 items
distanceMeters
number
filters
Array<object>
object
op
required
string
Allowed values: eq neq in contains contains_any gt gte lt lte
target
required
string
/^item_state\.[A-Za-z0-9_]+$/
value
pagination
object
limit
integer
default: 20 >= 1 <= 100
offset
integer
0

Responses

Section titled “Responses”

200

Section titled “200”

Default Response

Media typeapplication/json
object
context
required
object
version
string
default: 1.0.0
messageId
required
string
>= 1 characters
timestamp
string
networkId
required
string
>= 1 characters
domain
required
string
>= 1 characters
itemType
required
string
>= 1 characters
message
required
object
items
required
Array<object>
object
item_network
required
string
item_domain
required
string
item_type
required
string
item_id
required
string
item_state
required
object
key
additional properties
item_locations
required
Array<object>
object
lat
required
number
lng
required
number
label
string
score
number
distanceMeters
number
meta
required
object
total
required
number
limit
required
number
offset
required
number
Example
{
  "context": {
    "version": "1.0.0"
  }
}

400

Section titled “400”

Default Response

Media typeapplication/json
object
error
required
string
message
required
string
Examplegenerated
{
  "error": "example",
  "message": "example"
}

401

Section titled “401”

Default Response

Media typeapplication/json
object
error
required
string
message
required
string
Examplegenerated
{
  "error": "example",
  "message": "example"
}

403

Section titled “403”

Default Response

Media typeapplication/json
object
error
required
string
message
required
string
Examplegenerated
{
  "error": "example",
  "message": "example"
}

404

Section titled “404”

Default Response

Media typeapplication/json
object
error
required
string
message
required
string
Examplegenerated
{
  "error": "example",
  "message": "example"
}

422

Section titled “422”

Default Response

Media typeapplication/json
object
error
required
string
message
required
string
Examplegenerated
{
  "error": "example",
  "message": "example"
}