CosmoOps KB — API Reference

1. Authentication

All API endpoints (except the health check) require a valid API key. Pass it via one of two headers:

# Option A — Authorization header (recommended)
curl https://kb.cosmoops.com/api/v1/store \
  -H "Authorization: Bearer cmo_YOUR_API_KEY"

# Option B — X-API-Key header
curl https://kb.cosmoops.com/api/v1/store \
  -H "X-API-Key: cmo_YOUR_API_KEY"

If the key is missing, expired, or revoked the API returns 401.

2. Creating API Keys

API keys are managed from the CosmoOps dashboard — there is no API endpoint to create them programmatically.

1. Sign in to the CosmoOps dashboard.
2. Navigate to Settings → API Keys.
3. Click "Create API Key" and enter a descriptive name.
4. Copy the key immediately — it is shown only once.

Keys use the format cmo_<32 random chars>. You can revoke keys at any time from the same settings page.

3. Health Check

Returns the API status. No authentication required.

curl https://kb.cosmoops.com/api/v1/health

Response:

{ "status": "ok" }

4. Create a Store

Creates a new knowledge store to hold documents. Each store is scoped to your organization.

Request Body

Example

curl -X POST https://kb.cosmoops.com/api/v1/store \
  -H "Authorization: Bearer cmo_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Docs",
    "description": "Public product documentation",
    "source": {
      "id": "product-docs",
      "collection": "documentation"
    }
  }'

Response 201:

{
  "store": {
    "id": "abc123",
    "orgId": "org_xyz",
    "name": "Product Docs",
    "description": "Public product documentation",
    "source": {
      "id": "product-docs",
      "collection": "documentation"
    },
    "documentCount": 0,
    "customCount": 0,
    "createdBy": "api:key_id",
    "createdAt": "...",
    "updatedAt": "..."
  }
}

5. Update a Store

Updates an existing store. Only the fields you include in the request body will be changed.

URL Parameters

Request Body

Example

curl -X PUT https://kb.cosmoops.com/api/v1/store/abc123 \
  -H "Authorization: Bearer cmo_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Docs v2",
    "description": "Updated documentation store"
  }'

Response 200:

{
  "store": {
    "id": "abc123",
    "name": "Product Docs v2",
    "description": "Updated documentation store",
    "...": "..."
  }
}

6. Delete a Store

Permanently deletes a store and all its documents. This operation is idempotent — deleting an already-deleted store returns success.

Example

curl -X DELETE https://kb.cosmoops.com/api/v1/store/abc123 \
  -H "Authorization: Bearer cmo_YOUR_API_KEY"

Response 200:

{ "deleted": true }

7. How RAG Works

CosmoOps uses a Retrieval-Augmented Generation (RAG) pipeline to answer queries against your knowledge stores. Here is what happens when you call the query endpoint:

1. Embedding — Your query text is converted into a vector embedding using Vertex AI.
2. Retrieval — The embedding is used to perform a similarity search against document embeddings stored in Firestore, returning up to topK results.
3. LLM Judgment (optional) — When enableRagEvaluation is turned on, an LLM judge evaluates whether the retrieved documents actually answer the query. It produces a relevance flag, confidence score, reasoning, and a synthesised answer.
4. Response — The API returns the matched sources, answer text, and optional judgment metadata.

8. Query (RAG Search)

Performs a RAG query against a store and returns relevant documents with an AI-generated answer.

Request Body

Example

curl -X POST https://kb.cosmoops.com/api/v1/query \
  -H "Authorization: Bearer cmo_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "abc123",
    "query": "How do I configure SSO?",
    "topK": 5,
    "enableRagEvaluation": true
  }'

Response 200:

{
  "answer": "To configure SSO, navigate to Settings → Identity ...",
  "sources": [
    {
      "id": "doc_456",
      "summary": "SSO configuration guide for enterprise accounts",
      "score": 0.92,
      "updatedAt": "2026-04-01T12:00:00Z"
    }
  ],
  "retrievedCount": 3,
  "judgment": {
    "relevant": true,
    "confidence": 0.95,
    "reasoning": "Documents contain a direct SSO setup guide.",
    "answer": "To configure SSO, navigate to Settings → Identity ..."
  }
}

Example Without RAG Evaluation

curl -X POST https://kb.cosmoops.com/api/v1/query \
  -H "Authorization: Bearer cmo_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "abc123",
    "query": "deployment checklist"
  }'

Response 200:

{
  "answer": "Retrieved 2 relevant documents.",
  "sources": [
    {
      "id": "doc_789",
      "summary": "Pre-deployment checklist for production releases",
      "score": 0.87
    },
    {
      "id": "doc_012",
      "summary": "Infrastructure readiness template",
      "score": 0.71
    }
  ],
  "retrievedCount": 2
}

9. Error Reference

All errors return a JSON body with an error field and optional details.

Error Response Shape

{
  "error": "Invalid request parameters",
  "details": [
    {
      "code": "too_small",
      "minimum": 1,
      "type": "string",
      "inclusive": true,
      "exact": false,
      "message": "storeId is required",
      "path": [
        "storeId"
      ]
    }
  ]
}