Cosmic Logo

Content RAG (Semantic Search)

Search your bucket content by meaning instead of exact keywords. Content RAG embeds your objects into a vector index so a natural-language query returns the most semantically relevant objects, even when the wording differs.

Content RAG is in Beta. New projects and workspaces have it on by default. For existing ones, an admin or manager can turn it on under Settings → Semantic search (project or workspace settings); existing content is indexed automatically in the background. Keyword search via Queries is always available.

The same retrieval powers Agents: when enabled, content and team agents can find objects by meaning with the search_content tool instead of scanning titles.

Base URL

https://workers.cosmicjs.com
POST/v3/buckets/:bucket_slug/ai/search

Embed a query and return the objects whose content is closest in meaning, ranked by similarity score. This is retrieval only (no answer generation) and requires a bucket write key.

Required parameters

  • Name
    query
    Type
    string
    Description

    The natural-language search query. Results are ranked by semantic similarity to this text.

Optional parameters

  • Name
    type
    Type
    string
    Description

    Restrict results to a single object type slug (e.g. blog-posts).

  • Name
    locale
    Type
    string
    Description

    Restrict results to a single locale.

  • Name
    status
    Type
    string
    Description

    Filter by object status (e.g. published, draft).

  • Name
    limit
    Type
    number
    Description

    Maximum number of results to return. Default 10, maximum 50.

  • Name
    min_score
    Type
    number
    Description

    Minimum similarity score (0-1). Results below this threshold are dropped. Default 0.

Request Examples

curl -X POST \
  https://workers.cosmicjs.com/v3/buckets/BUCKET_SLUG/ai/search \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer BUCKET_WRITE_KEY' \
  -d '{
    "query": "how do refunds work on annual plans",
    "type": "policies",
    "limit": 10,
    "min_score": 0.6
  }'

Response

{
  "results": [
    {
      "object_id": "66f1a2...",
      "slug": "refund-policy",
      "type": "policies",
      "locale": "en",
      "status": "published",
      "score": 0.83,
      "snippet": "Annual plans can be refunded within 30 days of purchase..."
    },
    {
      "object_id": "66f1b7...",
      "slug": "billing-faq",
      "type": "faqs",
      "locale": "en",
      "status": "published",
      "score": 0.74,
      "snippet": "After the refund window, plans are non-refundable but..."
    }
  ]
}

How it works

  • Embeddings on write. When Content RAG is enabled for your account, Cosmic embeds each object's searchable text (title, slug, content, and text-like Metafields) into a vector index and keeps it in sync as you create, edit, publish, unpublish, and delete content. Embedding your content is free; it does not consume AI tokens.
  • Search at query time. Each ai/search call embeds your query and runs a vector search scoped to your bucket. Query-time usage is metered through the standard AI token system.
  • Semantic vs. keyword. Use ai/search to match on meaning. Use Queries for exact, structured filtering (by metadata values, dates, and ranges). They are complementary: reach for structured queries when you know the exact field/value, and semantic search when you're matching intent.

The dashboard search (⌘K) is fast title/type navigation inside the dashboard UI. Content RAG semantic search is an API that ranks your content by meaning for use in your apps, support bots, and agents.