API Reference

Interactive Swagger UI documenting the REST API

Rosmarium provides a comprehensive REST API for content management, semantic search, and graph traversals. All endpoints expect and return standard application/json.

Authentication

All API endpoints (except public reads if explicitly configured) require authentication. You can use a Session Cookie (for browser contexts) or an API Key (for server-to-server communication).

Example: API Key Auth

curl -H ‘Authorization: Bearer ctx_live_…’ http://localhost:3000/api/content-types

Endpoint Definitions

GET/api/content/:type

Fetch a paginated list of entries for a specific content type.

Parameters

filters (optional) e.g. filters[status][eq]=draft
sort (optional) e.g. createdAt:desc
limit (optional) default 20

Response

{
  "data": [
    { "id": "cuid...", "data": { "title": "Hello" } }
  ],
  "meta": { "total": 1 }
}

GET/api/search

Perform a hybrid search across all content types using Reciprocal Rank Fusion (RRF).

Parameters

q (required) The search string
alpha (optional) 0=keyword, 1=vector. Default 0.5
limit (optional) default 10

Response

{
  "data": [
    { "id": "cuid...", "score": 0.0156, "snippet": "..." }
  ],
  "meta": { "alpha": 0.5, "latencyMs": 42 }
}

POST/api/rag/retrieve

Retrieve semantically relevant chunks formatted for LLM context windows.

Body payload

{
  "query": "Install guide?",
  "content_types": ["doc"],
  "top_k": 5,
  "rerank": true
}

Response

{
  "chunks": [
    { "chunk_text": "...", "score": 0.89 }
  ]
}

POST/api/ingestor/jobs

Start a new intelligent web crawl and content ingestion job.

Body payload

{
  "startUrl": "https://example.com/blog",
  "maxDepth": 2,
  "maxPages": 100,
  "contentSetName": "Blog Migration",
  "importAs": "draft",
  "apiKey": "ctx_live_..."
}

Response

{
  "data": {
    "jobId": "test-job-id",
    "contentSetId": "set-123",
    "status": "queued"
  }
}