Home/Docs/Cloud Edition/REST API

Cloud Edition · v0.16

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}, ...] — items without vectors are embedded server-side

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/batch_deletebulk soft-delete by ids + entity_id, optional cascade edge pruning — up to 100k IDs, one save()

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

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

Search

MethodPathDescription

POST/v1/{ns}/searchvector search (pre-filtered ANN when filter targets indexed fields)

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

POST/v1/{ns}/keyword_searchBM25 only — no vector required (v0.13.1+)

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 (returns error if too large — filter by namespace_id/entity)

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

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

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

POST/v1/{ns}/flushforce save + compact WAL immediately (bypasses throttle interval)

Index introspection (v0.13.1+)

MethodPathDescription

GET/v1/{ns}/admin/index_statsdim, record count, quantization state, auto-compaction threshold, secondary-index sizes

PUT/v1/{ns}/admin/auto_compactenable incremental compaction { "ratio": 0.2 }

PUT/v1/{ns}/admin/quantizetoggle on-disk int8 quantization { "modality": "text", "on": true }

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

POST/v1/admin/uploadstream a local .feather file to cloud (validates v1–v9, atomic adopt)

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