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"`.
`rerank`	`boolean`	`false`	For neural search, rerank grouped documents using the title, author, headings, and useful passages. Adds latency but improves precision.
`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.
`collection_ids`	`string[]`	—	Restrict results to documents in these collections. Every value must be a collection UUID — get them from `GET /api/document-collections`. Repeatable: `collection_ids=a&collection_ids=b` (or `collection_ids[]=a&collection_ids[]=b`).
`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.
`relevance_score`	`number \| null`	Document-level reranker score when `rerank=true` succeeds; otherwise `null`.
`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.
`product_url`	`string \| null`	Canonical product page associated with the document.
`document_format`	`string \| null`	Document format (e.g. `"PDF"`, `"MEDIA"`, `"DOC"`).
`scope`	`string \| null`	Visibility scope: `"private"`, `"shared"`, 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`.
`400`	`invalid-collection-ids`	`collection_ids` contained at least one empty value. A malformed (non-UUID) value returns the generic validation error above instead.
`401`	—	Missing or invalid authentication.
`403`	—	Magisterium AI library requires a paid plan.
`404`	`collection-not-found`	One or more requested collections do not exist or are not visible to you.
`404`	`team-not-found`	The `team` slug does not match a team.
`500`	`collection-lookup-failed`	The requested collections could not be resolved.

Examples

Neural search

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

Keyword search

curl -G "https://vulgate.ai/api/search" \
  -H "Authorization: Bearer $VULGATE_TEAM_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_TEAM_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_TEAM_API_KEY" \
  --data-urlencode "search=sacraments" \
  --data-urlencode "document_id=doc-xyz789" \
  --data-urlencode "libraries=mai"

Search within a collection

curl -G "https://vulgate.ai/api/search" \
  -H "Authorization: Bearer $VULGATE_TEAM_API_KEY" \
  --data-urlencode "search=grace" \
  --data-urlencode "collection_ids=b6f0c1d2-3e45-4a67-89bc-0de1f2a34567" \
  --data-urlencode "libraries=orientale"

Search multiple libraries

curl -G "https://vulgate.ai/api/search" \
  -H "Authorization: Bearer $VULGATE_TEAM_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_TEAM_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

count stays an estimate under collection_ids too: a full first page can report the vector search’s 1000-result cap even for a small collection.

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).
Shared documents are returned to the uploader and to users who own or have an accepted invite to a shared collection that contains the document.
Organization documents are returned for any authenticated team member.
Magisterium AI library (mai) requires the team to have an active paid subscription.
Collections (collection_ids) return only published documents in those collections that you can already see. Private and shared collections require a user-backed key; a service-role key can only scope to organization collections. Collection scoping narrows within your team and ignores the Magisterium AI side of libraries. Combining collection_ids with document_id or id intersects the two filters — a document outside the collection returns no results. An unknown or inaccessible collection id is a 404, not an unfiltered search.

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