Search API (REST)

Search indexed collections over REST/JSON using a key with Read or Admin rights.

Endpoint Overview

Method	Path	Description	Required Permission
GET	/search/{pageSize}/{collectionId}	Execute a simple search query	Read, Admin
GET	/search/{pageSize}	Search all authorized collections	Read, Admin
GET	/search/hybrid/{pageSize}/{collectionId}	Execute hybrid text/vector search in one collection	Read, Admin
GET	/search/hybrid/{pageSize}	Currently returns 400; use the collection-specific hybrid route	Read, Admin

Usage

GET /search/{pageSize}/{collectionId}?q={query}
x-api-key: YOUR_API_KEY
api-version: 1.0

Path Parameters

• pageSize: Number of results to return. Current route validation accepts values from 10 to 100.
• collectionId: The ULID of the collection to search. Omit this segment to search all collections allowed by the API key.

Query Parameters

Parameter	Type	Required	Description
q	string	Yes	At least two characters; no /, ?, #, %, or control characters.
l	string	No	Language ISO code (e.g., ENG) for analyzer selection.
c	string	No	Pagination cursor for the next page of results.
sug	boolean	No	If true, returns a list of query suggestions.
hl	boolean	No	If true, enables hit highlighting in results.
hlf	string	No	The field to highlight (required if hl is true).

Highlighting & Suggestions

• Highlighting: Set hl=true and hlf to a configured text field. Treat returned fragments as untrusted content when rendering them.
• Suggestions: sug=true requests related terms in the optional suggests collection.
• Hybrid search: /search/hybrid/... combines full-text ranking with vector retrieval when embeddings are available.

Pagination

BlueCurve uses cursor-based pagination for stable result sets.

1. The first request returns a nextPageCursor.
2. For subsequent pages, pass this cursor as the c parameter.
3. A null or empty nextPageCursor means there are no additional pages. Keep the query, collection, and page size consistent when using a cursor.

Request example

Use your deployment address and a collection ULID from the Collections API. Let your HTTP client encode the query string.

curl --fail-with-body --get "$BLUECURVE_API_URL/search/20/$COLLECTION_ID" \
  -H "x-api-key: $BLUECURVE_API_KEY" \
  -H 'api-version: 1.0' \
  --data-urlencode 'q=annual report' \
  --data-urlencode 'l=ENG'

Response format

The response envelope contains total, resultsPerPage, nextPageCursor, suggests, time, and results. Result entries contain dynamic document fields determined by the collection and stored document; do not assume a fixed title/URL/preview schema.

A response with no matches can look like this:

{
  "total": 0,
  "resultsPerPage": 20,
  "nextPageCursor": null,
  "suggests": null,
  "time": "00:00:00.0450000",
  "results": []
}

Errors and rate limits

Status	Meaning
400	Invalid query, inconsistent highlighting parameters, or unsupported cross-collection hybrid request.
401 / 403	Missing authentication or insufficient access.
429	Rate limit reached; back off and honor Retry-After when supplied.
500	Search processing failed.
503	A required access-control dependency is unavailable.

Rate limits are deployment settings. Obtain the applicable limits from your administrator rather than assuming a fixed request budget. Some errors have an empty body; check the HTTP status before attempting JSON deserialization.

Next: Indexing Plugins