Search API: Keyword and Semantic

Three endpoints, increasing in sophistication:

/api/v1/search — hybrid (keyword + semantic) ranked
/api/v1/search/semantic — semantic only
/api/v1/search/qa — natural language Q&A with citations

Hybrid search (default)

curl "https://yourtenant.papyrus.io/api/v1/search?q=contract+expiring&limit=20" \
  -H "Authorization: Bearer $KEY" -H "X-Tenant-Id: $TENANT"

Response:

{
  "success": true,
  "data": {
    "results": [
      {
        "documentId": "f47ac10b-...",
        "title": "Service Contract — Acme Ltd",
        "snippet": "...contract expires on 31 December 2026...",
        "score": 0.94,
        "category": "Contract",
        "url": "/documents/f47ac10b-.../view"
      }
    ],
    "totalCount": 42,
    "queryTimeMs": 73
  }
}

Advanced filters

Combine with filters:

curl "https://yourtenant.papyrus.io/api/v1/search?q=invoice&\
classification=Invoice&\
dateFrom=2026-01-01&\
dateTo=2026-06-30&\
folderId=11111111-..." \
  -H "Authorization: Bearer $KEY" -H "X-Tenant-Id: $TENANT"

Filter parameters:

Parameter	Notes
`classification`	Document type (e.g., `Invoice`, `Contract`)
`dateFrom` / `dateTo`	ISO 8601 date or date-time
`folderId`	Folder UUID
`tag`	Tag value (repeat for multiple)
`author`	User UUID
`confidenceMin`	Minimum AI confidence
`confidentialityMax`	Max sensitivity level (you only see what you can access anyway)

Semantic-only search

Useful when keyword matches are too narrow:

curl "https://yourtenant.papyrus.io/api/v1/search/semantic?q=policies+about+remote+work&limit=10" \
  -H "Authorization: Bearer $KEY" -H "X-Tenant-Id: $TENANT"

Q&A endpoint (RAG)

For natural-language questions where you want a synthesised answer:

curl https://yourtenant.papyrus.io/api/v1/search/qa \
  -X POST \
  -H "Authorization: Bearer $KEY" -H "X-Tenant-Id: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What contracts expire in the next 90 days?",
    "conversationId": null,
    "maxSources": 5
  }'

Response:

{
  "success": true,
  "data": {
    "answer": "Three contracts expire in the next 90 days: ...",
    "conversationId": "conv_8a3b9c2d",
    "citations": [
      {
        "documentId": "f47ac10b-...",
        "title": "Service Contract — Acme Ltd",
        "page": 1,
        "snippet": "...expires 31 December 2026..."
      }
    ]
  }
}

Continue a conversation by passing the returned conversationId on subsequent calls.

Performance

P50 hybrid search latency: 45ms
P95 hybrid search latency: 220ms
P50 Q&A latency: 1.2s (depends on cloud LLM cold-start)
P95 Q&A latency: 4s

RBAC

All search endpoints respect the calling key's scope and the underlying user permissions. Results never include documents the user/key cannot access.