Search API

Run a semantic knowledge search over your ingested content using the existing RAG pipeline.

POST/v1/search

Authentication

Requires a secret API key passed as a Bearer token (Authorization: Bearer carrier_sk_…).

Request body

Field	Type	Description
query*	string	The natural-language search query.
topK	number, 1–20	Max chunks to retrieve. Default 6.
minSimilarity	number, 0–1	Minimum similarity threshold. Default 0.3.

Example request

bash

curl -X POST https://api.carrieros.ai/v1/search \
  -H "Authorization: Bearer carrier_sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "How does OAuth refresh work?" }'

Response

Field	Type	Description
answer	string	Synthesized answer from retrieved context.
sources	string[]	Source URLs/identifiers the answer draws from.
confidence	number	0–1 heuristic based on retrieval coverage.

Example response

json

{
  "success": true,
  "data": {
    "answer": "Refresh tokens let a client obtain a new access token…",
    "sources": ["https://…"],
    "confidence": 0.83
  }
}

Possible errors

Code	HTTP	When it occurs
VALIDATION_ERROR	400	query is missing, or topK/minSimilarity is out of range.

Notes

If nothing relevant has been ingested yet, the response falls back to an answer with an empty sources array and confidence of 0 — this is expected, not an error.