Search Content

Search across document content in one or more libraries. Returns ranked passages (document parts) with full document metadata. Supports neural (semantic) and keyword search modes.

GET /api/search

Authentication

Requires a Bearer token. See Getting Started.

Authorization: Bearer <your-api-key>

Query parameters

Parameter	Type	Default	Description
`search`	`string`	Required	Search query. Supports advanced query syntax.
`mode`	`string`	`"neural"`	Search mode: `"neural"` or `"keyword"`.
`libraries`	`string[]`	`["private"]`	Libraries to search. Pass multiple values with `libraries=a&libraries=b` or `libraries[]=a&libraries[]=b`.
`page`	`integer`	`1`	Page number (1-indexed).
`per_page`	`integer`	`10`	Results per page. Min: `1`, Max: `100`.
`author`	`string`	—	Filter by author name (partial match).
`publication_date`	`string`	—	Filter by publication year.
`isbn`	`string`	—	Filter by ISBN or ISBN-13.
`id`	`string`	—	Filter by a specific document ID.
`document_id`	`string`	—	Search within a specific document.
`team`	`string`	—	Team slug. Automatically inferred from your API key if not provided.
`user_id`	`string`	—	User ID for private library access. Automatically inferred from session-based auth.

Response

Success response

{
  "data": [SearchResult],
  "count": 42,
  "error": null
}

Field	Type	Description
`data`	`SearchResult[]`	Array of matching document parts.
`count`	`integer`	Estimated total number of results (for pagination).
`error`	`null`	`null` on success.

SearchResult object

Field	Type	Description
`id`	`string`	Unique ID of the document part.
`created_at`	`string`	ISO 8601 timestamp.
`document_id`	`string`	ID of the parent document.
`index`	`string \| number`	URN reference within the document (e.g. `urn:vulgate:doc-id:section`), or a numeric position.
`content_rendered`	`string \| null`	HTML-rendered content of the matching passage.
`headings`	`string[] \| null`	Section headings associated with this passage.
`language`	`string \| null`	ISO language code (e.g. `"en"`, `"la"`, `"grc"`).
`namespace`	`string`	Team slug / namespace the result belongs to.
`documents`	`object`	Parent document metadata (see below).

Documents object

Field	Type	Description
`id`	`string`	Document ID.
`title`	`string \| null`	Document title.
`author`	`string \| null`	Author name.
`publication_date`	`string \| null`	Publication year.
`publication_place`	`string \| null`	Place of publication.
`isbn`	`string \| null`	ISBN-10.
`isbn_13`	`string \| null`	ISBN-13.
`publisher`	`string \| null`	Publisher name.
`document_format`	`string \| null`	Document format (e.g. `"PDF"`, `"MEDIA"`, `"DOC"`).
`scope`	`string \| null`	Visibility scope: `"private"` or `"organization"`.

Error response

{
  "data": null,
  "count": 0,
  "error": {
    "code": "no-libraries-selected",
    "message": "No libraries selected"
  }
}

HTTP Status	Error Code	Description
`400`	—	Validation error (invalid parameters).
`400`	`no-libraries-selected`	No libraries were included in the request.
`400`	`private-library-no-user-id`	Private library requires a `user_id`.
`401`	—	Missing or invalid authentication.
`403`	—	Magisterium AI library requires a paid plan.

Examples

Neural search

curl -G "https://vulgate.ai/api/search" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  --data-urlencode "search=the role of bishops in early Christianity" \
  --data-urlencode "libraries=mai" \
  --data-urlencode "mode=neural" \
  --data-urlencode "per_page=10" \
  --data-urlencode "page=1"

Keyword search

curl -G "https://vulgate.ai/api/search" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  --data-urlencode "search=Nicene Creed" \
  --data-urlencode "libraries=mai" \
  --data-urlencode "mode=keyword"

Filter by author

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

Search within a document

curl -G "https://vulgate.ai/api/search" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  --data-urlencode "search=sacraments" \
  --data-urlencode "document_id=doc-xyz789" \
  --data-urlencode "libraries=mai"

Search multiple libraries

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

Search private documents

curl -G "https://vulgate.ai/api/search" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  --data-urlencode "search=meeting notes" \
  --data-urlencode "libraries=private" \
  --data-urlencode "user_id=your-user-id"

Pagination

Results are paginated. Use page and per_page to navigate through results.

The count field in the response provides an estimated total number of matching results. This is suitable for rendering pagination controls but should not be treated as an exact count.

# Page 1
?search=theology&per_page=20&page=1
 
# Page 2
?search=theology&per_page=20&page=2

Scope and permissions

Search results respect document visibility scopes:

Private documents are only returned when the authenticated user matches the document uploader. Requires user_id to be set (inferred automatically with session auth).
Organization documents are returned for any authenticated team member.
Magisterium AI library (mai) requires the team to have an active paid subscription.

When searching both private and organization libraries simultaneously, results from both scopes are merged and paginated together.