Vector Search API

Explore the API

Launch the OpenAPI Explorer to browse the live REST specs, inspect request and response schemas, and execute calls against your environment with an API key.

All endpoints require authentication and the relevant vector permissions.

Endpoint	Method	Features	Description
/api/vector/search	GET	vector.search	Runs a vector similarity search for the current tenant/organisation scope. Query string parameters: q (required text), limit (optional, default 10).
/api/vector/settings	GET	vector.manage	Returns current vector settings including embedding provider configuration, configured providers list, indexed dimension, and auto-indexing status.
/api/vector/settings	POST	vector.manage	Updates vector settings. Body accepts { "autoIndexingEnabled": boolean } and/or { "embeddingConfig": { "providerId", "model", "dimension" } }. Changing embedding config triggers table recreation.
/api/vector/reindex	POST	vector.reindex	Recomputes embeddings. Body accepts { "entityId": "module:entity", "purgeFirst": true }. When entityId is omitted the service reindexes every configured entity for the tenant. Also available via yarn saasframe vector reindex.

Search response

GET /api/vector/search?q=customer

{
  "results": [
    {
      "entityId": "customers:customer_entity",
      "recordId": "1dcf0d22-...",
      "score": 0.89,
      "url": "/backend/customers/people/1dcf0d22-...",
      "presenter": {
        "title": "Alex Jensen",
        "subtitle": "[email protected]"
      },
      "links": [
        { "href": "/backend/customers/deals/4f18...", "label": "Open deal" }
      ]
    }
  ]
}

Each result includes a similarity score (higher is better), a primary URL, optional presenter metadata, and auxiliary links (exposed in the UI as chips / row actions).

Settings response

GET /api/vector/settings

{
  "settings": {
    "openaiConfigured": true,
    "autoIndexingEnabled": true,
    "autoIndexingLocked": false,
    "lockReason": null,
    "embeddingConfig": {
      "providerId": "openai",
      "model": "text-embedding-3-small",
      "dimension": 1536,
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    "configuredProviders": ["openai", "ollama"],
    "indexedDimension": 1536,
    "reindexRequired": false
  }
}

The configuredProviders array lists providers with valid API keys. Use this to populate provider dropdowns in custom UIs.

If SF_DISABLE_VECTOR_SEARCH_AUTOINDEXING=true, the API reports auto-indexing as locked off and rejects attempts to re-enable it from the UI or API. The legacy alias DISABLE_VECTOR_SEARCH_AUTOINDEXING=1 is still accepted for existing deployments.

Settings payloads

# Toggle auto-indexing
curl -X POST /api/vector/settings \
  -H "Content-Type: application/json" \
  --data '{"autoIndexingEnabled": false}'

# Change embedding provider (triggers reindex if dimensions differ)
curl -X POST /api/vector/settings \
  -H "Content-Type: application/json" \
  --data '{
    "embeddingConfig": {
      "providerId": "ollama",
      "model": "nomic-embed-text",
      "dimension": 768
    }
  }'

Reindex payloads

# Reindex a single entity (customers)
curl -X POST /api/vector/reindex \
  -H "Content-Type: application/json" \
  --data '{"entityId":"customers:customer_entity"}'

# Purge + rebuild everything for the current tenant
curl -X POST /api/vector/reindex \
  -H "Content-Type: application/json" \
  --data '{"purgeFirst":true}'

The API executes synchronously; for large datasets trigger the endpoint from a background job or CLI wrapper.

Future AI integrations

Vector search APIs are the backbone for planned AI workflows across Open Saasframe. The same embeddings will drive conversational chat assistants, MCP server connectors, and other automation surfaces that need semantically ranked context from your tenant data.