Search API quickstart

Run neural or keyword searches against your Library from the command line or any HTTP client.

May 21, 2026

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.

Related

Search help