Semantic search over the tenant's indexed objects

POST

/v1/retrieval/search

curl --request POST \
  --url https://api.aerandil.com/v1/retrieval/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "limit": 10, "object_types": [ "example" ], "query": "example" }'

• Production API

Embeds query and cosine-ranks it against the host-side retrieval index (AIP Increment 4, Option B: vanilla Postgres, no extension). Only unmarked String/Text/Enum properties are ever embedded, and every hit is re-hydrated through the caller’s authorized read path — marking redaction applies and unreadable objects are dropped, never ranked into view. Returns 501 when the retrieval tier is disabled (AERANDIL_RETRIEVAL_ENABLED unset).

Authorizations

• aerandil_oauth

Request Body^required

Media typeapplication/json

object

limit

Maximum hits returned (clamped to 1..100).

integer

default: 10 >= 1 <= 100

object_types

Optional filter to these object-type api-names; defaults to every indexed type.

Array<string>

query

required

Natural-language query text.

string

Responses

200

Cosine-ranked, ACL-hydrated hits, best first.

Media typeapplication/json

object

data

required

Array<object>

object

id

required

string format: uuid

object_type

required

string

properties

required

The object’s properties as the caller is cleared to see them (marking redaction applied).

object

score

required

Cosine similarity in [-1, 1], higher is closer.

number

Example^generated

{
  "data": [
    {
      "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "object_type": "example",
      "properties": {},
      "score": 1
    }
  ]
}

Headers

Cache-Control

string

Allowed value: no-store

Always no-store — live data.

403

Missing objects:read scope.

501

The retrieval tier is disabled on this deployment.