REST API.

The full surface the admin SPA, MCP server, and your apps share. Auth via X-API-Key header on every request. Full OpenAPI at /docs.

Auth

X-API-Key header

Every /v1/* request must carry the API key as a header. The same key gates the admin SPA login.

curl -H "X-API-Key: $FEATHER_API_KEY" \
     http://localhost:8000/v1/namespaces

v0.10 ships with a single shared key. Per-key, per-namespace authz is on the v0.11 roadmap — for now, run one container per tenant for hard isolation.

Namespaces

MethodPathDescription

POST/v1/namespacescreate namespace

DELETE/v1/namespaces/{ns}hard-delete namespace (.feather + WAL)

GET/v1/namespaceslist namespaces

GET/v1/namespaces/{ns}/statsdim + record count

Records & ingestion

MethodPathDescription

POST/v1/{ns}/vectorsadd a record with vector

POST/v1/{ns}/ingest_textembed text via configured provider + store

POST/v1/{ns}/importbulk import [{id, vector, metadata}, ...]

POST/v1/{ns}/seedbulk-insert N random records (testing)

GET/v1/{ns}/records?limit=&after=paginate records

GET/v1/{ns}/records/{id}fetch one

PUT/v1/{ns}/records/{id}update metadata

DELETE/v1/{ns}/records/{id}soft-delete (HNSW markDelete)

POST/v1/{ns}/records/{id}/linkadd typed edge

GET/v1/{ns}/records/{id}/edgesoutgoing + incoming edges

Search

MethodPathDescription

POST/v1/{ns}/searchvector search

POST/v1/{ns}/hybrid_searchvector + BM25 fused via RRF

POST/v1/{ns}/keyword_searchBM25 only

POST/v1/{ns}/context_chainvector search + BFS expansion

Discovery & maintenance

MethodPathDescription

GET/v1/{ns}/schemadistinct attribute keys + samples

GET/v1/{ns}/hierarchyBrand → Channel → Campaign tree

GET/v1/{ns}/top_recalledrecords sorted by recall_count desc

GET/v1/{ns}/graphD3-shaped nodes + edges

POST/v1/{ns}/purgebulk delete by namespace_id

POST/v1/{ns}/compactrebuild HNSW dropping soft-deleted

POST/v1/{ns}/saveflush WAL to disk

Admin & observability

MethodPathDescription

GET/v1/admin/overviewcluster stats

GET/v1/admin/metricsp50 / p95 / p99 latency + ops counts

GET/v1/admin/activityrecent ops feed

GET/v1/admin/ops_timeseriesbuckets for sparkline rendering

GET/v1/admin/connection_infocopy-paste cURL / Python / JS snippets

GET/v1/admin/embedding_modelsper-provider model catalog

GET/v1/admin/embedding_configcurrent config (API key never echoed)

PUT/v1/admin/embedding_configconfigure provider + key

OpenAPI schema

GET /docs · GET /openapi.json

FastAPI auto-generates a full OpenAPI 3.1 schema. Visit http://localhost:8000/docs for the interactive Swagger UI, or pull http://localhost:8000/openapi.json for codegen (e.g. openapi-typescript).

Embedding Providers

Python API