API Surface

Transport Layer

Protocol	Default Port	Purpose
HTTP/REST	6340	Primary: used for all operations (collection management, data ingestion, search, learn, graduation)

The server is started via prismdb serve --port 6340 --data-dir ./data. All endpoints are under the /api/v1/ prefix.

1. Collection Management

CreateCollection

POST /api/v1/collections

{
  "name": "products",
  "dimensions": [
    { "name": "material", "type": "semantic" },
    { "name": "color", "type": "semantic" },
    { "name": "style", "type": "semantic" },
    { "name": "category", "type": "exact" }
  ]
}

Dimension types:

Type	Behavior
`"semantic"`	Free-text values indexed with BM25 sparse + dense 1024d vectors
`"exact"`	Enumerated values with equality matching + optional enum alias expansion

Optional fields: temporal: true (enable temporal axis), null_values (sentinels to skip at insert, default ["NA", "N/A", ""]).

DropCollection

DELETE /api/v1/collections/{name}

Removes all data, indices, caches, and vocabulary for the collection. Evicts TrackIndex and vocab caches (temporal collections).

GetCollection / ListCollections

GET /api/v1/collections/{name}
GET /api/v1/collections

Returns schema, dimension configs, record count, segment info.

2. Data Ingestion

Insert

POST /api/v1/collections/{name}/records

{
  "id": "SKU-001",
  "facts": {
    "material": "genuine Italian leather",
    "color": "midnight navy",
    "style": "minimalist low-top sneaker",
    "category": "footwear"
  }
}

Record is searchable immediately via all lenses on insert. Null values (matching the collection’s null_values list) are skipped: absence-native sparsity.

For temporal collections, each insert appends a timestamped chunk to the record’s streams. The stream_key (default: record id / track_id) groups chunks belonging to the same entity.

Get

GET /api/v1/collections/{name}/records/{id}

Returns the record’s facts and artifact fields.

Delete

DELETE /api/v1/collections/{name}/records/{id}

Removes the record from all indices.

3. Query

Search

POST /api/v1/collections/{name}/search

{
  "query": "blue leather shoes",
  "limit": 10
}

Response:

{
  "results": [
    {
      "id": "SKU-001",
      "score": 0.94,
      "facts": {
        "material": "genuine Italian leather",
        "color": "midnight navy",
        "style": "minimalist low-top sneaker"
      },
      "matched_dimensions": ["color", "material", "style"]
    }
  ],
  "elapsed_ms": 5
}

Temporal query parameters (temporal collections only):

Parameter	Type	Effect
`time_at`	timestamp	As-of query: only chunks present at time T, latest per track
`time_range`	`[start, end)`	Range filter on fact timestamps
`time_latest`	boolean	Search only the most recent chunk per track (opt-in, not default)
`sequence`	`["A", "B"]`	Trajectory: find tracks where A happened before B (strict ts ordering)

Other parameters: backfill: true (pad tail with gate rejects ordered by evidence), entity_rollup / entity_df (opt-in entity-level mechanisms).

4. Vocabulary & Lifecycle

Learn

POST /api/v1/collections/{name}/learn

Triggers the cost ladder of vocabulary expansion tiers on the collection. NLI judges corpus-derived candidates per (dimension, value). Cached per unique pair; warm re-learn is milliseconds.

Reindex

POST /api/v1/collections/{name}/reindex

Rebuilds BM25 sparse vectors in-place to incorporate learned expansions. No delete/reload needed.

Graduate

POST /api/v1/collections/{name}/graduate

Full lifecycle step: seal segment → learn (novelty diff via pair cache) → reindex → compile entity documents (temporal) → open next segment. Score-identical to the manual flow (load → learn → delete → reload).

5. Admin

Stats / Health

GET /api/v1/collections/{name}/stats
GET /api/v1/health

Collection stats include per-dimension vocabulary size, record count, segment info. Health endpoint confirms server is running.

Experimental

POST /api/v1/collections/{name}/reflect, .../load-oracle, .../train-router exist for internal experimentation (learned-routing research). Unstable: not part of the supported surface.

6. Feedback (Planned)

POST /api/v1/collections/{name}/feedback

Planned endpoint for query-log learning: accept search feedback (query + clicked results) to derive vocabulary expansions from real usage patterns. See the query-log learning design for the Class A (NLI-gated) and Class B (usage-gated) tiers.

SDK Status

Client SDKs (Python, Rust, Go) are on the roadmap. The HTTP API is the stable surface today; use curl or any HTTP client directly.