--- title: "REST API" description: "HTTP endpoint reference for Xio.Lucent.Api: ingestion, querying, document management, backup, and admin operations." published: 2026-05-14T12:11:16.55869+00:00 updated: 2026-05-14T12:11:16.55869+00:00 tags: ["api", "lucent", "reference", "rest"] url: https://xiobjects.com/docs/xio/lucent/api/rest source: XI Objects --- # REST API `Xio.Lucent.Api` mounts Lucent's HTTP surface into any ASP.NET Core host. `Xio.Lucent.Api.Host` is a ready-to-run Kestrel server if you don't need a custom host. ## Setup ```csharp // Register engine + API controllers builder.Services.AddLucent(builder.Configuration.GetSection("Lucent")); builder.Services.AddLucentApi(); // Auth: choose JWT bearer or API key (or both) builder.Services.AddLucentJwtBearer(builder.Configuration); // or: builder.Services.AddLucentApiKey(builder.Configuration); builder.Services.AddLucentAuthorizationPolicies(builder.Configuration); // Mount app.UseMiddleware(); app.MapControllers(); ``` ## Endpoints ### Documents | Method | Route | Scope | Description | |--------|-------|-------|-------------| | `POST` | `/v1/collections/{collectionId}/documents` | `lucent:write` | Ingest a document | | `GET` | `/v1/collections/{collectionId}/documents` | `lucent:read` | List documents | | `DELETE` | `/v1/collections/{collectionId}/documents/{documentId}` | `lucent:write` | Delete a document | | `GET` | `/v1/collections/{collectionId}/documents/{documentId}/signed-source` | `lucent:read` | Stream preserved XION bytes | ### Search | Method | Route | Scope | Description | |--------|-------|-------|-------------| | `POST` | `/v1/collections/{collectionId}/query` | `lucent:read` | Hybrid vector + BM25 search | ### Backup | Method | Route | Scope | Description | |--------|-------|-------|-------------| | `GET` | `/v1/collections/{collectionId}/export` | `lucent:admin` | Stream collection backup | | `POST` | `/v1/collections/{collectionId}/import` | `lucent:admin` | Restore from backup stream | ### Admin | Method | Route | Scope | Description | |--------|-------|-------|-------------| | `POST` | `/v1/admin/provision` | `lucent:admin` | Download and verify ONNX model + sqlite-vec | | `POST` | `/v1/admin/warmup` | `lucent:admin` | Warm up the embedder | --- ## POST /v1/collections/{collectionId}/documents Ingests a document. Accepts `multipart/form-data`. **Form fields:** | Field | Type | Required | Description | |-------|------|----------|-------------| | `file` | File | Yes | Document content (binary or text) | | `documentId` | string | No | Explicit document ID; generated from content hash if omitted | | `contentTypeHint` | string | No | Overrides content type detection (e.g. `application/pdf`) | | `metadataJson` | string | No | JSON object of key-value metadata attached to every chunk | | `isXionContent` | bool | No | Set to `true` to trigger XION verification before ingestion | **Response: 200 OK** ```json { "documentId": "abc123", "chunkCount": 42, "contentType": "application/pdf", "contentTypeSource": "Detected", "modelId": "nomic-embed-text-v1.5", "chunkingDurationMs": 210, "embeddingDurationMs": 890, "storageDurationMs": 45, "routingDurationMs": 3 } ``` **Error responses:** | Status | Meaning | |--------|---------| | 400 | Malformed request (missing file, invalid metadata JSON) | | 422 | XION verification failed | | 500 | Pipeline error | --- ## POST /v1/collections/{collectionId}/query Runs a hybrid search. **Request body:** ```json { "text": "what is the cancellation policy", "topK": 10, "scoreThreshold": 0.35, "filter": { "type": "And", "operands": [ { "type": "Eq", "key": "category", "value": "legal" }, { "type": "Eq", "key": "status", "value": "approved" } ] } } ``` All fields except `text` are optional. **Response: 200 OK** ```json { "chunks": [ { "score": 0.812, "vectorScore": 0.76, "textScore": 0.61, "source": "hybrid", "chunk": { "id": "abc123:0000000000", "documentId": "abc123", "content": "Cancellations must be submitted…", "startOffset": 0, "endOffset": 312, "metadata": { "heading": "Cancellation Policy", "sectionPath": "Terms > Cancellation Policy", "pageNumber": 4, "chunkIndex": 0, "totalChunks": 42, "custom": { "category": "legal" } } } } ], "embeddingDurationMs": 14, "retrievalDurationMs": 8, "scoringDurationMs": 0, "lucentInstanceId": null } ``` --- ## GET /v1/collections/{collectionId}/documents/{documentId}/signed-source Streams the preserved XION bytes for a document ingested with `isXionContent = true`. Returns `application/octet-stream`. Returns `404` for documents that weren't ingested as XION content. --- ## Authentication Two schemes are supported and can be used simultaneously. ### JWT Bearer ```jsonc { "Lucent": { "Auth": { "Jwt": { "Authority": "https://login.example.com/", "Audience": "lucent-api", "ValidIssuer": "https://login.example.com/" } } } } ``` Scopes are checked as JWT claims. The scope claim name is configurable; defaults to `scope`. ### API Key ```jsonc { "Lucent": { "Auth": { "ApiKey": { "HeaderName": "X-Api-Key", "Keys": { "sk_live_abc123": ["lucent:read", "lucent:write"], "sk_admin_xyz789": ["lucent:read", "lucent:write", "lucent:admin"] } } } } } ``` Comparison is constant-time to prevent timing attacks. --- ## Full Configuration Reference ```jsonc { "Lucent": { "StorageRoot": "/var/data/lucent", "Auth": { "Jwt": { "Authority": "…", "Audience": "…" }, "ApiKey": { "HeaderName": "X-Api-Key", "Keys": { "key": ["scope"] } } }, "Cors": { "AllowedOrigins": ["https://app.example.com"], "AllowCredentials": true }, "RateLimit": { "Global": { "PermitLimit": 100, "WindowSeconds": 60 }, "PerUser": { "PermitLimit": 20, "WindowSeconds": 60 } }, "OpenTelemetry": { "OtlpEndpoint": "http://localhost:4317" } } } ``` --- ## Typed .NET Client `Xio.Lucent.Api.Client` provides a typed client for the HTTP surface: ```csharp services.AddLucentApiClient(new Uri("https://lucent.internal.example.com")); // Inject and use public class DocumentIngester(ILucentApiClient lucent) { public Task Ingest(Stream file, string fileName) => lucent.AddDocumentAsync("my-collection", file, fileName); public Task Ask(string question) => lucent.QueryAsync("my-collection", question, topK: 5); } ``` The client uses `IHttpClientFactory`. Bearer token or API key injection is handled via delegating handlers; wire them in when calling `AddLucentApiClient`.