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": [ 1 ] }, "distanceMeters": 1 } ], "filters": [ { "op": "eq", "target": "example", "value": "example" } ], "sort": "relevance", "orderingCenter": { "type": "Point", "coordinates": [ 1 ] } }, "pagination": { "limit": 20, "offset": 0 } } }'

Beckn-aligned envelope. Provide any combination of textSearch, an anchor item.id, spatial, orderingCenter, sort, and filters. Ordering: pass intent.sort (relevance | newest | nearest); when omitted, ordering is inferred as cosine → distance → recency for backward compatibility. intent.spatial FILTERS (s_dwithin); intent.orderingCenter only ORDERS and never filters. meta.sort_applied always reports the order actually used — an order whose precondition is unmet degrades to newest rather than erroring. textSearch narrows results even when an anchor supplies the ranking vector.

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
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$/
spatial
Array
<= 1 items
One of:
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
required
sort
string
Allowed values: relevance newest nearest
orderingCenter
object
type
required
string
Allowed values: Point
coordinates
required
Array
>= 2 items <= 2 items
pagination
object
limit
integer
default: 20 >= 1 <= 100
offset
integer
0 <= 9007199254740991

Responses

Section titled “Responses”

200

Section titled “200”

Default Response

Media typeapplication/json
object
context
required
object
version
required
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
item_instance_url
required
string
nullable
item_schema_url
required
string
nullable
created_at
required
string
updated_at
required
string
created_by
required
string
nullable
lifecycle_status
required
string
score
number
distanceMeters
number
meta
required
object
total
required
number
limit
required
number
offset
required
number
sort_applied
required
string
Allowed values: relevance newest nearest
Example
{
  "context": {
    "version": "1.0.0"
  },
  "message": {
    "meta": {
      "sort_applied": "relevance"
    }
  }
}

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"
}