REST API
Query EigenSearch programmatically. Every call is filtered by the end user's permissions.
EigenSearch exposes a small REST API. Each request runs as a specific user, and results only ever include documents that user can open. The app itself is built on the same API.
Permissions are always enforced
Every request takes an as_user. EigenSearch resolves that person's identity and groups
live, then filters results to documents they can open. There is no way to retrieve a
document a user could not open themselves.
Base URL
EigenSearch is self-hosted, so the base URL is your own deployment:
https://eigensearch.<your-company>.internalAuthentication
Send a bearer token on every request, and identify the end user with as_user.
Authorization: Bearer $EIGENSEARCH_TOKEN
Content-Type: application/json| Header | Required | Notes |
|---|---|---|
Authorization | Yes | Bearer token for your EigenSearch deployment. |
Content-Type | Yes | application/json. |
Search
/v1/searchHybrid (keyword + semantic) search. Returns ranked passages the user can open.
Body
Prop
Type
curl -X POST https://eigensearch.acme.internal/v1/search \
-H "Authorization: Bearer $EIGENSEARCH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"query": "SCA exemption thresholds for low-value payments",
"as_user": "anna@acme.com"
}'{
"hits": [
{ "title": "SCA Exemption Thresholds (PSD2)", "source": "confluence", "score": 0.91 },
{ "title": "Card Disputes SOP (Support)", "source": "sharepoint", "score": 0.78 }
],
"hidden_by_permissions": 2
}Response
Prop
Type
Answer
/v1/answerRuns a search, then returns a grounded answer with the context it used. Drop context
straight into your model call.
Body
Prop
Type
curl -X POST https://eigensearch.acme.internal/v1/answer \
-H "Authorization: Bearer $EIGENSEARCH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"query": "What is the SCA exemption limit for low-value payments?",
"as_user": "anna@acme.com"
}'{
"answer": "Low-value payments under €30 can skip SCA, up to €150 cumulative or 5 in a row.",
"context": [
{ "title": "SCA Exemption Thresholds (PSD2)", "source": "confluence" },
{ "title": "Card Disputes SOP (Support)", "source": "sharepoint" }
],
"hidden_by_permissions": 2
}Response
Prop
Type
Ingest
/v1/ingestPush a document for indexing manually, for content a connector doesn't cover. Set acl
so it's only returned to the right people, exactly like connector-sourced documents.
Body
Prop
Type
curl -X POST https://eigensearch.acme.internal/v1/ingest \
-H "Authorization: Bearer $EIGENSEARCH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "SCA Exemption Thresholds (PSD2)",
"content": "Low-value payments under €30 can skip SCA, up to €150 cumulative...",
"source": "policies",
"acl": ["support", "emea"]
}'{
"id": "doc_8f21c4",
"status": "indexed"
}Response
Prop
Type
Resolve identity
/v1/identity/resolveMap a user to the groups and access EigenSearch sees for them. Useful for debugging why a document is or isn't returned.
Body
Prop
Type
curl -X POST https://eigensearch.acme.internal/v1/identity/resolve \
-H "Authorization: Bearer $EIGENSEARCH_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "as_user": "anna@acme.com" }'{
"user": "anna@acme.com",
"groups": ["support", "emea"],
"sources": ["sharepoint", "confluence", "jira"]
}Response
Prop
Type
Errors
EigenSearch uses standard HTTP status codes. Error bodies include a message field.
| Status | Meaning |
|---|---|
400 | Malformed request body. |
401 | Missing or invalid bearer token. |
403 | as_user could not be resolved, or the token lacks scope. |
429 | Rate limited. Retry after the Retry-After header. |
Permissions are resolved live from your identity provider on every call. See document-level security for how access is enforced.