Search Annotations

Search user annotations and comments across document rooms. Supports both neural and keyword search modes. Results are filtered to annotations the authenticated user has permission to view.

GET /api/search/annotations

Authentication

Requires session-based authentication. The authenticated user is automatically identified from the session. This endpoint is not accessible via API key alone — it requires an active user session.

Query parameters

Parameter	Type	Default	Description
`search`	`string`	Required	Search query.
`mode`	`string`	`"neural"`	Search mode: `"neural"` or `"keyword"`.
`page`	`integer`	`1`	Page number.
`per_page`	`integer`	`10`	Results per page.
`team`	`string`	—	Team slug to filter annotations by team.

Response

Success response

{
  "data": [
    {
      "id": "annotation-abc123",
      "created_at": "2024-11-15T10:30:00Z",
      "updated_at": "2024-11-15T10:30:00Z",
      "room_id": "room-xyz789",
      "bodies": [
        {
          "type": "TextualBody",
          "value": "Important passage on ecclesiology",
          "purpose": "commenting"
        }
      ],
      "index": 42,
      "target": {
        "selector": { "type": "TextQuoteSelector", "exact": "..." }
      },
      "version": 1
    }
  ],
  "count": 15,
  "error": null
}

Field	Type	Description
`data`	`array`	Array of matching annotations.
`data[].id`	`string`	Annotation ID.
`data[].created_at`	`string`	ISO 8601 creation timestamp.
`data[].updated_at`	`string`	ISO 8601 last-updated timestamp.
`data[].room_id`	`string`	ID of the room containing the annotation.
`data[].bodies`	`array`	Annotation body content (W3C Web Annotation format).
`data[].index`	`integer`	Position index within the room.
`data[].target`	`object`	Annotation target / selector.
`data[].version`	`integer`	Annotation version number.
`count`	`integer`	Estimated total results.
`error`	`null`	`null` on success.

Error response

{
  "error": "Unauthorized: User ID is required."
}

HTTP Status	Description
`401`	No authenticated user session.

Example

curl -G "https://vulgate.ai/api/search/annotations" \
  -H "Cookie: <session-cookie>" \
  --data-urlencode "search=ecclesiology" \
  --data-urlencode "mode=neural"

Permission model

Annotations are filtered based on the authenticated user’s access:

Private rooms: The user must be a member of the room, or the room must have no assigned users (open rooms).
Public rooms: The user must be a team member with access to the document’s team.
Team filter: When a team parameter is provided, results are further restricted to annotations on documents belonging to that team.

Notes

Neural search uses OpenAI text-embedding-3-small embeddings (768 dimensions) to find semantically similar annotations.
Keyword mode for annotations is currently a placeholder and returns empty results. Use neural mode for annotation search.