API Reference

Complete REST API for Lunexa search-as-a-service. Every endpoint can be tested live with your API key.

Authentication

All API requests must include your API key.

Pass your key via the X-LUNEXA-API-KEY header or as a Authorization: Bearer <key> header. API keys are scoped to a single project and carry action permissions (e.g. documents:search).

curl https://api.ailunexa.com/api/v1/orgs/{org}/projects/{project}/collections \
  -H "X-LUNEXA-API-KEY: lnx_your_key_here"

Base URL

All endpoints are relative to:

https://api.ailunexa.com/api/v1

Every resource endpoint uses the pattern: /orgs/{orgSlug}/projects/{projectSlug}/...

Error Handling

Errors return JSON with an error field:

{
  "error": "api key does not have the required scope: documents:create"
}

Status	Meaning
400	Bad request — invalid body or parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — key lacks required scope or project access
404	Resource not found
429	Rate limit exceeded

Collections

Collections are search indexes. Create a collection with a schema, then add documents to it.

POST

Create Collection

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collectionsScope: collections:create

Creates a new collection with the given schema. Fields define the structure of documents you'll index.

Field	Type	Description
`name`*	string	Collection name (must be unique within the project)
`fields`*	array	Array of field objects with `name`, `type`, and optional `facet`, `index`, `optional`
`default_sorting_field`	string	Field to sort by when no sort is specified

POST/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections

https://api.ailunexa.com/api/v1/orgs//projects//collections

GET

List Collections

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collectionsScope: collections:read

Returns all collections in the project.

GET/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections

https://api.ailunexa.com/api/v1/orgs//projects//collections

GET

Get Collection

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}Scope: collections:read

Returns a single collection's schema and metadata.

GET/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}

https://api.ailunexa.com/api/v1/orgs//projects//collections/

PATCH

Update Collection

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}Scope: collections:update

Update a collection's schema — add or modify fields.

PATCH/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}

https://api.ailunexa.com/api/v1/orgs//projects//collections/

DELETE

Delete Collection

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}Scope: collections:delete

Permanently deletes a collection and all its documents.

DELETE/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}

https://api.ailunexa.com/api/v1/orgs//projects//collections/

Documents

Documents are the records stored in a collection. Create, read, update, delete, import, and export.

POST

Create Document

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/documentsScope: documents:create

Index a single document. Fields must match the collection schema.

POST/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/documents

https://api.ailunexa.com/api/v1/orgs//projects//collections//documents

GET

Get Document

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/documents/{docId}Scope: documents:search

Retrieve a single document by its ID.

GET/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/documents/{docId}

https://api.ailunexa.com/api/v1/orgs//projects//collections//documents/

PUT

Upsert Document

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/documents/{docId}Scope: documents:update

Create or replace a document. If the document exists, it is fully replaced.

PUT/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/documents/{docId}

https://api.ailunexa.com/api/v1/orgs//projects//collections//documents/

PATCH

Update Document

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/documents/{docId}Scope: documents:update

Partially update a document. Only provided fields are changed.

PATCH/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/documents/{docId}

https://api.ailunexa.com/api/v1/orgs//projects//collections//documents/

DELETE

Delete Document

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/documents/{docId}Scope: documents:delete

Permanently delete a document by ID.

DELETE/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/documents/{docId}

https://api.ailunexa.com/api/v1/orgs//projects//collections//documents/

POST

Import Documents

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/documents/importScope: documents:import

Bulk import documents in JSONL format (one JSON object per line). Supports upsert, create, update, and delete actions.

POST/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/documents/import

https://api.ailunexa.com/api/v1/orgs//projects//collections//documents/import?action=upsert

GET

Export Documents

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/documents/exportScope: documents:export

Export all documents as JSONL (newline-delimited JSON).

GET/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/documents/export

https://api.ailunexa.com/api/v1/orgs//projects//collections//documents/export

Search

Full-text search with filtering, sorting, and pagination.

POST

Search Documents

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/searchScope: documents:search

Field	Type	Description
`q`*	string	Search query. Use `*` for all documents.
`query_by`*	string	Comma-separated list of fields to search in
`filter_by`	string	Filter expression, e.g. `price:>50 && category:Electronics`
`sort_by`	string	Sort expression, e.g. `price:desc`
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page (default: 20)

POST/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/search

https://api.ailunexa.com/api/v1/orgs//projects//collections//search

POST

Multi-Search

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/multi-searchScope: multi_search

Execute multiple search queries in a single request across different collections.

POST/api/v1/orgs/{orgSlug}/projects/{projectSlug}/multi-search

https://api.ailunexa.com/api/v1/orgs//projects//multi-search

GET

Generate Scoped Search Key

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/search-keyScope: documents:search

Generate a temporary, scoped search key safe for frontend use. Expires after 1 hour.

GET/api/v1/orgs/{orgSlug}/projects/{projectSlug}/search-key

https://api.ailunexa.com/api/v1/orgs//projects//search-key

Synonyms

Define synonyms so users find results regardless of the exact term they search for.

GET

List Synonyms

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/synonymsScope: synonyms:manage

GET/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/synonyms

https://api.ailunexa.com/api/v1/orgs//projects//collections//synonyms

PUT

Upsert Synonym

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/synonyms/{synonymId}Scope: synonyms:manage

Create or update a synonym rule. Use synonyms for multi-way synonyms or root + synonyms for one-way.

PUT/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/synonyms/{synonymId}

https://api.ailunexa.com/api/v1/orgs//projects//collections//synonyms/

GET

Get Synonym

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/synonyms/{synonymId}Scope: synonyms:manage

GET/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/synonyms/{synonymId}

https://api.ailunexa.com/api/v1/orgs//projects//collections//synonyms/

DELETE

Delete Synonym

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/synonyms/{synonymId}Scope: synonyms:manage

DELETE/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/synonyms/{synonymId}

https://api.ailunexa.com/api/v1/orgs//projects//collections//synonyms/

Curations (Overrides)

Pin or hide specific documents for certain search queries.

GET

List Overrides

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/overridesScope: curations:manage

GET/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/overrides

https://api.ailunexa.com/api/v1/orgs//projects//collections//overrides

PUT

Upsert Override

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/overrides/{overrideId}Scope: curations:manage

PUT/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/overrides/{overrideId}

https://api.ailunexa.com/api/v1/orgs//projects//collections//overrides/

GET

Get Override

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/overrides/{overrideId}Scope: curations:manage

GET/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/overrides/{overrideId}

https://api.ailunexa.com/api/v1/orgs//projects//collections//overrides/

DELETE

Delete Override

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/overrides/{overrideId}Scope: curations:manage

DELETE/api/v1/orgs/{orgSlug}/projects/{projectSlug}/collections/{collectionName}/overrides/{overrideId}

https://api.ailunexa.com/api/v1/orgs//projects//collections//overrides/

Aliases

Point an alias name to a collection for zero-downtime reindexing.

GET

List Aliases

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/aliasesScope: aliases:manage

GET/api/v1/orgs/{orgSlug}/projects/{projectSlug}/aliases

https://api.ailunexa.com/api/v1/orgs//projects//aliases

PUT

Upsert Alias

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/aliases/{aliasName}Scope: aliases:manage

PUT/api/v1/orgs/{orgSlug}/projects/{projectSlug}/aliases/{aliasName}

https://api.ailunexa.com/api/v1/orgs//projects//aliases/

GET

Get Alias

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/aliases/{aliasName}Scope: aliases:manage

GET/api/v1/orgs/{orgSlug}/projects/{projectSlug}/aliases/{aliasName}

https://api.ailunexa.com/api/v1/orgs//projects//aliases/

DELETE

Delete Alias

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/aliases/{aliasName}Scope: aliases:manage

DELETE/api/v1/orgs/{orgSlug}/projects/{projectSlug}/aliases/{aliasName}

https://api.ailunexa.com/api/v1/orgs//projects//aliases/

Stopwords

Manage stopword sets to exclude common words from search indexing.

GET

List Stopword Sets

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/stopwordsScope: stopwords:manage

GET/api/v1/orgs/{orgSlug}/projects/{projectSlug}/stopwords

https://api.ailunexa.com/api/v1/orgs//projects//stopwords

PUT

Upsert Stopword Set

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/stopwords/{setId}Scope: stopwords:manage

PUT/api/v1/orgs/{orgSlug}/projects/{projectSlug}/stopwords/{setId}

https://api.ailunexa.com/api/v1/orgs//projects//stopwords/

DELETE

Delete Stopword Set

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/stopwords/{setId}Scope: stopwords:manage

DELETE/api/v1/orgs/{orgSlug}/projects/{projectSlug}/stopwords/{setId}

https://api.ailunexa.com/api/v1/orgs//projects//stopwords/

Presets

Save and reuse search parameter presets.

GET

List Presets

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/presetsScope: presets:manage

GET/api/v1/orgs/{orgSlug}/projects/{projectSlug}/presets

https://api.ailunexa.com/api/v1/orgs//projects//presets

PUT

Upsert Preset

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/presets/{presetName}Scope: presets:manage

PUT/api/v1/orgs/{orgSlug}/projects/{projectSlug}/presets/{presetName}

https://api.ailunexa.com/api/v1/orgs//projects//presets/

DELETE

Delete Preset

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/presets/{presetName}Scope: presets:manage

DELETE/api/v1/orgs/{orgSlug}/projects/{projectSlug}/presets/{presetName}

https://api.ailunexa.com/api/v1/orgs//projects//presets/

Analytics Rules

Configure analytics rules to track popular queries, no-result queries, and click events.

GET

List Analytics Rules

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/analytics/rulesScope: analytics:manage

GET/api/v1/orgs/{orgSlug}/projects/{projectSlug}/analytics/rules

https://api.ailunexa.com/api/v1/orgs//projects//analytics/rules

PUT

Upsert Analytics Rule

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/analytics/rules/{ruleName}Scope: analytics:manage

PUT/api/v1/orgs/{orgSlug}/projects/{projectSlug}/analytics/rules/{ruleName}

https://api.ailunexa.com/api/v1/orgs//projects//analytics/rules/

DELETE

Delete Analytics Rule

/api/v1/orgs/{orgSlug}/projects/{projectSlug}/analytics/rules/{ruleName}Scope: analytics:manage

DELETE/api/v1/orgs/{orgSlug}/projects/{projectSlug}/analytics/rules/{ruleName}

https://api.ailunexa.com/api/v1/orgs//projects//analytics/rules/