Overview

The Vulgate Search API lets you query your document libraries using neural (semantic) search, keyword search, or title matching. It returns ranked passages from ingested documents along with full document metadata, enabling you to build search experiences, RAG pipelines, and content discovery features.

Base URL

All Search API endpoints are relative to your Vulgate instance:

https://vulgate.ai/api

Endpoints

Authentication

All endpoints require authentication via a Bearer token in the Authorization header:

Authorization: Bearer <your-api-key>

API keys are scoped to a team and carry the permissions of the team owner. See Getting Started for how to obtain and configure your API key.

Search modes

The Search API supports two search modes, set via the mode query parameter:

Neural (default)

?mode=neural

Semantic search powered by vector embeddings. Your query is converted to an embedding and matched against document content using a hybrid strategy that combines dense vector similarity (cosine) with sparse keyword matching (BM25). This is the recommended mode for natural-language queries.

Keyword

?mode=keyword

Traditional full-text search using BM25 ranking. Best for exact-term lookups, identifiers, or queries where precise wording matters.

Libraries

Search results are scoped to one or more libraries. If omitted, the API defaults to private.

Pass libraries as query parameters:

?libraries=orientale&libraries=mai

Or using bracket syntax:

?libraries[]=orientale&libraries[]=mai

Quick example

Search for passages about eucharistic theology across the Magisterium AI library:

curl -G "https://vulgate.ai/api/search" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  --data-urlencode "search=eucharistic theology" \
  --data-urlencode "libraries=mai" \
  --data-urlencode "mode=neural" \
  --data-urlencode "per_page=5"

The response returns a ranked list of matching passages under data, each with the source document’s metadata:

{
  "data": [
    {
      "id": "part-abc123",
      "document_id": "doc-xyz789",
      "index": "urn:vulgate:doc-xyz789:42",
      "content_rendered": "<p>The eucharistic theology of...</p>",
      "language": "en",
      "namespace": "magisterium",
      "documents": {
        "id": "doc-xyz789",
        "title": "Ecclesia de Eucharistia",
        "author": "John Paul II",
        "publication_date": "2003",
        "document_format": "PDF",
        "scope": "organization"
      }
    }
  ],
  "count": 42,
  "error": null
}

Rate limits

Search requests have a maximum execution time of 40 seconds. If your query does not complete within this window, the request will time out. Narrow your search with filters or reduce per_page to improve response times.

Next steps

• Search Content - full reference for the main search endpoint
• Search Documents - search by document title
• Search Annotations - search user annotations
• Query Syntax - advanced query filters and modifiers