Search API quickstart

The Search API gives programmatic access to the same retrieval engine that powers Vulgate’s Search and Chat. You can run neural (meaning-based) and keyword (literal-match) searches, with optional filters for author, publication year, ISBN, and document ID.

The full reference lives at /docs/search/overview. This guide covers the most common patterns.

Neural search

Find passages whose meaning matches a query:

curl -G "https://vulgate.ai/api/search" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  --data-urlencode "search=early church councils on civic authority" \
  --data-urlencode "mode=neural" \
  --data-urlencode "per_page=5"

Response (truncated):

{
  "data": [
    {
      "id": "part-abc123",
      "document_id": "doc-xyz789",
      "index": "urn:vulgate:doc-xyz789:42",
      "content_rendered": "<p>The fathers reasoned that civic governance...</p>",
      "language": "en",
      "namespace": "mai",
      "documents": {
        "id": "doc-xyz789",
        "title": "The Council of Nicaea",
        "author": "...",
        "publication_date": "1995",
        "document_format": "PDF",
        "scope": "organization"
      }
    }
  ],
  "count": 42,
  "error": null
}

Keyword search

Find passages that contain the literal words. Set mode=keyword:

curl -G "https://vulgate.ai/api/search" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  --data-urlencode "search=Constantine" \
  --data-urlencode "mode=keyword" \
  --data-urlencode "per_page=10"

Filtering

Add filters via query parameters:

curl -G "https://vulgate.ai/api/search" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  --data-urlencode "search=grace" \
  --data-urlencode "author=Augustine" \
  --data-urlencode "mode=neural"

Available filters: author, publication_date (year), isbn, id (document ID for an exact match), and document_id (to search within a single document).

Choosing libraries

The libraries query parameter restricts the search to one or more Libraries. Pass it as a repeated query parameter:

curl -G "https://vulgate.ai/api/search" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  --data-urlencode "search=liturgical calendar" \
  --data-urlencode "libraries=mai" \
  --data-urlencode "libraries=orientale"

If libraries is omitted, the API defaults to your private library.

Searching documents (not passages)

To list documents that match by title instead of returning individual passages, use /api/search/documents:

curl -G "https://vulgate.ai/api/search/documents" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  --data-urlencode "search=Eucharist" \
  --data-urlencode "per_page=20"

Pagination

Use page (1-indexed) and per_page (max 100) to navigate the result set:

?search=theology&per_page=20&page=2

The response’s count field is an estimated total — suitable for paginator UIs.