Search documents (POST)

Query your indexed documents.

POST/api/v1/search

Search with natural language.

Request body

Parameter	Type	Description
`query`required	`string`	Natural language query.
`collections`required	`string[]`	Collections to search.
`limit`	`number`	Max results (default: 10, max: 100).
`offset`	`number`	Pagination offset (default: 0).

Example

import { Etoile } from "@etoile-dev/client";

const etoile = new Etoile({
apiKey: process.env.ETOILE_PUBLIC_KEY,
});

const { results } = await etoile.search({
query: "swirling sky painting",
collections: ["paintings"],
limit: 5,
});

const response = await fetch("https://etoile.dev/api/v1/search", {
method: "POST",
headers: {
  Authorization: `Bearer ${process.env.ETOILE_PUBLIC_KEY}`,
  "Content-Type": "application/json",
},
body: JSON.stringify({
  query: "swirling sky painting",
  collections: ["paintings"],
  limit: 5,
}),
});

const { results } = await response.json();

curl -X POST "https://etoile.dev/api/v1/search" \
-H "Authorization: Bearer $ETOILE_PUBLIC_KEY" \
-H "Content-Type: application/json" \
-d '{
  "query": "swirling sky painting",
  "collections": ["paintings"],
  "limit": 5
}'

Response

{
"query": "swirling sky painting",
"results": [
  {
    "external_id": "starry-night",
    "title": "The Starry Night",
    "collection": "paintings",
    "metadata": {
      "artist": "Vincent van Gogh",
      "year": 1889
    },
    "score": 0.94
  }
]
}

Scores

Scores range 0–1 (higher is better). Weak matches are filtered automatically.

Auth

Works with public key or secret key.