smartbotic-vectorapi/api/llms.txt

# smartbotic-vectorapi

> General-purpose REST API over smartbotic-database. **Multi-project**: every
> collection and document lives under a named project supplied as a URL path
> segment (e.g. `/api/v1/projects/{project}/collections`). **Multi-key**: each
> API key carries a list of project grants (MySQL-style; `["*"]` for all); admin
> keys additionally manage projects and keys. Auth: `Authorization: Bearer <KEY>`.
> Machine-readable spec: `/openapi.json` (OpenAPI 3.1).

## Projects

Requires a valid key. Admin-only operations are noted.

- `GET  /api/v1/projects` — List projects the key may access (admin sees all).
- `POST /api/v1/projects` `{name}` — Create a project (admin).
- `GET  /api/v1/projects/{project}` — Get project info (collection/document counts).
- `DELETE /api/v1/projects/{project}` — Drop a project (admin; the `default` project cannot be dropped).

## Keys (admin)

All key-management endpoints require an admin key.

- `GET  /api/v1/keys` — List keys. Secret value is masked; returns `id`, `key_prefix`, `label`, `projects`, `admin`, `created_at`, and `scope` (if present). Use `id` to reference the key in PATCH/DELETE.
- `POST /api/v1/keys` `{label, projects:[], admin?, scope?}` — Generate a new key. Returns the secret key value **once** (store it immediately) plus the stable `id`. Pass a `scope` object (see below) to create a capability-scoped key.
- `PATCH /api/v1/keys/{id}` `{label?, projects?, admin?, scope?}` — Update grants for an existing key, identified by its `id` (not the secret). Pass `scope: null` to clear an existing scope.
- `DELETE /api/v1/keys/{id}` — Revoke a key by `id`. Active sessions using it are immediately invalidated.

### Capability-scoped keys

A non-admin key may carry a `scope` object that restricts what it can do. Scoped keys are designed to be safely embedded in untrusted clients (browser frontends, mobile apps, n8n workflows). A scoped key cannot manage collections or projects regardless of its project grants.

`scope` fields:

- `rules` (required, non-empty array) — Each rule specifies a `collection` name and the permitted `ops` array (`read`, `list`, `search`, `insert`, `update`, `delete`). A request succeeds only if a matching `{collection, op}` rule exists. A rule may also set `require_human_token: true` (see CAPTCHA below).
- `origins` (array of strings, default empty) — Allowed `Origin` header values. When non-empty, requests without a matching `Origin` header are rejected with 403 (**fails closed** — no origin header means denied). Use this to pin a key to a specific domain.
- `rate_limit_per_min` (integer, default 0 = unlimited) — Per-key request rate limit. When the limit is exceeded the server returns **429** with a `Retry-After: 60` header.
- `expires_at` (integer, default 0 = never) — Unix epoch seconds after which the key is treated as expired; auth returns 401.

### CAPTCHA-gated operations

A scope rule may set `require_human_token: true`. When this flag is active, the client must supply an `X-Captcha-Token` request header containing the CAPTCHA challenge response. The server verifies the token via the configured provider endpoint and returns **403** `captcha_required` if the token is absent, invalid, or if no provider is configured. Configure the provider via the settings API: `captcha_provider` (`"turnstile"` or `"hcaptcha"`), `captcha_secret` (server-side secret), and `captcha_verify_url` (full verify endpoint URL).

Example scope (insert-only, origin-pinned, rate-limited, expiring):
```json
{
  "rules": [{"collection": "designs", "ops": ["insert"]}],
  "origins": ["https://app.example.com"],
  "rate_limit_per_min": 60,
  "expires_at": 1893456000
}
```

## Collections

Project-scoped. A key must be granted the project.

- `POST   /api/v1/projects/{project}/collections` `{name, kind:"json"|"vector", vector_dimension?, embedding_model?}` — Create a collection. `vector_dimension` is required for `kind=vector`. `embedding_model` defaults to the server's `default_embedding_model` setting.
- `GET    /api/v1/projects/{project}/collections` — List collections with metadata (incl. `document_count`, `size_bytes`). Query params (all applied server-side): `q` (case-insensitive name substring filter), `sort` (`name`|`kind`|`documents`|`size`|`created_at`, default `name`), `desc` (bool).
- `GET    /api/v1/projects/{project}/collections/{name}` — Get collection metadata.
- `DELETE /api/v1/projects/{project}/collections/{name}` — Drop a collection and all its documents.

Collection names may not start with `_` or the reserved prefix `vectorapi_`.

## JSON documents

Arbitrary JSON CRUD under a `kind=json` collection.

- `POST  /api/v1/projects/{project}/collections/{name}/documents` `{data:{…}}` — Insert a document. Returns `{id}`.
- `GET   /api/v1/projects/{project}/collections/{name}/documents/{id}` — Fetch a document by ID.
- `PUT   /api/v1/projects/{project}/collections/{name}/documents/{id}` — Replace a document (full upsert).
- `PATCH /api/v1/projects/{project}/collections/{name}/documents/{id}` — Partially update a document (merge fields).
- `DELETE /api/v1/projects/{project}/collections/{name}/documents/{id}` — Delete a document.
- `GET   /api/v1/projects/{project}/collections/{name}/documents` — Find documents.

**Filter grammar**: `?filter=field:op:value` (repeatable; ANDed). Supported ops: `eq`, `ne`, `lt`, `lte`, `gt`, `gte`, `contains`. Example: `?filter=age:gte:30&filter=name:eq:Alice`.

Additional query params: `limit` (default 20), `offset` (default 0), `sort` (field name), `desc` (bool).

## RAG vectors

Requires a `kind=vector` collection. Vectors are stored with cosine-similarity indexing.

- `POST /api/v1/projects/{project}/collections/{name}/vectors` `{id?, text?, vector?, metadata?}` — Store a vector. Supply either `text` (the server embeds it using the collection's `embedding_model`) or a pre-computed `vector` array. `vector` dimension must match the collection's `vector_dimension`. `metadata` is an arbitrary JSON object stored alongside the vector.
- `POST /api/v1/projects/{project}/collections/{name}/search` `{query_text?, query_vector?, top_k, min_score?, filters?}` — Cosine-similarity search. Supply either `query_text` or `query_vector`. `top_k` (required) limits results. `min_score` (0–1) filters low-confidence matches. `filters` apply the same `field:op:value` grammar to vector metadata.

  **Latency tip:** `query_text` triggers a synchronous server-side embedding call to the configured provider, which usually dominates request time (seconds for large models). Cosine search itself is sub-millisecond. If your client issues many searches (e.g. an LLM/n8n agent doing RAG), embed the query once on your side and pass `query_vector` to skip server-side embedding entirely.

  **Cache bypass:** Send `Cache-Control: no-store` on a `/vectors` or `/search` request to skip the server-side embedding cache — the text is re-embedded fresh and the result is not stored in the cache.

## Settings (admin)

All settings endpoints require an admin key.

- `GET  /api/v1/settings` — Return current settings as JSON. `openai_api_key` is masked: the field is absent and `openai_api_key_set` (bool) indicates whether a key is configured.
- `PUT  /api/v1/settings` `{openai_api_base?, openai_api_key?, default_embedding_model?, cors_origins?, session_ttl_minutes?, webui_enabled?, default_project?, embedding_connect_timeout_sec?, embedding_read_timeout_sec?, embedding_cache_size?, embedding_cache_ttl_sec?, embedding_cache_max_bytes?, embedding_cache_normalize?, embedding_client_pool_size?, captcha_provider?, captcha_secret?, captcha_verify_url?}` — Merge the supplied fields into the current settings and persist. Omit `openai_api_key` or `captcha_secret` (or pass an empty string) to keep the existing secret. Changes are hot-reloaded immediately; cache settings are applied instantly via `reconfigure()`.

## Stats

- `GET /api/v1/projects/{project}/stats` — Per-project stats (collections, document counts). Accessible to any key granted the project.
- `GET /api/v1/stats` — Server-wide stats including `memory_pressure_level` and an `embedding` object with cache telemetry (`cache_size`, `cache_capacity`, `cache_hits`, `cache_misses`, `cache_hit_ratio`, `cache_bytes`). Admin only.

## Ops

Public (no auth required):

- `GET /healthz` — Liveness probe; always 200 while the process is running.
- `GET /readyz`  — Readiness probe; 200 when the database is reachable, 503 otherwise.
- `GET /openapi.json` — OpenAPI 3.1 machine-readable spec.
- `GET /llms.txt`     — This file.

Session login (used by the web UI):

- `POST /ui/login` `{key}` — Exchange an API key for an HttpOnly session cookie (`svapi_session`). The cookie may be used in place of the `Authorization: Bearer` header for all `/api/v1/*` endpoints.