openapi.yaml

openapi: 3.1.0
info:
  title: Quivr V2 public text foundation contract
  version: 0.0.0-draft
  description: THE-543 and THE-547 evaluation contracts; endpoint implementations are separate work. Matching
    criterion is plugin-owned and deferred. One configured webhook destination, immutable Matches, independent
    at-least-once Delivery and reference-only notifications. OpenAPI is authoritative for transport shapes.
    THE-640 adds text search and asynchronous Corpus projection rebuild initiation.
security:
- ApiKey: []
# Public engine error classes and the operations that can return them.
# Documentation only: responses and schemas below remain authoritative.
# embedded errors occur inside a successful result, not as its HTTP status.
# response_code records a domain condition reported with an existing envelope code.
# response_code_from marks delivery conditions whose public code comes from the provider.
x-public-errors:
  record_count_too_broad:
    status_class: 422
    retryable: false
    operations: [countRecords]
  corpus_archived:
    status_class: 409
    retryable: false
    operations: [getCorpusStats, searchRecords, listRecords, countRecords, countFacets, pollChanges, streamChanges, requestConnectorRun]
  delivery_failed:
    status_class: 500
    retryable: false
    response_code_from: provider_delivery
    operations: [challengeConnectorAPI, pushConnectorAPI, relayConnectorChallenge, relayConnectorDelivery]
  delivery_unavailable:
    status_class: 503
    retryable: true
    response_code_from: provider_delivery
    operations: [challengeConnectorAPI, pushConnectorAPI, relayConnectorChallenge, relayConnectorDelivery]
  invalid_idempotency_key:
    status_class: 400
    retryable: false
    operations: [challengeConnectorAPI, pushConnectorAPI, relayConnectorChallenge, relayConnectorDelivery]
  ip_not_allowed:
    status_class: 403
    retryable: false
    operations: [challengeConnectorAPI, pushConnectorAPI, relayConnectorChallenge, relayConnectorDelivery]
  rate_limited:
    status_class: 429
    retryable: true
    operations: [challengeConnectorAPI, pushConnectorAPI, relayConnectorChallenge, relayConnectorDelivery]

  backfill_in_progress:
    status_class: 409
    retryable: false
    operations: [requestBackfill, rerunOperation]
  batch_too_large:
    status_class: 413
    retryable: false
    operations: [ingestBatch]
  changes_unavailable:
    status_class: 503
    retryable: true
    operations: [pollChanges, streamChanges]
  connector_disabled:
    status_class: 409
    retryable: false
    operations: [createConnectorToken, pauseConnector, resumeConnector, requestConnectorRun, rotateConnectorToken]
  connector_paused:
    status_class: 409
    retryable: false
    operations: [requestConnectorRun]
  connectors_unavailable:
    status_class: 503
    retryable: true
    operations: [challengeConnectorAPI, changeConnectorSchedule, createConnector, createConnectorToken, disableConnector, pauseConnector, resumeConnector, getConnector, listConnectorKinds, listConnectorTokens, listConnectors, pushConnectorAPI, relayConnectorChallenge, relayConnectorDelivery, replaceConnectorCredential, requestConnectorRun, revokeConnectorToken, rotateConnectorToken]
  content_unavailable:
    status_class: 503
    retryable: true
    operations: [getCorpusStats, getReceipt, getRecord, getVersion, ingestBatch, ingestRecord, listRecords, countRecords, countFacets, withdrawRecord]
  cost_confirmation_required:
    status_class: 409
    retryable: false
    operations: [requestBackfill]
  coverage_incomplete:
    status_class: 409
    retryable: false
    operations: [promoteVectorSpace]
  credentials_unavailable:
    status_class: 503
    retryable: false
    operations: [createConnector, replaceConnectorCredential]
  cursor_expired:
    status_class: 410
    retryable: false
    operations: [pollChanges, streamChanges]
  cursor_scope_changed:
    status_class: 409
    retryable: false
    operations: [getCorpusStats, listAdminDocuments, listCorpora, listDeliveryAttempts, listMatches, listQuarantinedVersions, listRecords, listSubscriptions, pollChanges, streamChanges]
  definition_too_large:
    status_class: 422
    retryable: false
    operations: [createSavedQuery, createSavedQueryVersion, createSubscription, createSubscriptionVersion, previewSubscription]
  dependency_unavailable:
    status_class: 503
    retryable: true
    operations: [listVectorSpaces]
  dry_run_required:
    status_class: 409
    retryable: false
    operations: [reprocessQuarantine, requestBackfill]
  entry_too_large:
    status_class: 413
    retryable: false
    operations: [ingestBatch]
  evidence_expired:
    status_class: 410
    retryable: false
    operations: [getMatch, listMatches]
  evaluator_error:
    status_class: 502
    retryable: false
    operations: [previewSubscription]
  evaluator_unavailable:
    status_class: 503
    retryable: true
    operations: [previewSubscription]
  extension_namespace_owned:
    status_class: 422
    retryable: false
    operations: [ingestBatch, ingestRecord, withdrawRecord]
  forbidden:
    status_class: 403
    retryable: false
    operations: [getCorpusStats, activatePlugin, cancelOperation, challengeConnectorAPI, changeConnectorSchedule, configureRetrieval, confirmUpload, createConnector, createConnectorToken, createCorpus, createSavedQuery, createSavedQueryVersion, createSubscription, createSubscriptionVersion, createUpload, deleteSavedQuery, deleteSubscription, disableConnector, pauseConnector, resumeConnector, disableSubscription, enableSubscription, getActivePipelinePlan, getBlob, getConnector, listConnectorPushStats, getCorpus, getDelivery, getDocumentTimeline, getEvaluationRetirement, getMatch, getMatchStats, getOperation, getPipelinePlan, getPluginCallStats, getPluginRegistration, getReceipt, getReceivedStats, getRecord, getSavedQuery, getSavedQueryVersion, getSearchStats, getStepStats, getSubscription, getSubscriptionVersion, getTopQueries, getUpload, getVersion, ingestBatch, ingestRecord, listActivePlugins, listAdminDocuments, listConnectorKinds, listConnectorTokens, listConnectors, listCorpora, listDeliveryAttempts, listEvaluationBacklog, listMatches, listPipelinePlans, listPluginRegistrations, listQuarantinedVersions, listRecords, countRecords, countFacets, listSearchProfiles, listSubscriptions, listVectorSpaces, migrateSubscriptionEvaluators, pauseOperation, pollChanges, previewSubscription, promoteVectorSpace, pushConnectorAPI, rebuildCorpusProjection, registerPlugin, renameSavedQuery, renameSubscription, replaceConnectorCredential, reprocessQuarantine, requestBackfill, requestConnectorRun, rerunOperation, resumeOperation, retireEvaluations, revokeConnectorToken, rollbackPipelinePlan, rotateConnectorToken, searchRecords, streamChanges, withdrawRecord]
  idempotency_conflict:
    status_class: 409
    retryable: false
    operations: [activatePlugin, cancelOperation, changeConnectorSchedule, configureRetrieval, confirmUpload, createConnector, createCorpus, createSavedQuery, createSavedQueryVersion, createSubscription, createSubscriptionVersion, createUpload, deleteSavedQuery, deleteSubscription, disableConnector, pauseConnector, resumeConnector, disableSubscription, enableSubscription, ingestBatch, ingestRecord, migrateSubscriptionEvaluators, pauseOperation, rebuildCorpusProjection, registerPlugin, renameSavedQuery, renameSubscription, replaceConnectorCredential, reprocessQuarantine, requestBackfill, requestConnectorRun, rerunOperation, resumeOperation, retireEvaluations, rollbackPipelinePlan, withdrawRecord]
  invalid_api_key:
    status_class: 401
    retryable: false
    operations: [activatePlugin, cancelOperation, challengeConnectorAPI, changeConnectorSchedule, configureRetrieval, confirmUpload, createConnector, createConnectorToken, createCorpus, createSavedQuery, createSavedQueryVersion, createSubscription, createSubscriptionVersion, createUpload, deleteSavedQuery, deleteSubscription, disableConnector, pauseConnector, resumeConnector, disableSubscription, enableSubscription, getActivePipelinePlan, getBlob, getConnector, listConnectorPushStats, getCorpus, getDelivery, getDocumentTimeline, getEvaluationRetirement, getMatch, getMatchStats, getOperation, getPipelinePlan, getPluginCallStats, getPluginRegistration, getReceipt, getReceivedStats, getRecord, getSavedQuery, getSavedQueryVersion, getSearchStats, getStepStats, getSubscription, getSubscriptionVersion, getTopQueries, getUpload, getVersion, ingestBatch, ingestRecord, listActivePlugins, listAdminDocuments, listConnectorKinds, listConnectorTokens, listConnectors, listCorpora, listDeliveryAttempts, listEvaluationBacklog, listMatches, listPipelinePlans, listPluginRegistrations, listQuarantinedVersions, listRecords, countRecords, countFacets, listSearchProfiles, listSubscriptions, listVectorSpaces, migrateSubscriptionEvaluators, pauseOperation, pollChanges, previewSubscription, promoteVectorSpace, pushConnectorAPI, rebuildCorpusProjection, registerPlugin, renameSavedQuery, renameSubscription, replaceConnectorCredential, reprocessQuarantine, requestBackfill, requestConnectorRun, rerunOperation, resumeOperation, retireEvaluations, revokeConnectorToken, rollbackPipelinePlan, rotateConnectorToken, searchRecords, streamChanges, withdrawRecord]
  invalid_backfill:
    status_class: 422
    retryable: false
    operations: [requestBackfill]
  invalid_config:
    status_class: 422
    retryable: false
    operations: [changeConnectorSchedule, createConnector, replaceConnectorCredential]
  invalid_credential:
    status_class: 422
    retryable: false
    operations: [changeConnectorSchedule, createConnector, replaceConnectorCredential]
  invalid_cursor:
    status_class: 422
    retryable: false
    operations: [getCorpusStats, listAdminDocuments, listConnectors, listCorpora, listDeliveryAttempts, listMatches, listPipelinePlans, listPluginRegistrations, listQuarantinedVersions, listRecords, listSubscriptions, pollChanges, streamChanges]
  invalid_expression:
    status_class: 422
    retryable: false
    operations: [createSubscription, createSubscriptionVersion, migrateSubscriptionEvaluators, previewSubscription]
  invalid_input:
    status_class: 422
    retryable: false
    operations: [confirmUpload, createConnector, createUpload, ingestBatch, ingestRecord, retireEvaluations, withdrawRecord]
  invalid_instance_token:
    status_class: 401
    retryable: false
    operations: [challengeConnectorAPI, pushConnectorAPI]
  invalid_interval:
    status_class: 422
    retryable: false
    operations: [changeConnectorSchedule, createConnector, replaceConnectorCredential]
  invalid_json:
    status_class: 400
    retryable: false
    operations: [challengeConnectorAPI, pushConnectorAPI, relayConnectorChallenge, relayConnectorDelivery]
  invalid_limit:
    status_class: 422
    retryable: false
    operations: [listConnectorPushStats, getReceivedStats, getTopQueries, listAdminDocuments, listConnectorTokens, listConnectors, listCorpora, listDeliveryAttempts, listEvaluationBacklog, listMatches, listPipelinePlans, listPluginRegistrations, listQuarantinedVersions, listRecords, listSubscriptions, pollChanges, retireEvaluations]
  invalid_mapping:
    status_class: 422
    retryable: false
    operations: [configureRetrieval, createCorpus]
  invalid_migration:
    status_class: 422
    retryable: false
    operations: [migrateSubscriptionEvaluators]
  invalid_owner:
    status_class: 422
    retryable: false
    operations: [createSubscription, listSubscriptions]
  invalid_plugin:
    status_class: 422
    retryable: false
    operations: [activatePlugin, registerPlugin]
  invalid_query:
    status_class: 422
    retryable: false
    operations: [getCorpusStats, searchRecords, listConnectorPushStats, getEvaluationRetirement, getMatchStats, getPluginCallStats, getReceivedStats, getSearchStats, getStepStats, getTopQueries, listAdminDocuments, listConnectorKinds, listConnectorTokens, listConnectors, listCorpora, listDeliveryAttempts, listEvaluationBacklog, listMatches, listPipelinePlans, listPluginRegistrations, listQuarantinedVersions, listRecords, countRecords, countFacets, listSubscriptions, pollChanges, streamChanges]
  invalid_reprocess:
    status_class: 422
    retryable: false
    operations: [reprocessQuarantine]
  invalid_schema:
    status_class: 422
    retryable: false
    operations: [activatePlugin, cancelOperation, changeConnectorSchedule, configureRetrieval, confirmUpload, createConnector, createCorpus, createSavedQuery, createSavedQueryVersion, createSubscription, createSubscriptionVersion, createUpload, deleteSavedQuery, deleteSubscription, disableConnector, pauseConnector, resumeConnector, disableSubscription, enableSubscription, ingestBatch, ingestRecord, migrateSubscriptionEvaluators, pauseOperation, previewSubscription, promoteVectorSpace, rebuildCorpusProjection, registerPlugin, relayConnectorChallenge, relayConnectorDelivery, renameSavedQuery, renameSubscription, replaceConnectorCredential, reprocessQuarantine, requestBackfill, requestConnectorRun, rerunOperation, resumeOperation, retireEvaluations, rollbackPipelinePlan, searchRecords, withdrawRecord, countFacets]
  invalid_signature:
    status_class: 401
    retryable: false
    operations: [pushConnectorAPI, relayConnectorDelivery]
  invalid_subscription_configuration:
    status_class: 422
    retryable: false
    operations: [createSubscription, createSubscriptionVersion, migrateSubscriptionEvaluators, previewSubscription]
  invalid_window:
    status_class: 422
    retryable: false
    operations: [listConnectorPushStats, getMatchStats, getPluginCallStats, getReceivedStats, getSearchStats, getStepStats, getTopQueries]
  item_rejected:
    status_class: 422
    retryable: false
    operations: [challengeConnectorAPI, pushConnectorAPI, relayConnectorChallenge, relayConnectorDelivery]
  malformed_json:
    status_class: 400
    retryable: false
    operations: [activatePlugin, cancelOperation, changeConnectorSchedule, configureRetrieval, confirmUpload, createConnector, createCorpus, createSavedQuery, createSavedQueryVersion, createSubscription, createSubscriptionVersion, createUpload, deleteSavedQuery, deleteSubscription, disableConnector, pauseConnector, resumeConnector, disableSubscription, enableSubscription, ingestBatch, ingestRecord, migrateSubscriptionEvaluators, pauseOperation, previewSubscription, promoteVectorSpace, rebuildCorpusProjection, registerPlugin, renameSavedQuery, renameSubscription, replaceConnectorCredential, reprocessQuarantine, requestBackfill, requestConnectorRun, rerunOperation, resumeOperation, retireEvaluations, rollbackPipelinePlan, searchRecords, withdrawRecord, countFacets]
  method_not_allowed:
    status_class: 405
    retryable: false
    operations: [activatePlugin, cancelOperation, challengeConnectorAPI, changeConnectorSchedule, configureRetrieval, confirmUpload, createConnector, createConnectorToken, createCorpus, createSavedQuery, createSavedQueryVersion, createSubscription, createSubscriptionVersion, createUpload, deleteSavedQuery, deleteSubscription, disableConnector, pauseConnector, resumeConnector, disableSubscription, enableSubscription, getActivePipelinePlan, getBlob, getConnector, getCorpus, getDelivery, getDocumentTimeline, getEvaluationRetirement, getMatch, getMatchStats, getOperation, getPipelinePlan, getPluginCallStats, getPluginRegistration, getReceipt, getReceivedStats, getRecord, getSavedQuery, getSavedQueryVersion, getSearchStats, getStepStats, getSubscription, getSubscriptionVersion, getTopQueries, getUpload, getVersion, ingestBatch, ingestRecord, listActivePlugins, listAdminDocuments, listConnectorKinds, listConnectorPushStats, listConnectorTokens, listConnectors, listCorpora, listDeliveryAttempts, listEvaluationBacklog, listMatches, listPipelinePlans, listPluginRegistrations, listQuarantinedVersions, listRecords, countRecords, countFacets, listSearchProfiles, listSubscriptions, listVectorSpaces, migrateSubscriptionEvaluators, pauseOperation, pollChanges, previewSubscription, promoteVectorSpace, pushConnectorAPI, rebuildCorpusProjection, registerPlugin, relayConnectorChallenge, relayConnectorDelivery, renameSavedQuery, renameSubscription, replaceConnectorCredential, reprocessQuarantine, requestBackfill, requestConnectorRun, rerunOperation, resumeOperation, retireEvaluations, revokeConnectorToken, rollbackPipelinePlan, rotateConnectorToken, searchRecords, streamChanges, withdrawRecord]
  no_previous_plan:
    status_class: 409
    retryable: false
    operations: [rollbackPipelinePlan]
  not_evaluation_space:
    status_class: 422
    retryable: false
    operations: [promoteVectorSpace]
  not_found:
    status_class: 404
    retryable: false
    operations: [getCorpusStats, activatePlugin, cancelOperation, challengeConnectorAPI, changeConnectorSchedule, configureRetrieval, confirmUpload, createConnector, createConnectorToken, createCorpus, createSavedQuery, createSavedQueryVersion, createSubscription, createSubscriptionVersion, createUpload, deleteSavedQuery, deleteSubscription, disableConnector, pauseConnector, resumeConnector, disableSubscription, enableSubscription, getActivePipelinePlan, getBlob, getConnector, getCorpus, getDelivery, getDocumentTimeline, getEvaluationRetirement, getMatch, getMatchStats, getOperation, getPipelinePlan, getPluginCallStats, getPluginRegistration, getReceipt, getReceivedStats, getRecord, getSavedQuery, getSavedQueryVersion, getSearchStats, getStepStats, getSubscription, getSubscriptionVersion, getTopQueries, getUpload, getVersion, ingestBatch, ingestRecord, listActivePlugins, listAdminDocuments, listConnectorKinds, listConnectorPushStats, listConnectorTokens, listConnectors, listCorpora, listDeliveryAttempts, listEvaluationBacklog, listMatches, listPipelinePlans, listPluginRegistrations, listQuarantinedVersions, listRecords, countRecords, countFacets, listSearchProfiles, listSubscriptions, listVectorSpaces, migrateSubscriptionEvaluators, pauseOperation, pollChanges, previewSubscription, promoteVectorSpace, pushConnectorAPI, rebuildCorpusProjection, registerPlugin, relayConnectorChallenge, relayConnectorDelivery, renameSavedQuery, renameSubscription, replaceConnectorCredential, reprocessQuarantine, requestBackfill, requestConnectorRun, rerunOperation, resumeOperation, retireEvaluations, revokeConnectorToken, rollbackPipelinePlan, rotateConnectorToken, searchRecords, streamChanges, withdrawRecord]
  operation_not_terminal:
    status_class: 409
    retryable: false
    operations: [cancelOperation, pauseOperation, rerunOperation, resumeOperation]
  plugin_conflict:
    status_class: 409
    retryable: false
    operations: [activatePlugin, rollbackPipelinePlan]
  plugin_unreachable:
    status_class: 409
    retryable: false
    operations: [activatePlugin, rollbackPipelinePlan]
  push_replayed:
    status_class: 409
    retryable: false
    operations: [pushConnectorAPI, relayConnectorDelivery]
  query_too_long:
    status_class: 422
    retryable: false
    operations: [searchRecords]
  rebuild_required:
    status_class: 409
    retryable: false
    operations: [requestBackfill]
  registration_not_active:
    status_class: 409
    retryable: false
    operations: [requestBackfill, rerunOperation]
  registration_not_validated:
    status_class: 409
    retryable: false
    operations: [activatePlugin, rollbackPipelinePlan]
  reprocess_in_progress:
    status_class: 409
    retryable: false
    operations: [reprocessQuarantine, rerunOperation]
  request_too_large:
    status_class: 413
    retryable: false
    operations: [activatePlugin, cancelOperation, challengeConnectorAPI, changeConnectorSchedule, configureRetrieval, confirmUpload, createConnector, createCorpus, createSavedQuery, createSavedQueryVersion, createSubscription, createSubscriptionVersion, createUpload, deleteSavedQuery, deleteSubscription, disableConnector, pauseConnector, resumeConnector, disableSubscription, enableSubscription, ingestBatch, ingestRecord, migrateSubscriptionEvaluators, pauseOperation, previewSubscription, promoteVectorSpace, pushConnectorAPI, rebuildCorpusProjection, registerPlugin, relayConnectorChallenge, relayConnectorDelivery, renameSavedQuery, renameSubscription, replaceConnectorCredential, reprocessQuarantine, requestBackfill, requestConnectorRun, rerunOperation, resumeOperation, retireEvaluations, rollbackPipelinePlan, searchRecords, withdrawRecord, countFacets]
  reserved_idempotency_key:
    status_class: 422
    retryable: false
    operations: [ingestBatch, ingestRecord, withdrawRecord]
  retrieval_plugin_invalid:
    status_class: 502
    retryable: false
    operations: [searchRecords]
  saved_query_deleted:
    status_class: 409
    retryable: false
    operations: [createSavedQueryVersion, deleteSavedQuery, getSavedQuery, getSavedQueryVersion, renameSavedQuery]
  saved_query_in_use:
    status_class: 409
    retryable: false
    operations: [deleteSavedQuery]
  search_deadline_exceeded:
    status_class: 504
    retryable: false
    operations: [searchRecords]
  preview_deadline_exceeded:
    status_class: 504
    retryable: true
    operations: [previewSubscription]
  search_unavailable:
    status_class: 503
    retryable: true
    operations: [searchRecords]
  model_unavailable:
    status_class: 503
    retryable: true
    operations: [searchRecords]
  metadata_filter_unavailable:
    status_class: 422
    retryable: false
    operations: [searchRecords, listRecords, countFacets]
  filter_too_broad:
    status_class: 422
    retryable: false
    operations: [listRecords]
  source_filter_unavailable:
    status_class: 422
    retryable: false
    operations: [searchRecords]
  source_namespace_in_use:
    status_class: 409
    retryable: false
    operations: [createConnector]
  storage_unavailable:
    status_class: 503
    retryable: true
    operations: [activatePlugin, cancelOperation, configureRetrieval, confirmUpload, createCorpus, createSavedQuery, createSavedQueryVersion, createSubscription, createSubscriptionVersion, createUpload, deleteSavedQuery, deleteSubscription, disableSubscription, enableSubscription, getActivePipelinePlan, getBlob, listConnectorPushStats, getCorpus, getDelivery, getDocumentTimeline, getEvaluationRetirement, getMatch, getMatchStats, getOperation, getPipelinePlan, getPluginCallStats, getPluginRegistration, getReceivedStats, getSavedQuery, getSavedQueryVersion, getSearchStats, getStepStats, getSubscription, getSubscriptionVersion, getTopQueries, getUpload, listActivePlugins, listAdminDocuments, listCorpora, listDeliveryAttempts, listEvaluationBacklog, listMatches, listPipelinePlans, listPluginRegistrations, listQuarantinedVersions, listSubscriptions, migrateSubscriptionEvaluators, pauseOperation, previewSubscription, promoteVectorSpace, rebuildCorpusProjection, registerPlugin, renameSavedQuery, renameSubscription, reprocessQuarantine, requestBackfill, rerunOperation, resumeOperation, retireEvaluations, rollbackPipelinePlan]
  subscription_changed:
    status_class: 409
    retryable: false
    embedded: true
    operations: [migrateSubscriptionEvaluators]
  subscription_deleted:
    status_class: 409
    retryable: false
    operations: [createSubscriptionVersion, deleteSubscription, disableSubscription, enableSubscription, getSubscription, getSubscriptionVersion, renameSubscription]
  token_inactive:
    status_class: 409
    retryable: false
    operations: [rotateConnectorToken]
  tokens_unavailable:
    status_class: 503
    retryable: true
    response_code: connectors_unavailable
    operations: [challengeConnectorAPI, createConnectorToken, listConnectorTokens, pushConnectorAPI, revokeConnectorToken, rotateConnectorToken]
  unknown_destination:
    status_class: 422
    retryable: false
    operations: [createSubscription, createSubscriptionVersion, previewSubscription]
  unknown_saved_query:
    status_class: 422
    retryable: false
    operations: [createSubscription, createSubscriptionVersion, previewSubscription]
  unsupported_connector_kind:
    status_class: 422
    retryable: false
    operations: [changeConnectorSchedule, createConnector, replaceConnectorCredential]
  unsupported_content:
    status_class: 422
    retryable: false
    operations: [ingestBatch, ingestRecord, withdrawRecord]
  unsupported_evaluator:
    status_class: 422
    retryable: false
    operations: [createSubscription, createSubscriptionVersion, migrateSubscriptionEvaluators, previewSubscription]
  unsupported_media_type:
    status_class: 415
    retryable: false
    operations: [activatePlugin, cancelOperation, changeConnectorSchedule, configureRetrieval, confirmUpload, createConnector, createCorpus, createSavedQuery, createSavedQueryVersion, createSubscription, createSubscriptionVersion, createUpload, deleteSavedQuery, deleteSubscription, disableConnector, pauseConnector, resumeConnector, disableSubscription, enableSubscription, ingestBatch, ingestRecord, migrateSubscriptionEvaluators, pauseOperation, previewSubscription, promoteVectorSpace, rebuildCorpusProjection, registerPlugin, renameSavedQuery, renameSubscription, replaceConnectorCredential, reprocessQuarantine, requestBackfill, requestConnectorRun, rerunOperation, resumeOperation, retireEvaluations, rollbackPipelinePlan, searchRecords, withdrawRecord, countFacets]
  unsupported_operation_kind:
    status_class: 422
    retryable: false
    operations: [cancelOperation, pauseOperation, rerunOperation, resumeOperation]
  unsupported_profile:
    status_class: 422
    retryable: false
    operations: [configureRetrieval, createCorpus, createSavedQuery, createSavedQueryVersion, createSubscription, createSubscriptionVersion, previewSubscription, searchRecords]
  unsupported_search:
    status_class: 422
    retryable: false
    operations: [searchRecords]
  unverified_blob:
    status_class: 422
    retryable: false
    operations: [ingestBatch, ingestRecord, withdrawRecord]
# Existing HTTP aliases are routing metadata, not additional operations.
x-quivr-route-aliases:
  /v0/admin/plugins/: /v0/admin/plugins
paths:
  /v0/version:
    get:
      operationId: getBuildVersion
      summary: Read the running Quivr build
      description: Reports the distribution release, source revision and API and plugin engine compatibility versions. Any valid API key can read it; no database access is needed.
      responses:
        '200':
          description: The running build identity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildVersion'
        default:
          description: Structured error. 401 unauthenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-required-permissions: []
  /v0/records:
    post:
      operationId: ingestRecord
      description: Commit durable input, Receipt and dispatch intent before responding. Same key and canonical
        request returns same Receipt; changed request conflicts. A new source revision corrects the Record.
        All accepted/replayed submissions use 202, even when a replayed Receipt has resolved.
      responses:
        '202':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receipt'
        default:
          description: Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404
            absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503
            temporary failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestCommand'
      x-required-permissions:
      - content:write
    get:
      operationId: listRecords
      description: >-
        List authorized canonical Records from one or several Corpora. Without metadata
        predicates the catalog includes withdrawn Records. Metadata predicates require
        the current Version to be projected in the routed generation; withdrawn Records
        can disappear from filtered pages after projection purge or rebuild. Use the
        unfiltered catalog and change feed for complete resynchronization.
        Metadata equality and datetime-range pages use scoped indexes and bounded
        reads. A filter that exceeds the bounded read budget returns 422
        filter_too_broad with retryable false; narrow the metadata or acceptance-time
        range before sending another request. No partial page is returned.
        The default record_id order is ascending byte-wise ID order for resynchronization.
        accepted_at_desc orders by the current Version's acceptance time, newest first,
        then by Record ID descending for ties. A correction moves the Record when its
        replacement Version becomes current. Records without a current Version have no
        acceptance time; they appear last in unbounded date listings and are excluded by
        either time bound. Bounds also work with the default ID order. Equal bounds select
        an empty range; reversed bounds, malformed dates, duplicate or unknown parameters
        and unknown orders return 422 invalid_query.
        The opaque page cursor binds Corpus selection, authorization scope, order, time
        bounds and metadata predicates with their routed generations;
        changing any returns 409 cursor_scope_changed with resync_url. Repeat the same
        parameters for subsequent pages. Newer arrivals between pages do not shift the
        keyset or duplicate previously listed Records. Each page is an independent read,
        not a historical snapshot: concurrent corrections, withdrawals and readiness
        changes are reconciled through the change feed. Capture a start-now Change Cursor
        before scanning and consume changes as invalidations by rereading current resources.
        This route, relative to the API base, is the resync_url of catalog cursor errors.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordPage'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: corpus_id
        in: query
        required: false
        schema:
          type: string
          minLength: 1
      - name: corpus_ids
        in: query
        required: false
        description: Comma-separated selection of up to 16 distinct Corpora. Supply exactly one of corpus_id or corpus_ids.
        style: form
        explode: false
        schema:
          type: array
          minItems: 1
          maxItems: 16
          uniqueItems: true
          items:
            type: string
            minLength: 1
      - name: metadata
        in: query
        required: false
        description: JSON array of MetadataFilter predicates, at most 16. Applied before ordering and pagination to current Versions projected in the routed generation. Withdrawn Records can be omitted after projection purge or rebuild; use the unfiltered catalog for full resynchronization. Repeat on later pages. Filters require a metadata-capable generation; rebuild older Corpora first.
        schema:
          type: string
          maxLength: 262144
      - name: order
        in: query
        required: false
        schema:
          type: string
          enum: [record_id, accepted_at_desc]
          default: record_id
      - name: accepted_after
        in: query
        required: false
        description: Inclusive lower bound on the current Version's acceptance time. RFC 3339 with an offset and at most 9 fractional-second digits; clients convert local days into bounds. Quivr applies no time-zone rules.
        schema:
          type: string
          format: date-time
      - name: accepted_before
        in: query
        required: false
        description: Exclusive upper bound on the current Version's acceptance time. RFC 3339 with an offset and at most 9 fractional-second digits.
        schema:
          type: string
          format: date-time
      - name: page_cursor
        in: query
        required: false
        schema:
          type: string
          minLength: 1
      - name: limit
        in: query
        required: false
        description: The most items to return. An empty, non-integer or out-of-range value is 422 invalid_limit.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
      x-required-permissions:
      - content:read
  /v0/facets:
    post:
      operationId: countFacets
      description: >-
        Exact document counts for projected metadata fields across authorized Corpora.
        Uses content:read and validates every requested Corpus before resolving mappings,
        including Corpora excluded for missing facet or predicate fields. Exclusions use
        the same excluded_corpora shape and rules as search and metadata-filtered listing.
        All fields are aggregated in one read snapshot from current baseline-ready,
        non-quarantined Versions; withdrawn Records and Tombstones are excluded immediately.
        Each distinct array value counts a document once. Missing field values contribute
        no bucket. Common metadata.* fields and custom fields declared with the filter
        role are supported. Incompatible types across Corpora return 422 invalid_query.
        Existing projections without metadata require rebuilding (422 metadata_filter_unavailable).
        Each field returns at most its limit, selected by descending count then JSON value
        text in byte order for ties. UTC date buckets are then returned chronologically;
        empty date buckets are omitted. Histograms require day, month or year on datetime
        fields; interval on another type is invalid_query. Counts are independent of search
        and listing reads and can change with ingestion. No text query or ranking is applied.
        Each API process admits at most 8 active facet requests; excess work returns retryable
        503 content_unavailable with Retry-After: 1. Requests have a 25-second execution deadline.
        With accuracy fast, counts may instead come from each Corpus's stored snapshot, exact
        as of the response's as_of and refreshed in the background while it is read, when the
        request has no predicate or only whole UTC days of the single date field it counts;
        otherwise from an exact count that ends within about a second, or else estimates
        scaled from a uniform sample of the Corpora's Records, marked approximate with their
        sample_fraction. Exact responses carry neither as_of nor approximate.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FacetRequest'
      responses:
        '200':
          description: Bounded document counts and excluded Corpus explanations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FacetResponse'
        default:
          description: Structured error; malformed_json, invalid_schema, request_too_large, unsupported_media_type, invalid_query, forbidden, not_found, metadata_filter_unavailable or content_unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-required-permissions:
      - content:read
  /v0/corpora/{corpus_id}/stats:
    get:
      operationId: getCorpusStats
      description: >-
        Running eligible-document and catalog totals from transactional aggregates.
        Eligible documents have a current baseline-ready, non-quarantined Version and
        no withdrawal or tombstone. Catalog membership includes withdrawn and unready
        Record identities. Counts are independent of projection generations.
        All requested fields share one database snapshot at observed_at. complete=false
        and approximate=true mean historical initialization has not finished; partial
        zeros are not certified empty. Archived Corpora return 409 corpus_archived.
        Default reads return totals only. Include histogram and/or sources explicitly.
        History uses the CURRENT Version's acceptance time, stored in UTC hours; a
        correction moves its Record to the new hour. Day resolution groups UTC days.
        Local days can be reconstructed exactly only for whole-hour UTC offsets.
        Fractional-hour offsets require finer data and must not be labelled exact.
        History has no lifetime cutoff: each page covers at most 10000 consecutive
        buckets, with missing buckets zero only within its covered interval at observed_at
        when complete=true. Boundary days may be clipped by the requested time range.
        Consume histogram.next_page_cursor with histogram_cursor and repeat the original
        parameters. Sources use namespace plus trusted connector identity; historical
        and public submissions have connector_id unknown. Source counts are lifetime
        totals regardless of histogram bounds. Consume sources.next_page_cursor with
        sources_cursor. Each continuation is an independent snapshot; concurrent
        corrections can change earlier pages, so multiple pages are not one census.
        Cursors bind Corpus, authorization scope and every query option.
      parameters:
      - name: corpus_id
        in: path
        required: true
        schema: {type: string, minLength: 1}
      - name: include
        in: query
        description: Comma-separated histogram and/or sources; omit for totals only.
        schema: {type: string}
      - name: resolution
        in: query
        description: Histogram grouping. Requires include=histogram.
        schema: {type: string, enum: [day, hour], default: day}
      - name: accepted_after
        in: query
        description: Inclusive histogram bound, RFC 3339 at a UTC-hour boundary.
        schema: {type: string, format: date-time}
      - name: accepted_before
        in: query
        description: Exclusive histogram bound, RFC 3339 at a UTC-hour boundary.
        schema: {type: string, format: date-time}
      - name: histogram_cursor
        in: query
        schema: {type: string, minLength: 1}
      - name: sources_cursor
        in: query
        schema: {type: string, minLength: 1}
      - name: source_limit
        in: query
        schema: {type: integer, minimum: 1, maximum: 1000, default: 100}
      responses:
        '200':
          description: Totals and any requested series.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/CorpusStats'}
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Error'}
      x-required-permissions: [content:read]
  /v0/records/count:
    get:
      operationId: countRecords
      description: >-
        Count of one Corpus's authorized Records. Time-bounded counts are exact within
        a two-second query budget; larger windows return non-retryable 422
        record_count_too_broad and require narrower bounds. Unbounded counts probe at
        most 10001 identities: up to 10000 are exact, larger Corpora return stored
        catalog totals with approximate=true. complete=false means initialization
        has not finished; incomplete zeros must not be presented as empty. observed_at
        names the independent read snapshot. Includes withdrawn Records, as the listing does. Records
        without a current Version are counted only when neither bound is supplied.
        Uses content:read and the same Corpus scope as listRecords. This is an independent
        read, not a snapshot shared with listing pages. Equal bounds count zero; reversed
        bounds, malformed dates, duplicate or unknown parameters return 422 invalid_query.
      parameters:
      - name: corpus_id
        in: query
        required: true
        schema:
          type: string
          minLength: 1
      - name: accepted_after
        in: query
        required: false
        description: Inclusive lower bound on the current Version's acceptance time. RFC 3339 with an offset and at most 9 fractional-second digits; clients convert local days into bounds. Quivr applies no time-zone rules.
        schema:
          type: string
          format: date-time
      - name: accepted_before
        in: query
        required: false
        description: Exclusive upper bound on the current Version's acceptance time. RFC 3339 with an offset and at most 9 fractional-second digits.
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordCount'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-required-permissions:
      - content:read
  /v0/records/batch:
    post:
      operationId: ingestBatch
      description: 'Initial bound: 100 entries (413 batch_too_large), envelope 10 MiB (413 request_too_large).
        Validate envelope structure/size first, then each entry independently against IngestCommand,
        including wrong types or missing fields. Each raw entry is also held to the 1 MiB single-request
        bound (entry error entry_too_large), so the same entry bytes are never refused for size alone. HTTP
        200 carries Receipt or Error per entry, with the same error codes as single submission. Same ingestion
        family/key as single submission. Each entry has a fresh 5-second acceptance budget, bounded by
        an 8-second deadline for the whole batch, including envelope decoding and validation. Caller
        cancellation or an earlier caller deadline also applies. An entry that times out, and every
        remaining entry after the batch deadline, returns retryable content_unavailable. Retry with
        the same entry keys to recover the original Receipts. If the envelope cannot be read before
        the deadline, HTTP 503 returns retryable content_unavailable without attempting entries.
        Reuse entry keys after unknown transport outcomes.'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResult'
        default:
          description: Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404
            absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503
            temporary failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      x-required-permissions:
      - content:write
  /v0/records/withdrawals:
    post:
      operationId: withdrawRecord
      description: Durably commit withdrawal and Receipt before responding. Terminal identity fence, including
        before first materialization; no physical purge and no cascade. Uses a distinct withdrawal route
        family.
      responses:
        '202':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receipt'
        default:
          description: Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404
            absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503
            temporary failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawalCommand'
      x-required-permissions:
      - content:write
  /v0/records/{record_id}:
    get:
      operationId: getRecord
      description: Authorized canonical currentness and withdrawal view.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Record'
        default:
          description: Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404
            absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503
            temporary failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: record_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      x-required-permissions:
      - content:read
  /v0/records/{record_id}/versions/{version_id}:
    get:
      operationId: getVersion
      description: Authorized immutable source Manifest plus separate live availability and relation expansion.
        Available links supply current eligible target Record and Version IDs; unavailable links reveal
        no resolved target IDs or absence/access reason. Historical lookup grants no new rights.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Version'
        default:
          description: Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404
            absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503
            temporary failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: record_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: version_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      x-required-permissions:
      - content:read
  /v0/ingestion-receipts/{receipt_id}:
    get:
      operationId: getReceipt
      description: Return outcome and separately authorized linked availability/diagnostics. Omit unavailable
        linked content rather than bypassing rights through the Receipt. Linked Version/Record details
        require current content:read permission and target Corpus authorization.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receipt'
        default:
          description: Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404
            absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503
            temporary failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: receipt_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      x-required-permissions:
      - content:read
  /v0/uploads:
    post:
      operationId: createUpload
      description: 'Create a transfer session with a single presigned PUT URL, required headers and expiry.
        Initial limits: 1 GiB Blob, configurable; oversized uploads are rejected before a session is issued.'
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upload'
        default:
          description: Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404
            absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503
            temporary failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadRequest'
      x-required-permissions:
      - blobs:write
  /v0/uploads/{upload_id}/confirm:
    post:
      operationId: confirmUpload
      description: Start or observe checksum/size verification; SDK polls until verified before referencing
        the Blob in ingestion. Confirmation is repeatable for this session.
      responses:
        '202':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upload'
        default:
          description: Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404
            absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503
            temporary failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: upload_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      x-required-permissions:
      - blobs:write
  /v0/uploads/{upload_id}:
    get:
      operationId: getUpload
      description: Observe upload verification independently of Ingestion Receipt.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upload'
        default:
          description: Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404
            absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503
            temporary failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: upload_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      x-required-permissions:
      - blobs:read
  /v0/blobs/{blob_id}:
    get:
      operationId: getBlob
      description: Inspect verified Blob metadata within authorized Organization scope; ID possession
        does not grant access.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Blob'
        default:
          description: Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404
            absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503
            temporary failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: blob_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      x-required-permissions:
      - blobs:read
  /v0/operations/{operation_id}:
    get:
      operationId: getOperation
      description: Follow administrative progress. Corpus Operations require operations:read and matching Corpus grants. vector_space_promotion, plugin_activation and plugin_rollback require plugins:admin in the Organization that requested them; they carry admin and have no corpus_id.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        default:
          description: Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404
            absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503
            temporary failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: operation_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      x-required-permissions: []
      x-conditional-permissions:
        corpus_operations: [operations:read]
        admin_operations: [plugins:admin]
  /v0/corpora:
    post:
      operationId: createCorpus
      description: Explicit Corpus creation. Same creation route-family key and canonical request replays
        the same Corpus. Requires corpora:write.
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Corpus'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CorpusRequest'
      x-required-permissions:
      - corpora:write
    get:
      operationId: listCorpora
      description: Authorized Corpora only. Opaque page cursor bound to action/filter/scope; not a Change
        Cursor or a Record page cursor (either is 422 invalid_cursor).
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CorpusPage'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: page_cursor
        in: query
        required: false
        schema:
          type: string
          minLength: 1
      - name: limit
        in: query
        required: false
        description: The most items to return. An empty, non-integer or out-of-range value is 422 invalid_limit.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
      - name: include_archived
        in: query
        required: false
        description: Include archived corpora; false by default. Bound into the page cursor.
        schema:
          type: boolean
          default: false
      x-required-permissions:
      - corpora:read
  /v0/corpora/{corpus_id}:
    get:
      operationId: getCorpus
      description: Read effective resolved configuration.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Corpus'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: corpus_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      x-required-permissions:
      - corpora:read
    patch:
      operationId: renameCorpus
      description: Rename an authorized corpus. Does not change its identity or content. Requires a separate administrative grant.
      parameters:
      - name: corpus_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      x-required-permissions: [corpora:rename]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Corpus'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CorpusRenameRequest'
  /v0/corpora/{corpus_id}/archive:
    post:
      operationId: archiveCorpus
      description: Reversibly hide a corpus from default listings, search, catalog, change feed and connector polling. Explicitly scoped search, catalog and feed requests return 409 corpus_archived; direct record, version and document-timeline reads return 404 not_found until restoration. Keeps canonical data and connector enabled state.
      parameters:
      - name: corpus_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      x-required-permissions: [corpora:archive]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Corpus'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/corpora/{corpus_id}/unarchive:
    post:
      operationId: unarchiveCorpus
      description: Restore an archived corpus and make its retained data visible again.
      parameters:
      - name: corpus_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      x-required-permissions: [corpora:archive]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Corpus'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/corpora/{corpus_id}/retrieval:
    put:
      operationId: configureRetrieval
      description: Resolve mapping and schedule a new immutable Projection Generation through a
        retrieval_configuration Operation (202 with Location). Existing active config remains in effect,
        and is what getCorpus returns, until validated cutover; the Operation reports the pending
        config's progress and outcome but not its content. A newer accepted config supersedes older pending ones, and a generation
        pinned to an older config than the effective one fails with retrieval_configuration_superseded
        instead of reverting it. Same key and canonical request replay the Operation; a changed request
        is 409 idempotency_conflict. Does not require a separate per-Corpus physical collection.
      responses:
        '202':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: corpus_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigUpdate'
      x-required-permissions:
      - corpora:write
      - operations:write
  /v0/changes:
    get:
      operationId: pollChanges
      description: Same durable journal as SSE. Every durable event has one identity and appears exactly
        once in a forward cursor traversal, in stable order with per-Record order preserved. Concurrent
        writes to different Records need not appear in exact commit order. Reusing an older cursor can
        redeliver events. Without cursor, return empty items and an exact start-now cursor, excluding
        already committed changes while retaining then-in-flight writes. Readers advance only through
        a safe published prefix; aborted allocations may leave gaps. In healthy parallel mode, publication
        delay is bounded by the longest configured engine transaction timeout (30 seconds by default)
        plus two 100 ms publisher polls. Outside long-running or prepared transactions and database
        unavailability can delay publication; readers fail closed rather than skip late commits. Cursor binds Organization, Corpus filter and authorization scope.
        Expiry is 410 cursor_expired with resync_url, never silent reset; changed scope/filter is 409
        cursor_scope_changed with resync_url. resync_url is the API-relative Record catalog route for
        the Corpus (/v0/records?corpus_id=...). next_cursor advances over scanned events even when none are visible. Public
        events are invalidations; reread current state, do not replay historical content into a current
        mirror.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangePage'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: cursor
        in: query
        required: false
        schema:
          type: string
          minLength: 1
      - name: corpus_id
        in: query
        required: true
        schema:
          type: string
          minLength: 1
      - name: limit
        in: query
        required: false
        description: The most items to return. An empty, non-integer or out-of-range value is 422 invalid_limit.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
      x-required-permissions:
      - changes:read
  /v0/changes/stream:
    get:
      operationId: streamChanges
      description: 'SSE over the same safe published journal with stable per-Record ordering and exact start-now
        semantics as polling. Cross-Record commit order is not guaranteed; resuming an older cursor can
        redeliver an event. Last-Event-ID takes precedence over query cursor on reconnect.
        id is an opaque Change Cursor; data.event_id is deduplication identity. Named change events carry
        ChangeEvent JSON. checkpoint events carry a cursor when no visible event is emitted, including
        initial start-now checkpoint. Resume cursor expires or scope changes: before headers use HTTP
        410/409; after headers send stream_error with Error JSON then close, without advancing id. Use
        authenticated streaming fetch/http client. See contract for checkpoint framing and resync.'
      responses:
        '200':
          description: Successful response
          content:
            text/event-stream:
              schema:
                type: string
              example: 'id: opaque-cursor

                event: change

                data: {"event_id":"event_1","type":"record.searchable","schema_version":"1","occurred_at":"2026-09-14T12:00:00Z","resource":{"kind":"record","id":"record_1","corpus_id":"corpus_1"},"cursor":"opaque-cursor"}


                '
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: cursor
        in: query
        required: false
        schema:
          type: string
          minLength: 1
      - name: corpus_id
        in: query
        required: true
        schema:
          type: string
          minLength: 1
      - name: Last-Event-ID
        in: header
        required: false
        schema:
          type: string
          minLength: 1
      x-required-permissions:
      - changes:read
  /v0/operations/{operation_id}/cancel:
    post:
      operationId: cancelOperation
      description: Idempotent cancellation request; does not undo committed effects. Terminal operation
        returns its existing state. A racing completion may win. Cancellation becomes terminal only after
        work stops safely; no partial active projection cutover.
      responses:
        '202':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: operation_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequest'
      x-required-permissions:
      - operations:write
  /v0/operations/{operation_id}/rerun:
    post:
      operationId: rerunOperation
      description: Only terminal Operations can be intentionally rerun; otherwise 409 operation_not_terminal.
        A backfill rerun while another backfill of its Corpus has not finished is 409 backfill_in_progress,
        and one whose ingestion plugin left the active plan is 409 registration_not_active.
        A quarantine_reprocess rerun takes the Versions still stuck in its source's scope, with the plan
        active now and its source's dry run as estimate; while another reprocess of its Corpus has not
        finished it is 409 reprocess_in_progress. A request key replays the same new linked Operation. Revalidate current scope and command eligibility;
        completed effects remain subject to domain idempotency.
      responses:
        '202':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: operation_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequest'
      x-required-permissions:
      - operations:write
  /v0/operations/{operation_id}/pause:
    post:
      operationId: pauseOperation
      description: Holds a backfill until it is resumed. A queued or running backfill becomes paused and makes
        no progress, keeping its checkpoint and the Pipeline Plan it is pinned to. Nothing committed is
        undone. Any other state is returned unchanged, so repeating the request is safe. Only backfills
        pause.
      responses:
        '202':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        default:
          description: Structured error; 403 without operations:write or the permission of the command
            that created the Operation (plugins:admin for a backfill), 404 unknown Operation, 422
            unsupported_operation_kind for a kind that cannot pause, 503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: operation_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequest'
      x-required-permissions:
      - operations:write
  /v0/operations/{operation_id}/resume:
    post:
      operationId: resumeOperation
      description: Lets a paused backfill continue from its checkpoint, on the Pipeline Plan it is pinned to.
        Any other state is returned unchanged, so repeating the request is safe. Only backfills resume.
      responses:
        '202':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        default:
          description: Structured error; 403 without operations:write or the permission of the command
            that created the Operation (plugins:admin for a backfill), 404 unknown Operation, 422
            unsupported_operation_kind for a kind that cannot pause, 503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: operation_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequest'
      x-required-permissions:
      - operations:write
  /v0/saved-queries:
    post:
      operationId: createSavedQuery
      description: Persist definition and first immutable version. Replay same key/request returns same
        IDs; conflict on changed request. Query creation alone evaluates nothing.
      x-required-permissions:
      - monitoring:write
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedQuery'
        default:
          description: Structured error. Existing /v0 authentication, scope, pagination and idempotency
            semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedQueryCreate'
  /v0/saved-queries/{saved_query_id}:
    get:
      operationId: getSavedQuery
      description: Authorized current query view.
      x-required-permissions:
      - monitoring:read
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedQuery'
        default:
          description: Structured error. Existing /v0 authentication, scope, pagination and idempotency
            semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: saved_query_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
  /v0/saved-queries/{saved_query_id}/versions/{version_id}:
    get:
      operationId: getSavedQueryVersion
      description: Read any immutable Version of the Saved Query, current or earlier, such as the one
        a Subscription Version or Match pins. The key must grant the Corpora of the Saved Query's current
        Version and of this Version. A deleted Saved Query's Versions stay readable.
      x-required-permissions:
      - monitoring:read
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedQueryVersion'
        default:
          description: Structured error. Existing /v0 authentication, scope, pagination and idempotency
            semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: saved_query_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: version_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
  /v0/saved-queries/{saved_query_id}/versions:
    post:
      operationId: createSavedQueryVersion
      description: Edit a Saved Query by committing a new immutable Version that becomes its current
        Version, with saved_query.updated in every Corpus of the previous and new scope. Subscriptions
        keep the Version they pin; a new Subscription Version moves one. The key must grant every Corpus
        of the current and new definitions. Replay of the same key and request returns the same Version;
        a changed request is 409 idempotency_conflict. A deleted Saved Query is 409 saved_query_deleted.
      x-required-permissions:
      - monitoring:write
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedQueryVersion'
        default:
          description: Structured error. Existing /v0 authentication, scope, pagination and idempotency
            semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: saved_query_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedQueryVersionCreate'
  /v0/saved-queries/{saved_query_id}/delete:
    post:
      operationId: deleteSavedQuery
      description: Logically delete a Saved Query that no Subscription which is not deleted belongs
        to (409 saved_query_in_use otherwise), with saved_query.deleted per Corpus. It and its Versions
        stay readable with deleted true; it gets no new Version or Subscription. Repeat is idempotent
        and commits no event.
      x-required-permissions:
      - monitoring:write
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedQuery'
        default:
          description: Structured error. Existing /v0 authentication, scope, pagination and idempotency
            semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: saved_query_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequest'
  /v0/saved-queries/{saved_query_id}/rename:
    post:
      operationId: renameSavedQuery
      description: Change the display name of a Saved Query. The name belongs to the Saved Query, not
        to its immutable Versions, so no Version is created and no Subscription moves. A new name commits
        saved_query.renamed in every Corpus of the current Version; the same name commits nothing.
        Replay of the same key and request returns the Saved Query; a changed request is 409
        idempotency_conflict. A deleted Saved Query is 409 saved_query_deleted.
      x-required-permissions:
      - monitoring:write
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedQuery'
        default:
          description: Structured error. Existing /v0 authentication, scope, pagination and idempotency
            semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: saved_query_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenameRequest'
  /v0/subscriptions:
    get:
      operationId: listSubscriptions
      description: Active (enabled, not deleted) Subscriptions of one Subscription Owner, or the global
        ones with owner=none, in stable Subscription ID order. Lists only Subscriptions the key sees,
        like every Subscription read. Stable keyset page cursor bound to the owner filter and key scope,
        not a Change Cursor. Quivr applies no per-owner rule; a layer above can use this listing to enforce
        its own.
      x-required-permissions:
      - monitoring:read
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionPage'
        default:
          description: Structured error. Existing /v0 authentication, scope, pagination and idempotency
            semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: owner
        in: query
        required: true
        description: A Subscription Owner, or none for global Subscriptions. Without it the request is 422
          invalid_query; an empty or refused owner is 422 invalid_owner, as on creation.
        schema:
          type: string
          minLength: 1
          maxLength: 128
      - name: page_cursor
        in: query
        schema:
          type: string
          minLength: 1
      - name: limit
        in: query
        description: The most items to return. An empty, non-integer or out-of-range value is 422 invalid_limit.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
    post:
      operationId: createSubscription
      description: Atomically create enabled Subscription/Version and activation boundary in the durable
        journal. Evaluate future eligible transitions, not existing history. Replay same key/request returns
        same identity and does not reactivate a disabled Subscription. The evaluator must be installed (422
        unsupported_evaluator); the pinned Saved Query Version expression and the evaluator configuration
        must satisfy the evaluator's declared schemas (422 invalid_expression with field /saved_query_version_id,
        or invalid_subscription_configuration with field /evaluator/configuration/...; message names the
        first schema issue).
      x-required-permissions:
      - monitoring:write
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        default:
          description: Structured error. Existing /v0 authentication, scope, pagination and idempotency
            semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionCreate'
  /v0/subscriptions/{subscription_id}:
    get:
      operationId: getSubscription
      description: Read enabled state and pinned current configuration.
      x-required-permissions:
      - monitoring:read
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        default:
          description: Structured error. Existing /v0 authentication, scope, pagination and idempotency
            semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
  /v0/subscriptions/{subscription_id}/versions/{version_id}:
    get:
      operationId: getSubscriptionVersion
      description: Read any immutable Version of the Subscription, current or earlier, such as the one
        a historical Match names. As for every read of a Subscription, its Matches and Deliveries, the
        key must grant every Corpus any of its Versions pinned. A deleted Subscription's Versions stay
        readable.
      x-required-permissions:
      - monitoring:read
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionVersion'
        default:
          description: Structured error. Existing /v0 authentication, scope, pagination and idempotency
            semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: version_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
  /v0/subscriptions/{subscription_id}/versions:
    post:
      operationId: createSubscriptionVersion
      description: Edit a Subscription by committing a new immutable Version that becomes current. It
        pins the current Version of the Subscription's own Saved Query (422 unknown_saved_query
        otherwise), an evaluator and a destination. It takes effect from its commit, recorded as its
        activation position with subscription.updated in every Corpus of the previous and new scope.
        Each later change is judged by the new Version, each earlier one by the Version effective
        before it. Nothing is backfilled and Matches keep the Version that produced them. Enabled
        state is unchanged. The evaluator, expression and configuration are checked as on creation
        (422 unsupported_evaluator, invalid_expression or invalid_subscription_configuration). Replay of the same key and request returns the same Version; a changed
        request is 409 idempotency_conflict. A deleted Subscription is 409 subscription_deleted.
      x-required-permissions:
      - monitoring:write
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionVersion'
        default:
          description: Structured error. Existing /v0 authentication, scope, pagination and idempotency
            semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionVersionCreate'
  /v0/subscriptions/{subscription_id}/delete:
    post:
      operationId: deleteSubscription
      description: Logically delete a Subscription for good, with subscription.deleted per Corpus.
        It is also disabled, with every disable guarantee - no new evaluation commit and no new
        Delivery Attempt admission (reason subscription_deleted); an in-flight attempt may complete.
        As for a disabled Subscription, a match.withdrawn notice for one of its Matches is still
        committed with its pending Delivery, which is never attempted. The Subscription, its Versions,
        Matches and Deliveries stay readable with deleted true. Enable or edit is then 409
        subscription_deleted. Repeat is idempotent and commits no event.
      x-required-permissions:
      - monitoring:write
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        default:
          description: Structured error. Existing /v0 authentication, scope, pagination and idempotency
            semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequest'
  /v0/subscriptions/{subscription_id}/disable:
    post:
      operationId: disableSubscription
      description: Commit disable. Block new evaluation commits and new Delivery Attempt admissions, including
        queued retries and update notices. In-flight attempts may complete. A match.withdrawn notice for
        a Match of this Subscription is still committed with its pending Delivery, which makes no attempt
        until re-enable. Repeat is idempotent; history remains.
      x-required-permissions:
      - monitoring:write
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        default:
          description: Structured error. Existing /v0 authentication, scope, pagination and idempotency
            semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequest'
  /v0/subscriptions/{subscription_id}/enable:
    post:
      operationId: enableSubscription
      description: Commit re-enable of a disabled Subscription on the same Subscription Version. Evaluation
        resumes from this commit; changes made while disabled are never evaluated. Pending Deliveries
        parked by the disable become eligible again under the usual admission checks and keep their
        delivery window, except a match.withdrawn notice committed while disabled, whose window starts
        at this re-enable. Enabling an enabled Subscription, or repeating the request, is idempotent and
        commits no event. A deleted Subscription is 409 subscription_deleted.
      x-required-permissions:
      - monitoring:write
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        default:
          description: Structured error. Existing /v0 authentication, scope, pagination and idempotency
            semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequest'
  /v0/subscription-previews:
    post:
      operationId: previewSubscription
      description: Dry run of a proposed Subscription. Runs the evaluator on the most recently accepted
        current eligible Record Versions of the Saved Query's Corpora, newest first, and returns what it
        would have matched. Nothing is written - no Saved Query, Subscription, Match, Delivery or event -
        and it is not idempotent. The Saved Query is an inline definition or an existing Saved Query
        Version; the pair is validated as at Subscription creation (422 unsupported_evaluator,
        invalid_expression, invalid_subscription_configuration). Each Record Version costs one evaluator
        call, sent with the synthetic Subscription reference preview. At most limit Record Versions
        (1 to 50, default 20) are judged, within a four-second budget including preparation and storage
        reads; those still undecided
        when it runs out are left out and complete is false. An evaluator that cannot be reached or
        reports a transient failure fails the preview with 503 evaluator_unavailable, and one that
        refuses or breaks an evaluation with 502 evaluator_error. A deadline during preparation or
        an earlier caller deadline returns retryable 504 preview_deadline_exceeded. A storage failure
        remains 503 storage_unavailable. Quivr applies no rate or cost rule; a
        layer above can limit who previews and how often.
      x-required-permissions:
      - monitoring:write
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionPreview'
        default:
          description: Structured error. Existing /v0 authentication and scope semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionPreviewRequest'
  /v0/subscriptions/{subscription_id}/rename:
    post:
      operationId: renameSubscription
      description: Change the display name of a Subscription. The name belongs to the Subscription, not
        to its immutable Versions, so no Version is created, evaluation and enabled state are unchanged,
        and its Matches and Deliveries stay attached. A new name commits subscription.renamed in every
        Corpus of the current Version; the same name commits nothing. Replay of the same key and
        request returns the Subscription; a changed request is 409 idempotency_conflict. A deleted
        Subscription is 409 subscription_deleted.
      x-required-permissions:
      - monitoring:write
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        default:
          description: Structured error. Existing /v0 authentication, scope, pagination and idempotency
            semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenameRequest'
  /v0/matches:
    get:
      operationId: listMatches
      description: Authorized historical Matches for a Subscription. Stable keyset page cursor, not a
        Change Cursor. Absence of a Match does not distinguish an evaluator still working from a negative
        result. A page containing evidence reclaimed by history_retention.alert_detail returns 410
        evidence_expired, retryable=false, with resync_url to explicitly resume after the expired Match.
        Resuming accepts a lost history interval; export evidence before retention expires if needed.
        Successful pages retain the original evidence and response shape.
      x-required-permissions:
      - monitoring:read
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchPage'
        default:
          description: Structured error. Existing /v0 authentication, scope, pagination and idempotency
            semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: subscription_id
        in: query
        required: true
        schema:
          type: string
          minLength: 1
      - name: page_cursor
        in: query
        schema:
          type: string
          minLength: 1
      - name: limit
        in: query
        description: The most items to return. An empty, non-integer or out-of-range value is 422 invalid_limit.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
  /v0/matches/{match_id}:
    get:
      operationId: getMatch
      description: Authorized historical positive result, explanation and provenance. Recheck current
        access to Subscription and content; disabled state alone does not erase history. Historical content
        retention remains separate from search eligibility. After history_retention.alert_detail reclaims
        evidence, this read returns 410 evidence_expired, retryable=false. Retained identity facts still
        prevent duplicate alerts and link corrections. Successful reads return the original immutable
        evidence with the existing response shape.
      x-required-permissions:
      - monitoring:read
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Match'
        default:
          description: Structured error. Existing /v0 authentication, scope, pagination and idempotency
            semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: match_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
  /v0/deliveries/{delivery_id}:
    get:
      operationId: getDelivery
      description: Read logical notification status and current admission view. Rights on the referenced
        Subscription/Corpus are still required for withdrawal-notice metadata.
      x-required-permissions:
      - monitoring:read
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Delivery'
        default:
          description: Structured error. Existing /v0 authentication, scope, pagination and idempotency
            semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: delivery_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
  /v0/deliveries/{delivery_id}/attempts:
    get:
      operationId: listDeliveryAttempts
      description: Paginated append-only transport history, without secrets or receiver bodies.
      x-required-permissions:
      - monitoring:read
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryAttemptPage'
        default:
          description: Structured error. Existing /v0 authentication, scope, pagination and idempotency
            semantics apply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: delivery_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: page_cursor
        in: query
        schema:
          type: string
          minLength: 1
      - name: limit
        in: query
        description: The most items to return. An empty, non-integer or out-of-range value is 422 invalid_limit.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
  /v0/connectors:
    post:
      operationId: createConnector
      description: Create a Connector Instance bound to exactly one authorized Corpus and one Source Namespace.
        Kind-specific config and credential secret are validated against the kind's JSON Schema (see listConnectorKinds); a failure is 422 invalid_config or invalid_credential with field pointing at the offending member. Replaying
        the same idempotency key and request returns the same instance (without re-enabling a disabled one);
        a different request under the same key is 409 idempotency_conflict. Another enabled instance on the
        same Corpus and Source Namespace is 409 source_namespace_in_use. The interval defaults per kind and
        is refused below the deployment floor (30 s by default) with 422 invalid_interval. Deposited
        credentials are write-only and never returned. A deployment without a credential key refuses any
        request carrying a credential with 503 credentials_unavailable (retryable false) before storing or
        digesting it; instances without a credential are unaffected. Commits connector.created in the change
        feed.
      x-required-permissions:
      - connectors:write
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connector'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectorCreate'
    get:
      operationId: listConnectors
      description: Connector Instances of authorized Corpora, optionally filtered to one Corpus, in stable
        identifier order. Opaque page cursor bound to filter and scope; not a Change Cursor or another
        list page cursor (422 invalid_cursor).
      x-required-permissions:
      - connectors:read
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorPage'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: corpus_id
        in: query
        required: false
        schema:
          type: string
          minLength: 1
      - name: page_cursor
        in: query
        required: false
        schema:
          type: string
          minLength: 1
      - name: limit
        in: query
        required: false
        description: The most items to return. An empty, non-integer or out-of-range value is 422 invalid_limit.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
  /v0/connectors/{connector_id}/tokens:
    parameters:
    - name: connector_id
      in: path
      required: true
      schema: {type: string, minLength: 1}
    post:
      operationId: createConnectorToken
      summary: Issue a source-scoped push token
      description: >-
        Requires connectors:admin on the instance's Organization and Corpus. Issue a random
        bearer token for this instance's instance_token routes only (Plugin API 0.12).
        The secret is shown once in this response with Cache-Control no-store; only its SHA-256
        hash and display metadata are stored. Issuance is not replayable. If the response is
        lost, list tokens, revoke the lost token and issue another. Disabled instances refuse
        issuance with 409 connector_disabled. No request body is needed.
      x-required-permissions: [connectors:admin]
      responses:
        '201':
          description: New token with its one-time bearer secret.
          headers:
            Cache-Control:
              schema: {type: string, enum: [no-store]}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ConnectorTokenCreated'}
        default:
          description: JSON Error envelope; 401 unauthenticated, 403 without admin permission, 404 out of scope, 409 disabled, 503 unavailable.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Error'}
    get:
      operationId: listConnectorTokens
      summary: List push token metadata
      description: >-
        Requires connectors:admin on the instance's Organization and Corpus. Returns metadata
        only, including expired or revoked tokens, never secrets or hashes. Pages are ordered
        by token_id; next_after is the next page's after value. Disabled instances remain readable.
      x-required-permissions: [connectors:admin]
      parameters:
      - name: after
        in: query
        schema: {type: string, maxLength: 128}
      - name: limit
        in: query
        schema: {type: integer, minimum: 1, maximum: 100, default: 100}
      responses:
        '200':
          description: Token metadata page.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ConnectorTokenList'}
        default:
          description: JSON Error envelope; 401 unauthenticated, 403 without admin permission, 404 out of scope, 422 invalid pagination, 503 unavailable.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Error'}
  /v0/connectors/{connector_id}/tokens/{token_id}/rotate:
    parameters:
    - name: connector_id
      in: path
      required: true
      schema: {type: string, minLength: 1}
    - name: token_id
      in: path
      required: true
      schema: {type: string, minLength: 1}
    post:
      operationId: rotateConnectorToken
      summary: Replace a push token with five minutes of overlap
      description: >-
        Requires connectors:admin on the instance's Organization and Corpus. Atomically issue a
        new token and mark this token rotated, valid for exactly five more minutes. The replacement
        has a new token_id and its secret is shown once with Cache-Control no-store. A revoked or
        already-rotated token is 409 token_inactive; repeating rotation cannot extend the overlap
        or reveal a secret again. Disabled instances are 409 connector_disabled. Revocation can
        cut the overlap short. No request body is needed; a lost response requires fresh issuance.
      x-required-permissions: [connectors:admin]
      responses:
        '201':
          description: Replacement token with its one-time bearer secret.
          headers:
            Cache-Control:
              schema: {type: string, enum: [no-store]}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ConnectorTokenCreated'}
        default:
          description: JSON Error envelope; 401 unauthenticated, 403 without admin permission, 404 unknown or foreign token, 409 inactive or disabled, 503 unavailable.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Error'}
  /v0/connectors/{connector_id}/tokens/{token_id}:
    parameters:
    - name: connector_id
      in: path
      required: true
      schema: {type: string, minLength: 1}
    - name: token_id
      in: path
      required: true
      schema: {type: string, minLength: 1}
    delete:
      operationId: revokeConnectorToken
      summary: Revoke a push token immediately
      description: >-
        Requires connectors:admin on the instance's Organization and Corpus. Revoke this token,
        even during rotation overlap or after the instance is disabled. Every authentication
        checks durable validity without a cache, so new authentications after the commit fail
        immediately; already admitted deliveries may finish. Revocation is idempotent and
        returns metadata only. Revoking an old token does not revoke its replacement; revoke
        each token_id that should lose access. No request body is needed.
      x-required-permissions: [connectors:admin]
      responses:
        '200':
          description: Revoked token metadata, never a secret.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ConnectorToken'}
        default:
          description: JSON Error envelope; 401 unauthenticated, 403 without admin permission, 404 unknown or foreign token, 503 unavailable.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Error'}
  /v0/connectors/{connector_id}/api/{path}:
    parameters:
    - name: Idempotency-Key
      in: header
      required: false
      description: >-
        Optional opaque key of 1–256 bytes, scoped to the instance. Authorized requests
        replay the first completed plugin/ingestion answer within the deployment TTL for quivr_key and instance_token routes
        (default 24h), without calling the plugin or charging another rate token.
        Authentication, route/body validation, IP and rate refusals do not reserve keys.
        Reusing a key on another declared route still replays its original answer.
      schema: {type: string, minLength: 1, maxLength: 256}
    - name: connector_id
      in: path
      required: true
      schema: {type: string}
    - name: path
      in: path
      required: true
      description: The declared relative route path, including any nested segments and filled template values.
      schema: {type: string, maxLength: 8192}
    post:
      operationId: pushConnectorAPI
      security: [{ApiKey: []}, {InstanceToken: []}, {}]
      x-quivr-plugin-response: {header: Quivr-Response-Origin, value: plugin, statuses: [4XX]}
      summary: Push data to a declared source route
      description: >-
        Resolve a named POST route from the instance kind's manifest (Plugin API 0.11; instance tokens and signatures since 0.12).
        For auth quivr_key, requires a Quivr bearer key with connector:push on the instance's Corpus and Organization,
        checked before any plugin call. For auth instance_token, requires this instance’s bearer token;
        Quivr keys and other instances’ tokens are refused with 401 invalid_instance_token.
        Missing or invalid key is 401; missing action 403;
        out-of-scope, disabled or unknown instance and undeclared path 404; undeclared method 405
        with Allow. JSON body is bounded to 1 MiB and the query to 8192 bytes. Malformed JSON is
        400; a request_schema mismatch is 422. Up to 64 bounded headers are relayed without
        Authorization, Cookie or hop-by-hop headers. The plugin and ingestion stage is bounded to 9 seconds; audit persistence adds at most 2 seconds.
        Accepted items use normal ingestion idempotency and return 202 with receipts in item order,
        including withdrawals; the accepted plugin answer is replaced. An empty delivery returns
        an empty receipts array. A rejected item returns 422 item_rejected; other items may already
        be accepted, so retrying their stable revisions replays the same receipts. Transient failures
        return 503 with Retry-After. Engine-generated failures return the JSON Error envelope
        with the engine's error code and no Quivr-Response-Origin header.
        A refused plugin verdict returns the plugin's 4xx status, content type and body unchanged,
        marked with Quivr-Response-Origin: plugin. That header selects the plugin-defined response
        variant (x-quivr-plugin-response), even when its status overlaps an engine response;
        the engine response schemas below apply to responses without that header.
        Per-instance token buckets use the deployment default unless push_policy overrides it.
        Excess requests return 429 with Retry-After (integer seconds) before plugin invocation;
        callers outside push_policy.allowed_cidrs return 403 ip_not_allowed. Only explicitly
        trusted proxy networks may supply X-Forwarded-For addresses. Every attempt for an
        existing instance commits connector.push.received (2xx) or connector.push.refused
        and per-instance admin counters before the response is sent. Audit storage failure
        returns 503. Legacy routes without declared signature ingress keep their existing behavior.
        For auth signature, the plugin verifies the provider signature; the engine checks one nonempty
        signature header and optional signed Unix-seconds timestamp within the declared window
        (401 invalid_signature). PostgreSQL reserves signature and Idempotency-Key fingerprints per
        instance for window_seconds before the plugin call; duplicate keys return 409 push_replayed.
        Signature routes bypass the response cache: once replay reservations expire, the plugin verifies
        every new admitted request, including one reusing an old Idempotency-Key.
        Signature storage failures return JSON Error 503. GET challenges bypass POST signature guards.
        X declares receive at api/receive with a 300-second signature cache and no timestamp.
        Its legacy connector-webhooks address shares the same guard, push policy, audit counters and receipts until engine 1.0.0.
      x-required-permissions: [connector:push]
      requestBody:
        required: true
        content:
          application/json:
            schema: {}
      responses:
        '202':
          description: Items accepted for ingestion; poll each Receipt through the normal API.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ConnectorPushReceipts'}
        '429':
          description: Instance token bucket exhausted; no plugin call or idempotency reservation.
          headers:
            Retry-After:
              schema: {type: integer, minimum: 1}
              description: Seconds until the next rate token.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Error'}
        default:
          description: Structured engine error, or the plugin's refusal answer.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Error'}
          headers:
            Quivr-Response-Origin:
              description: Present with value plugin only for a plugin-defined reply, whose status, content type and body are forwarded unchanged.
              schema: {type: string, enum: [plugin]}
    get:
      operationId: challengeConnectorAPI
      security: [{ApiKey: []}, {InstanceToken: []}, {}]
      x-quivr-plugin-response: {header: Quivr-Response-Origin, value: plugin, statuses: [2XX, 4XX]}
      summary: Answer a declared source challenge
      description: >-
        Resolve a declared GET route with the same request limits and deadline as POST.
        Routes with auth: quivr_key require connector:push authorization and instance scope.
        Only synchronous provider challenges are supported;
        a GET answer carrying ingestion items is rejected before ingestion. Reads and management
        stay on the normal API. Plugin challenge (2xx) and refusal (4xx) replies carry the plugin's status,
        content type and body unchanged, marked with Quivr-Response-Origin: plugin. That header
        selects the plugin-defined response variant (x-quivr-plugin-response), including provider
        JSON or text challenges and statuses that overlap engine errors. Engine-generated failures
        have no Quivr-Response-Origin header and follow the JSON Error schema below. A bodyless
        challenge is relayed with parsed body null. Unknown paths return 404; undeclared methods
        return 405 with Allow. Authentication follows the declared auth mode: quivr_key or
        instance_token; credentials for one mode cannot authenticate the other.
        A 204 challenge must have an empty response body; a plugin answer
        combining 204 with a nonempty body returns 500 plugin_invalid_response.
        The same IP allowlist, token bucket, idempotency and audit rules as POST apply.
        Signature routes bypass the response cache so every admitted call reaches provider verification.
        Signature GET routes need no bearer key and bypass POST signature and replay checks;
        the provider challenge is still verified and answered by the plugin.
      x-required-permissions: [connector:push]
      responses:
        '200':
          description: The plugin's synchronous challenge answer.
          content:
            text/plain:
              schema: {type: string}
          headers:
            Quivr-Response-Origin:
              description: Present with value plugin only for a plugin-defined reply, whose status, content type and body are forwarded unchanged.
              schema: {type: string, enum: [plugin]}
        '429':
          description: Instance token bucket exhausted; no plugin call or idempotency reservation.
          headers:
            Retry-After:
              schema: {type: integer, minimum: 1}
              description: Seconds until the next rate token.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Error'}
        default:
          description: Structured engine error, or the plugin's refusal answer.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Error'}
          headers:
            Quivr-Response-Origin:
              description: Present with value plugin only for a plugin-defined reply, whose status, content type and body are forwarded unchanged.
              schema: {type: string, enum: [plugin]}
  /v0/connector-webhooks/{connector_id}:
    get:
      operationId: relayConnectorChallenge
      description: Public webhook route of one Connector Instance whose kind declares the push mode; the address
        is its webhook_url. There is no API key; the connector plugin verifies the request (a signature, a challenge)
        with the Deposited Credential. A GET is typically a source's verification challenge, relayed to the
        plugin like a delivery.
      security: []
      parameters:
      - name: connector_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        2XX:
          description: The connector plugin accepted the delivery; its items were ingested before this answer.
            The body and content type are the plugin's answer to the source (for example a challenge response).
        4XX:
          description: The connector plugin refused the delivery (for example a bad signature), with its
            own body; nothing changed. 404 names no enabled instance of a kind that declares push; 413 a
            body over 1 MiB.
        '500':
          description: The delivery cannot be processed (the plugin reported an access or source error),
            shown in health.push.
        '503':
          description: Temporarily unavailable (the plugin is unreachable or ingestion is down); retry after
            Retry-After seconds. Polling catches up meanwhile.
    post:
      operationId: relayConnectorDelivery
      description: Relay one delivery the source sends to the Connector Instance. The core passes the raw request
        (a body of at most 1 MiB, lowercase headers) to the connector plugin, which verifies it and returns
        the items it carries. Items converge with those of pull runs on the same Receipts. Deliveries update
        health.push.
      security: []
      parameters:
      - name: connector_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        2XX:
          description: The connector plugin accepted the delivery; its items were ingested before this answer.
            The body and content type are the plugin's answer to the source (for example a challenge response).
        4XX:
          description: The connector plugin refused the delivery (for example a bad signature), with its
            own body; nothing changed. 404 names no enabled instance of a kind that declares push; 413 a
            body over 1 MiB.
        '500':
          description: The delivery cannot be processed (the plugin reported an access or source error),
            shown in health.push.
        '503':
          description: Temporarily unavailable (the plugin is unreachable or ingestion is down); retry after
            Retry-After seconds. Polling catches up meanwhile.
  /v0/connectors/{connector_id}:
    get:
      operationId: getConnector
      description: Read configuration, credential metadata (never the secret) and the last evaluated Connector
        Health. Instances of other Organizations or unauthorized Corpora are 404.
      x-required-permissions:
      - connectors:read
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connector'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: connector_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
  /v0/connectors/{connector_id}/disable:
    post:
      operationId: disableConnector
      description: Commit disable. No new acquisition run is scheduled; an in-flight run cannot advance
        the Acquisition Checkpoint afterwards. Repeat is idempotent and disable is absorbing (no re-enable).
        Commits connector.disabled and connector.health_changed.
      x-required-permissions:
      - connectors:write
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connector'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: connector_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequest'
  /v0/connectors/{connector_id}/pause:
    post:
      operationId: pauseConnector
      description: Pause scheduled acquisition, including continuation of a long import. Fences the in-flight run and retains its last committed checkpoint. An already admitted source request may finish; stale progress cannot commit. Inbound push routes remain available. Returns paused_at; repeat pause preserves the timestamp and emits no event. Disabled instances return 409 connector_disabled. Commits connector.paused only on a transition.
      x-required-permissions:
      - connectors:write
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connector'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: connector_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequest'
  /v0/connectors/{connector_id}/resume:
    post:
      operationId: resumeConnector
      description: Resume scheduled acquisition from the last committed checkpoint, immediately unless the source Retry-After defers it. Clears paused_at. Repeat resume does not change scheduling or a live lease. Disabled instances return 409 connector_disabled and cannot be re-enabled. Commits connector.resumed only on a transition.
      x-required-permissions:
      - connectors:write
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connector'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: connector_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequest'
  /v0/connectors/{connector_id}/credential:
    put:
      operationId: replaceConnectorCredential
      description: Deposit a new credential version to rotate the current one. The secret is encrypted at
        rest and never returned. Replaying the same key and request is idempotent; a different request under
        the same key is 409 idempotency_conflict. A disabled instance is 409 connector_disabled. Commits
        connector.credential_replaced, and connector.health_changed when the evaluated health changes. A
        deployment without a credential key refuses every rotation with 503 credentials_unavailable
        (retryable false) before storing or digesting it.
      x-required-permissions:
      - connectors:write
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connector'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: connector_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CredentialReplace'
  /v0/connectors/{connector_id}/schedule:
    put:
      operationId: changeConnectorSchedule
      description: Set the polling interval of an enabled instance. Setting the current value commits nothing,
        so repeating the request is harmless. A shorter interval pulls the next scheduled run in; a longer
        one applies after the run already scheduled. A disabled instance is 409 connector_disabled; an interval
        below the deployment floor (30 s by default) or above 24 h is 422 invalid_interval with field
        /interval_seconds. Commits connector.schedule_changed only when the interval changes.
      x-required-permissions:
      - connectors:write
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connector'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: connector_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleChange'
  /v0/connectors/{connector_id}/runs:
    post:
      operationId: requestConnectorRun
      description: Ask for an acquisition run now instead of at the next scheduled time, for example to
        check again a source that failed. The next run is pulled in, never pushed out, so repeating the
        request changes nothing and a run already in flight answers it. Rate limits still hold -- the run
        starts no sooner than the deployment interval floor (30 s by default) after the previous run ended,
        nor before the Retry-After the source asked for. The run then goes through the usual scheduler lease
        and records its outcome in health, committing connector.health_changed when the state changes; the
        request itself commits no event. run_at is when the run is due; the scheduler starts it within
        seconds after. A disabled instance is 409 connector_disabled; a paused instance is 409 connector_paused.
      x-required-permissions:
      - connectors:write
      responses:
        '202':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorRunRequest'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: connector_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequest'
  /v0/connector-kinds:
    get:
      operationId: listConnectorKinds
      description: Connector kinds enabled in this deployment, with the JSON Schemas that validate their
        config and credential secret, so clients can render configuration forms without knowing the kinds.
        credential_deposits tells whether this deployment accepts Deposited Credentials at all; when unavailable,
        any create carrying a credential and every rotation is 503 credentials_unavailable.
      x-required-permissions:
      - connectors:read
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorKindCatalog'
        default:
          description: Structured error; see contract HTTP mapping.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/audit:
    get:
      operationId: listAuditEvents
      description: List immutable sensitive-action entries for the API key's organization, newest first.
        Requires audit:read and organization-wide Corpus scope. Time filters are RFC3339 instants;
        since is inclusive and until exclusive. Cursors bind organization, permissions and filters
        including limit; reuse the same filters on later pages. Reads and searches are not audited.
      x-required-permissions:
      - audit:read
      parameters:
      - name: since
        in: query
        description: Inclusive RFC3339 timestamp.
        schema: {type: string, format: date-time}
      - name: until
        in: query
        description: Exclusive RFC3339 timestamp.
        schema: {type: string, format: date-time}
      - name: actor
        in: query
        description: Exact API key identifier; no substring matching.
        schema: {type: string}
      - name: action
        in: query
        description: Exact audit action name; no substring matching.
        schema: {type: string}
      - name: target_type
        in: query
        description: Exact target type; no substring matching.
        schema: {type: string}
      - name: target_id
        in: query
        description: Exact target identifier; no substring matching.
        schema: {type: string}
      - name: limit
        in: query
        schema: {type: integer, minimum: 1, maximum: 200, default: 50}
      - name: page_cursor
        in: query
        schema: {type: string}
      responses:
        '200':
          description: An organization-scoped page of audit entries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditEventPage'
        default:
          description: Structured error; 401 invalid API key, 403 without audit:read or with restricted
            Corpus scope, 422 invalid_cursor, 422 invalid_schema or invalid_limit, 503 storage_unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/plugins:
    get:
      operationId: listPluginRegistrations
      description: Every plugin version this deployment has registered, oldest first, with its endpoint,
        manifest digest, the roles its manifest declares and its state. Quivr never starts a plugin; the
        operator runs it at its endpoint. Every start records the plugins pinned in the startup
        configuration. Deployment-wide and not paginated. Requires
        plugins:admin, an operator action that organization keys do not get.
      x-required-permissions:
      - plugins:admin
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginRegistrationList'
        default:
          description: Structured error; 401 unauthenticated, 403 without plugins:admin, 503 storage
            unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: registerPlugin
      description: Register a plugin version the operator runs at an address. The request carries the exact
        quivr-plugin.yaml the plugin was built from, its endpoint and the settings it is installed with,
        with the shape and rules of a pin in the startup configuration (configuration, routes, kinds,
        spaces); plugin id and version come from the manifest. Quivr then checks it in the background with
        the Contract Runner against the endpoint, whose discovery must report the manifest's digest, using
        the normative fixtures and the fixtures the request carries. The registration is registered while
        its check runs, then validated or rejected with the report. The same idempotency key returns the
        same registration; a key already used for another registration or other fixtures is 409
        idempotency_conflict; a new key for a rejected registration checks it again. 422 invalid_plugin
        lists what the engine refuses in the manifest, settings or fixture paths. The body is at most 8
        MiB (413 request_too_large). Requires plugins:admin.
      x-required-permissions:
      - plugins:admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PluginRegistrationRequest'
      responses:
        '202':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginRegistration'
          headers:
            Location:
              description: The registration's read URL, which reports the check once it ran.
              schema:
                type: string
                format: uri-reference
        default:
          description: Structured error; 400 malformed, 401 unauthenticated, 403 without plugins:admin, 409
            idempotency_conflict, 413 request_too_large, 422 invalid_schema or invalid_plugin, 503 storage
            unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/plugins/{registration_id}:
    get:
      operationId: getPluginRegistration
      description: One registration with the Contract Runner's report once its check ran. Requires plugins:admin.
      x-required-permissions:
      - plugins:admin
      parameters:
      - name: registration_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginRegistration'
        default:
          description: Structured error; 401 unauthenticated, 403 without plugins:admin, 404 unknown
            registration, 503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/plugins/{registration_id}/activate:
    post:
      operationId: activatePlugin
      description: Prepare and activate a validated registration as a background Operation. Provider discovery and installation-wide coverage validation run before publication. Work already started keeps its recorded plan. An unchanged activation still validates discovery. Follow Location until the Operation succeeds or fails; admin.plan_id names the resulting immutable Pipeline Plan. Requires plugins:admin.
      x-required-permissions:
      - plugins:admin
      parameters:
      - name: registration_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PluginActivationRequest'
      responses:
        '202':
          description: Accepted background Operation.
          headers:
            Location:
              description: Follow this Operation with GET.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        default:
          description: Structured admission error; 400 malformed, 401 unauthenticated, 403 without plugins:admin, 404 unknown target, 409 idempotency_conflict, 422 invalid_schema or invalid target, 503 storage unavailable. Discovery, plan compatibility and coverage failures are reported in the accepted Operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/plugins/plans/{plan_id}:
    get:
      operationId: getPipelinePlan
      description: Any Pipeline Plan this deployment recorded, active or not. Plans are immutable, so an
        earlier plan stays readable after an activation. Requires plugins:admin.
      x-required-permissions:
      - plugins:admin
      parameters:
      - name: plan_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelinePlan'
        default:
          description: Structured error; 401 unauthenticated, 403 without plugins:admin, 404 unknown plan,
            503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/plugins/plans:
    get:
      operationId: listPipelinePlans
      description: The latest Pipeline Plans this deployment recorded, newest first. Each names the plan
        it replaced (previous_plan_id) and what recorded it (source), so this list is the history of plan
        changes; earlier plans stay reachable through previous_plan_id. Requires plugins:admin.
      x-required-permissions:
      - plugins:admin
      parameters:
      - name: limit
        in: query
        required: false
        description: The most items to return. An empty, non-integer or out-of-range value is 422 invalid_limit.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelinePlanList'
        default:
          description: Structured error; 401 unauthenticated, 403 without plugins:admin, 422 invalid_limit,
            503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/backfills:
    post:
      operationId: requestBackfill
      description: Reprocess a Corpus's past Versions with a selected active ingestion plugin, to fill vector
        spaces of the generation the Corpus is routed to, typically a new evaluation space. The scope is the
        Corpus and, optionally, a window on when Quivr accepted its Versions. Only Versions segmented by the selected plugin whose segments
        all hold a vector in the served space and miss one in a target space are processed; live enrichment
        fills the target spaces for newer Versions once the backfill has started. A dry run is required.
        dry_run true answers 200 with the estimate and records it under the idempotency key. The same body
        with dry_run false then accepts the backfill as a queued Operation (202, Location). Without a dry run
        recorded under that key and scope, the answer is 409 dry_run_required. An estimated cost above the
        deployment's backfill.max_cost_without_confirmation needs confirm_cost true, otherwise 409
        cost_confirmation_required. The same key with another scope is 409 idempotency_conflict, and an
        accepted key replays its Operation. A Corpus whose previous backfill has not finished is 409
        backfill_in_progress. The backfill runs on its own task queue at the deployment's
        backfill.rate, pinned to the Pipeline Plan active when it starts. It can be paused, resumed and
        canceled, and resumes from its checkpoint after a restart. It never creates Record Versions or
        content events. Versions whose projected segments the plugin would cut differently are skipped and
        counted (segmentation_differs), and a rebuild re-segments them. Requires plugins:admin, on a key of the
        Corpus's Organization that grants the Corpus.
      x-required-permissions:
      - plugins:admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BackfillRequest'
      responses:
        '200':
          description: The dry run's estimate, recorded under the key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackfillEstimate'
        '202':
          description: The accepted backfill Operation; read it at the Location.
          headers:
            Location:
              required: true
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        default:
          description: Structured error; 400 malformed, 401 unauthenticated, 403 without plugins:admin, 404
            unknown Corpus, 409 dry_run_required, cost_confirmation_required, idempotency_conflict,
            backfill_in_progress, registration_not_active or rebuild_required (the Corpus's generation predates named vector
            spaces), 422 invalid_schema or invalid_backfill (a space the plugin does not declare or the
            deployment does not enable, or an empty window), 503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/spaces/{vector_space_id}/promote:
    post:
      operationId: promoteVectorSpace
      description: Prepare a deployment-wide vector space promotion as a background Operation. Coverage is checked in bounded batches while imports continue. Incomplete coverage fails the Operation with coverage_incomplete unless force is true. The final switch changes routing atomically. The previous space retains its vectors and can be promoted again. Follow Location; admin.served_space_id and admin.previous_space_id describe the successful switch. Requires plugins:admin.
      x-required-permissions:
      - plugins:admin
      parameters:
      - name: vector_space_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VectorSpacePromotionRequest'
      responses:
        '202':
          description: Accepted background Operation.
          headers:
            Location:
              description: Follow this Operation with GET.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        default:
          description: Structured admission error; 400 malformed, 401 unauthenticated, 403 without plugins:admin, 404 unknown target, 409 idempotency_conflict, 422 invalid_schema or invalid target, 503 storage unavailable. Discovery, plan compatibility and coverage failures are reported in the accepted Operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/queues:
    get:
      operationId: getQueueBacklog
      description: Installation-wide document backlog for live and bulk workers. Requires the operator grant queues:read and all-Corpora scope. Stable numeric queues.live.waiting and queues.bulk.waiting paths support external autoscalers. Counts come from PostgreSQL, including undispatched work, and exclude terminal work. Bearer authentication uses the configured API key.
      x-required-permissions: [queues:read]
      responses:
        '200':
          description: Latest shared queue observation, refreshed in the background.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueBacklog'
        default:
          description: Structured error; 401 unauthenticated, 403 without installation operator grant, 503 storage unavailable, or queue snapshot missing or older than one minute.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/quarantine:
    get:
      operationId: listQuarantinedVersions
      description: The Record Versions stuck in quarantine, in Version id order, with the step each failed at
        (normalization or ingestion), its reason and when it was quarantined. Stuck means the Version can
        still become current; a Version its Record no longer desires (a newer revision was accepted) or whose
        Record was withdrawn is not listed. A reason recorded before quarantine reasons were structured has
        only its code and names no plugin, and its quarantined_at is when its revision was accepted. Every
        filter narrows the list; plugin matches the plugin id the reason names. Requires plugins:admin; a key
        limited to some Corpora lists theirs only. The cursor is bound to the key's scope and filters.
      x-required-permissions:
      - plugins:admin
      parameters:
      - name: corpus_id
        in: query
        required: false
        schema:
          type: string
          minLength: 1
      - name: plugin
        in: query
        required: false
        schema:
          type: string
          minLength: 1
      - name: code
        in: query
        required: false
        schema:
          type: string
          minLength: 1
      - name: quarantined_after
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: quarantined_before
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: page_cursor
        in: query
        required: false
        schema:
          type: string
          minLength: 1
      - name: limit
        in: query
        required: false
        description: The most items to return. An empty, non-integer or out-of-range value is 422 invalid_limit.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuarantinePage'
        default:
          description: Structured error; 401 unauthenticated, 403 without plugins:admin, 404 a corpus_id
            outside the key's Corpora, 409 cursor_scope_changed, 422 invalid query, limit, cursor or window,
            503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/quarantine/reprocess:
    post:
      operationId: reprocessQuarantine
      description: Rerun, with the Pipeline Plan active now, the step a Corpus's stuck Versions failed at,
        typically after a plugin was fixed and activated or a plan rolled back. A Version quarantined at
        normalization is normalized again, published with its new Manifest and processed; one quarantined at
        ingestion is segmented, embedded and indexed again. A Version that succeeds goes through the normal
        path, as for a first success. It becomes current if its Record still desires it, searchable, its
        alerts are evaluated, and the change feed announces it (record.materialized when its content changed,
        record.retrieval_ready, record.enrichment_available). A Version that fails again stays quarantined
        with its new reason. The scope is the Corpus's stuck Versions (see listQuarantinedVersions), kept by
        the optional filters, taken when the reprocess is accepted. Set from_stage to normalization to
        normalize its stored source Blob again before ingestion; omit it to retry the failed step. A dry run is required. dry_run true
        answers 200 with the count and records it under the idempotency key. The same body with dry_run
        false then accepts the reprocess as a queued Operation (202, Location). Without a dry run recorded
        under that key and Corpus, the answer is 409 dry_run_required. The same key with another filter scope or restart stage is 409
        idempotency_conflict, and an accepted key replays its Operation. A Corpus whose previous reprocess
        has not finished is 409 reprocess_in_progress. The reprocess runs on the backfills' task queue at the
        deployment's backfill.rate, pinned to the plan active when it is accepted. It can be paused, resumed,
        canceled and rerun. Its counters are versions_in_scope, versions_recovered, versions_quarantined
        (failed again) and versions_skipped (with skipped_<reason>). Requires plugins:admin, on a key of
        the Corpus's Organization that grants the Corpus.
      x-required-permissions:
      - plugins:admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuarantineReprocessRequest'
      responses:
        '200':
          description: The dry run's count, recorded under the key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuarantineReprocessEstimate'
        '202':
          description: The accepted reprocess Operation; read it at the Location.
          headers:
            Location:
              required: true
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        default:
          description: Structured error; 400 malformed, 401 unauthenticated, 403 without plugins:admin, 404
            unknown Corpus, 409 dry_run_required, idempotency_conflict or reprocess_in_progress, 422
            invalid_schema or invalid_reprocess (an empty window), 503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/subscriptions/evaluator-migrations:
    post:
      operationId: migrateSubscriptionEvaluators
      description: Move the key's Organization's Subscriptions from one version of an alert-rule plugin to
        the version the active Pipeline Plan serves, after that plugin's upgrade or rollback. It looks at
        the Subscriptions that are not deleted, enabled or disabled, whose current Version pins plugin_id at
        from_version, in Subscription id order, at most limit of them, after after. Each one's Saved Query
        expression and evaluator configuration must validate against the served version's schemas first;
        one that does not is listed in refused with the first issue and keeps its version. A moved
        Subscription gets a new current Version that keeps its Saved Query Version, configuration and
        destination and pins the served version. Like an edit, it judges only changes committed after it,
        nothing is re-evaluated, Matches keep the Version that produced them, and subscription.updated is
        announced in each of its Corpora. dry_run true validates and lists what would move without moving
        anything. A call moves each Subscription at most once; calling again with next_after continues, and
        repeating a call converges. Subscriptions whose Corpora the key does not all grant are left out.
        422 unsupported_evaluator when no version of plugin_id serves new Subscriptions, invalid_migration
        when from_version is that version. Requires plugins:admin.
      x-required-permissions:
      - plugins:admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionEvaluatorMigrationRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEvaluatorMigration'
        default:
          description: Structured error; 400 malformed, 401 unauthenticated, 403 without plugins:admin, 422
            invalid_schema, unsupported_evaluator or invalid_migration, 503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/subscriptions/evaluation-backlog:
    get:
      operationId: listEvaluationBacklog
      description: Read evaluation counts grouped by the pinned evaluator plugin id and version, only
        in the key's Organization and granted Corpora. unavailable counts pending intents whose latest
        error is evaluator_unavailable, not a live endpoint health check. retired counts terminal
        evaluator_retired intents. Rows with neither pending nor retired evaluations are omitted.
        Requires plugins:admin. Pages are ordered by plugin_id@version; next_after is the next after.
      x-required-permissions:
      - plugins:admin
      parameters:
      - in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 100
        description: Maximum evaluator versions returned; a present invalid value is 422 invalid_limit.
      - in: query
        name: after
        schema:
          type: string
          minLength: 1
          maxLength: 256
        description: The previous page's next_after. Counts are live, not a snapshot across pages.
      responses:
        '200':
          description: Scoped per-version counts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluationBacklogPage'
        default:
          description: Structured error; 401 unauthenticated, 403 without plugins:admin, 404 not configured,
            422 invalid_query or invalid_limit, 503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/subscriptions/evaluation-retirements:
    post:
      operationId: retireEvaluations
      description: Explicitly abandon a bounded batch of pending evaluations pinned to the named
        evaluator whose latest error is evaluator_unavailable. Only the key's Organization and granted
        Corpora are considered. Live leases and withdrawals are left alone. Never migrate an intent,
        run another evaluator, create a Match or Delivery, or declare no_match. The terminal outcome
        is evaluator_retired. Each real retirement emits evaluation.retired in the intent's Corpus,
        with resource.kind=evaluation_retirement and resource.id=retirement_id. The immutable receipt
        records the reason, original identities and event ids, and is readable at the Location.
        A real key replay returns the original batch, including its original counts; another request
        or Corpus scope using that key is 409 idempotency_conflict. An empty real batch also reserves
        its key. dry_run selects without writes or reserving the
        key, and remaining reports how many unavailable intents would remain after that selection.
        Use new real keys for further batches and recheck live backlog counts after dispatch and leases
        settle. This action does not establish a policy for future intents. It deliberately discards
        potential alerts; restore the exact old implementation to drain without losing judgments.
        Requires plugins:admin.
      x-required-permissions:
      - plugins:admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvaluationRetirementRequest'
      responses:
        '200':
          description: The dry-run preview or committed audit receipt
          headers:
            Location:
              description: The receipt read URL, present only for a real batch.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluationRetirement'
        default:
          description: Structured error; 400 malformed, 401 unauthenticated, 403 without plugins:admin,
            404 not configured, 409 idempotency_conflict, 422 invalid_schema, invalid_input or invalid_limit,
            503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/subscriptions/evaluation-retirements/{retirement_id}:
    get:
      operationId: getEvaluationRetirement
      description: Read the immutable audit receipt referenced by an evaluation.retired event or the
        retirement action's Location. Requires plugins:admin and grants covering the original request's
        entire Corpus scope; a deployment-wide request requires a key granting all Corpora. Unknown,
        another Organization's and ungranted receipts all answer 404 not_found.
      x-required-permissions:
      - plugins:admin
      parameters:
      - in: path
        name: retirement_id
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: The committed receipt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluationRetirement'
        default:
          description: Structured error; 401 unauthenticated, 403 without plugins:admin, 404 not_found,
            503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/plugins/plan/rollback:
    post:
      operationId: rollbackPipelinePlan
      description: Restore an earlier immutable Pipeline Plan through a background Operation. plan_id defaults to the plan the active one replaced. Returning registrations must answer discovery with their exact manifest digest. Coverage gaps do not prevent rollback; affected records retain their outgoing owner and space until background recovery completes the returning projection. pinned_work chooses drain or stop for outgoing work; pinned Subscription Versions keep their evaluators. Follow Location; admin.plan_id names the new rollback plan. Requires plugins:admin.
      x-required-permissions:
      - plugins:admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipelinePlanRollbackRequest'
      responses:
        '202':
          description: Accepted background Operation.
          headers:
            Location:
              description: Follow this Operation with GET.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        default:
          description: Structured admission error; 400 malformed, 401 unauthenticated, 403 without plugins:admin, 404 unknown target, 409 idempotency_conflict, 422 invalid_schema or invalid target, 503 storage unavailable. Discovery, plan compatibility and coverage failures are reported in the accepted Operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/plugins/plan:
    get:
      operationId: getActivePipelinePlan
      description: The active Pipeline Plan, an immutable mapping of every role of the deployment to the
        registration serving it, which api and worker follow. 404 not_found when no plan is active, because the startup configuration
        pins no plugin. Requires plugins:admin.
      x-required-permissions:
      - plugins:admin
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelinePlan'
        default:
          description: Structured error; 401 unauthenticated, 403 without plugins:admin, 404 no active plan,
            503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/active-plugins:
    get:
      operationId: listActivePlugins
      description: The plugin versions the active Pipeline Plan runs and the roles each serves, for operator
        views that read the plugin call rollups beside them. It names no address, configuration, manifest
        or digest, so it needs observability:read on a key that grants every Corpus, not plugins:admin. Empty
        when no plan is active.
      x-required-permissions:
      - observability:read
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivePluginList'
        default:
          description: Structured error; 401 unauthenticated, 403 without observability:read on every Corpus,
            404 on a deployment without a plugin registry, 503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/documents:
    get:
      operationId: listAdminDocuments
      description: The Organization's most recently accepted Record Versions across all its Corpora,
        newest first, with their Source, title, current state and step times, read in one query. Requires
        observability:read on a key for all Corpora; a key limited to some Corpora gets 403. Versions
        accepted before step times were recorded are not listed. Pages are independent reads, not a snapshot;
        the cursor is bound to the key's scope.
      x-required-permissions:
      - observability:read
      parameters:
      - name: page_cursor
        in: query
        required: false
        schema:
          type: string
          minLength: 1
      - name: limit
        in: query
        required: false
        description: The most items to return. An empty, non-integer or out-of-range value is 422 invalid_limit.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminDocumentPage'
        default:
          description: Structured error; 401 unauthenticated, 403 without observability:read or all Corpora, 409 cursor_scope_changed,
            422 invalid query, limit or cursor, 503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/documents/{version_id}/timeline:
    get:
      operationId: getDocumentTimeline
      description: One Record Version's finished steps in time order, each with how long it took since
        the step that caused it and, when known, the plugin that ran it. 404 for an unknown Version or one
        outside the key's Corpora. Requires observability:read.
      x-required-permissions:
      - observability:read
      parameters:
      - name: version_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentTimeline'
        default:
          description: Structured error; 401 unauthenticated, 403 without observability:read, 404 not found,
            503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/stats/connector-pushes:
    get:
      operationId: listConnectorPushStats
      summary: Count accepted and refused pushes per source instance
      description: >-
        Per-instance attempts to declared source API routes, split into received (2xx,
        including cached answers and GET challenges) and refused (all other answers).
        Includes authentication, scope, body, rate and IP refusals for existing instances.
        No payload, credentials, client IP or raw idempotency key is stored. Audit events
        and counters commit together. Requires observability:read on all Corpora;
        returns only the key's Organization. Uses the Spec 16 rollup windows and retention.
        By default lists the largest 100 instance/outcome pairs, with a total across
        every pair. Use connector_id to read both outcomes of one instance; its
        total then covers that instance only.
      parameters:
      - name: window
        in: query
        schema: {type: string, enum: [1h, 24h, 7d], default: 1h}
      - name: limit
        in: query
        description: Largest instance/outcome pairs to list; cannot be combined with connector_id.
        schema: {type: integer, minimum: 1, maximum: 100, default: 100}
      - name: connector_id
        in: query
        description: Read both outcomes of this instance; cannot be combined with limit.
        schema: {type: string, minLength: 1, maxLength: 256}
      x-required-permissions: [observability:read]
      responses:
        '200':
          description: Per-instance counters and time buckets.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ConnectorPushStatsList'}
        default:
          description: Structured error.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Error'}
  /v0/admin/stats/plugins:
    get:
      operationId: getPluginCallStats
      description: Calls, errors and latency of every plugin Contribution invoked for the key's Organization
        over the window, per plugin version and operation, with the last error code the plugin declared
        (or plugin_unavailable, invalid_output). Counts are written by each process every few seconds and
        kept 7 days; a window reads buckets of one resolution (1 minute for 1h, 15 minutes for 24h, 2 hours
        for 7d) and lists only non-empty ones. Latency percentiles are interpolated from fixed buckets.
        Requires observability:read on a key that grants every Corpus.
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          enum:
          - 1h
          - 24h
          - 7d
          default: 1h
      x-required-permissions:
      - observability:read
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginCallStatsList'
        default:
          description: Structured error; 401 unauthenticated, 403 without observability:read on every Corpus, 422 invalid_window,
            503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/stats/searches:
    get:
      operationId: getSearchStats
      description: Searches of the key's Organization over the window per mode and search profile, with
        errors, latency, the number of results returned and the number of searches over the profile's latency
        objective, in the buckets of getPluginCallStats. The profile is unknown for a search that named a
        profile the deployment does not serve. Requires observability:read on a key that grants every Corpus.
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          enum:
          - 1h
          - 24h
          - 7d
          default: 1h
      x-required-permissions:
      - observability:read
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchStatsList'
        default:
          description: Structured error; 401 unauthenticated, 403 without observability:read on every Corpus, 422 invalid_window,
            503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/stats/steps:
    get:
      operationId: getStepStats
      description: 'Processing steps of the key''s Organization over the window, in the buckets of getPluginCallStats:
        baseline (cut into segments and made searchable by keyword), enrichment (vectors added) and accepted_to_searchable
        (from acceptance to searchable by keyword) time the worker''s runs. materialized, segmented, retrieval_ready
        and enriched are the document timeline''s steps, each timed from the step that causes it, so they include
        the time a Record Version waited for the step. An error is a step that is retried or blocked, with its
        code. Requires observability:read on a key that grants every Corpus.'
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          enum:
          - 1h
          - 24h
          - 7d
          default: 1h
      x-required-permissions:
      - observability:read
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StepStatsList'
        default:
          description: Structured error; 401 unauthenticated, 403 without observability:read on every Corpus, 422 invalid_window,
            503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/stats/received:
    get:
      operationId: getReceivedStats
      description: Documents received by the key's Organization over the window per source namespace, in
        the buckets of getPluginCallStats. A document is counted when a command reserves a new revision of
        a Record; a replayed command or a revision the Record already had is not. Lists the limit namespaces
        with most documents, largest first; total and sources cover every namespace. Requires
        observability:read on a key that grants every Corpus.
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          enum:
          - 1h
          - 24h
          - 7d
          default: 1h
      - name: limit
        in: query
        required: false
        description: The most items to return. An empty, non-integer or out-of-range value is 422 invalid_limit.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
      x-required-permissions:
      - observability:read
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceivedStatsList'
        default:
          description: Structured error; 401 unauthenticated, 403 without observability:read on every Corpus, 422 invalid_window
            or invalid_limit, 503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/stats/matches:
    get:
      operationId: getMatchStats
      description: Matches the Subscriptions of the key's Organization committed over the window, per evaluator
        plugin, in the buckets of getPluginCallStats. A Match that corrects an earlier one on a new Version
        of the same Record counts too. Requires observability:read on a key that grants every Corpus.
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          enum:
          - 1h
          - 24h
          - 7d
          default: 1h
      x-required-permissions:
      - observability:read
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchStatsList'
        default:
          description: Structured error; 401 unauthenticated, 403 without observability:read on every Corpus, 422 invalid_window,
            503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/admin/stats/top-queries:
    get:
      operationId: getTopQueries
      description: The most frequent search queries of the key's Organization over the window, normalized
        (lowercased, white space collapsed, at most 200 characters) and counted per hour, each with its hourly
        counts. Query text is recorded
        only when the deployment sets observability.record_query_text; otherwise recording is false and the
        list is empty. Requires observability:read on a key that grants every Corpus.
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          enum:
          - 1h
          - 24h
          - 7d
          default: 1h
      - name: limit
        in: query
        required: false
        description: The most items to return. An empty, non-integer or out-of-range value is 422 invalid_limit.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      x-required-permissions:
      - observability:read
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopQueryList'
        default:
          description: Structured error; 401 unauthenticated, 403 without observability:read on every Corpus, 422 invalid_window
            or invalid_limit, 503 storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v0/search:
    post:
      operationId: searchRecords
      description: Resolve the requested profile, compile mandatory Corpus/Organization prefilters and
        any requested filter, obtain candidates, then canonically hydrate and reauthorize every returned segment. Lexical-first records
        remain eligible without embeddings; semantic-only queries require vector coverage. Ordinary hybrid searches
        use keywords for Corpora whose served vectors are unavailable, reporting their ids in retrieval_profile.degraded.
        Other Corpora keep their hybrid ranking. Explicit semantic requests remain 422 unsupported_search when
        vector search cannot run. Unknown coverage alone does not disable a routed space. Profile selection
        does not change access/currentness rules. When a retrieval plugin is pinned, it ranks. It asks
        the engine for candidates in up to three rounds and returns its ranking, which may hold only
        candidates the engine served in this search, each already authorized and hydrated.
        Each API process admits at most 64 active searches across callers. At capacity it immediately
        returns retryable 503 search_unavailable with Retry-After before storage or plugin work.
        A query encoding model that cannot answer returns retryable 503 model_unavailable,
        including the legacy inference service and the ingestion plugin that owns the requested vector space.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        default:
          description: Structured error; 400 malformed, 401 unauthenticated, 403 unauthorized scope/action,
            404 absent/inaccessible, 409 idempotency conflict, 422 unsupported_profile, query_too_long
            (the query is over the profile's or the vector space owner's length limit; the message names
            it), unsupported_search or source_filter_unavailable, 502 retrieval_plugin_invalid (the retrieval plugin broke its
            contract, for example ranked a segment the engine never served it), 503 model_unavailable
            (the query encoding model could not answer) or search_unavailable (another search dependency is unavailable),
            504 search_deadline_exceeded (the retrieval plugin's rounds outran the profile's hard bound, four times max_latency_ms;
            a dependency that does not answer in time is 503). At search capacity, 503 search_unavailable
            includes Retry-After; retry only after that delay.
          headers:
            Retry-After:
              description: Present when search capacity is full; minimum delay in seconds before retrying.
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-required-permissions:
      - content:read
      - search:query
  /v0/search/profiles:
    get:
      operationId: listSearchProfiles
      description: Every installed search profile, the profile aliased as default first, with full names, short names and budgets; the
        pinned retrieval plugin (core.retrieve unless another is pinned) declares them.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchProfileList'
        default:
          description: Structured error; 401 unauthenticated, 403 unauthorized scope/action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-required-permissions:
      - search:query
  /v0/corpora/{corpus_id}/vector-spaces:
    get:
      operationId: listVectorSpaces
      description: The vector spaces the Corpus's routed Projection Generation carries, the served one
        first, each with its owner (the engine, or the ingestion plugin that declares it), model, dimensions,
        metric, indexed and query modalities, its role in the generation (served answers search, evaluation
        is indexed and compared but never served) and its coverage, the current segments that hold a
        vector in it. A Corpus built before a space was enabled lists only the spaces it was built with;
        rebuild it (rebuildCorpusProjection) to add the others.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VectorSpaceList'
        default:
          description: Structured error; 401 unauthenticated, 403 unauthorized scope/action, 404 absent/inaccessible,
            503 dependency unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: corpus_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      x-required-permissions:
      - corpora:read
  /v0/corpora/{corpus_id}/rebuilds:
    post:
      operationId: rebuildCorpusProjection
      description: Durably commit a projection_rebuild Operation and dispatch intent before returning.
        Rebuild the requested Corpus from canonical text and durable artifacts, then activate its validated
        logical generation. Same Organization + Corpus + rebuild route + idempotency key and canonical
        request returns the same Operation, including after terminal completion; changed request conflicts.
        HTTP does not wait for reconstruction. Retries/restarts keep identity and target generation. Preserve
        other Corpora when physical storage is shared. Normal ingestion/withdrawal guards still apply.
        Live evaluation schema migrations remain a separate mechanism. Activation follows acceptance
        order, so a rebuild accepted before one that already activated for the same Corpus and retrieval
        configuration fails with operation_superseded instead of replacing it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequest'
      responses:
        '202':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
          headers:
            Location:
              description: Authorized Operation read URL.
              schema:
                type: string
                format: uri-reference
        default:
          description: Structured error; 400 malformed, 401 unauthenticated, 403 unauthorized scope/action,
            404 absent/inaccessible, 409 idempotency conflict, 422 unsupported profile/input, 503 dependency
            unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-required-permissions:
      - projections:rebuild
      parameters:
      - name: corpus_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
components:
  securitySchemes:
    InstanceToken:
      type: http
      scheme: bearer
      description: Source-scoped token accepted only by its instance's declared instance_token routes. Never grants normal API or token management access.
    ApiKey:
      type: http
      scheme: bearer
      description: API key, not necessarily a JWT. Server derives Organization, permitted actions and
        Corpus scope; every resource access is authorized.
  schemas:
    BuildVersion:
      type: object
      additionalProperties: false
      required: [version, revision, api_version, plugin_engine_version]
      properties:
        version:
          type: string
          description: Distribution release version, or dev for an unversioned build.
        revision:
          type: string
          description: Full source commit, or unknown for an unversioned build.
        api_version:
          type: string
          enum: [v0]
        plugin_engine_version:
          type: string
          description: Engine compatibility version checked against plugin manifests, independent of the distribution release.
    AuditEvent:
      type: object
      additionalProperties: false
      required: [id, time, actor, action, target_type, target_id, organization, outcome, request_id, detail]
      properties:
        id: {type: string, pattern: '^[1-9][0-9]*$', description: 'Decimal audit identifier, represented as text to preserve bigint precision.'}
        time: {type: string, format: date-time}
        actor: {type: string, description: SHA-256-derived API key identifier; empty for unauthenticated attempts.}
        action: {type: string}
        target_type: {type: string}
        target_id: {type: string, description: Target identifier; empty if refusal occurred before the target could be resolved.}
        organization: {type: string}
        outcome: {type: string, enum: [accepted, refused]}
        request_id: {type: string}
        detail:
          type: object
          additionalProperties: false
          required: [status]
          properties:
            status: {type: integer, minimum: 100, maximum: 599}
            error_code: {type: string}
            plan_id: {type: string}
            credential_version: {type: integer, minimum: 1}
    AuditEventPage:
      type: object
      additionalProperties: false
      required: [items]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AuditEvent'
        next_page_cursor: {type: string}
    ConnectorToken:
      type: object
      additionalProperties: false
      required: [token_id, prefix, created_at]
      properties:
        token_id: {type: string}
        prefix: {type: string, description: Display prefix only; cannot authenticate.}
        created_at: {type: string, format: date-time}
        rotated_at: {type: string, format: date-time}
        revoked_at: {type: string, format: date-time}
        valid_until: {type: string, format: date-time, description: Exclusive expiry of an old token after rotation; absent for an unrotated token.}
    ConnectorTokenCreated:
      type: object
      additionalProperties: false
      required: [token, secret]
      properties:
        token: {$ref: '#/components/schemas/ConnectorToken'}
        secret: {type: string, description: One-time bearer secret; never persisted or returned by metadata reads.}
    ConnectorTokenList:
      type: object
      additionalProperties: false
      required: [items]
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/ConnectorToken'}
        next_after: {type: string}
    ConnectorPushReceipts:
      type: object
      additionalProperties: false
      required: [receipts]
      properties:
        receipts:
          type: array
          items: {$ref: '#/components/schemas/Receipt'}
    SourceIdentity:
      $ref: ../../shared/v0/manifest.schema.json#/$defs/SourceIdentity
    Error:
      type: object
      additionalProperties: false
      properties:
        request_id:
          type: string
          description: Bounded caller X-Request-ID, or an engine-generated correlation ID.
        trace_id:
          type: string
          description: W3C trace ID when a trace context is present.
        span_id:
          type: string
          description: W3C span ID of the API handler when a trace context is present.
        code:
          type: string
          minLength: 1
        message:
          type: string
          minLength: 1
        retryable:
          type: boolean
        field:
          type: string
          minLength: 1
          description: JSON Pointer (RFC 6901) to the request member that caused a 422, when known (for
            example /config/url or /credential/secret/token on connector commands).
        resync_url:
          type: string
          format: uri-reference
      required:
      - code
      - message
      - retryable
    Diagnostic:
      type: object
      additionalProperties: false
      description: |-
        A structured processing diagnostic. plugin, contribution and invocation_id name the external
        invocation a normalization diagnostic concerns. Codes of external normalization:

        - normalizer_failed: the normalizer answered a terminal error. The Version is quarantined.
        - normalizer_invalid_output: the output broke the Plugin Protocol or the Manifest rules (schema,
          malformed or duplicate Part, a Blob Part that is not the input Blob or has another checksum,
          an undeclared extension namespace, too many Parts, a response over the size bound). Nothing
          from it is published; the Version is quarantined.
        - normalizer_timeout: the invocations kept exceeding the timeout until the retry budget (the
          manifest's retry.max_attempts, capped by the engine at 5) was spent. The Version is quarantined.
        - normalizer_retries_exhausted: the normalizer kept answering retryable errors until the retry
          budget was spent. The Version is quarantined.
        - input_unverified: the input Blob was no longer the verified accepted input. The Version is
          quarantined.
        - normalizer_unrouted: the media type's route was removed after acceptance and the built-in text
          path cannot read it (a text/* Blob takes the built-in text path instead). The Version is
          quarantined.
        - normalization_superseded: a newer revision of the Record was accepted before this Version was
          normalized, so the normalizer was not invoked. The Version is quarantined and never current.
        - normalizer_conflict: a later invocation with the same idempotency key returned a different
          output. The first recorded output is kept and published; nothing is overwritten.

        On an optional route every quarantining code above that comes from the normalizer is instead
        listed on a searchable Version published through the built-in text path. A plugin that is
        unavailable (connection failure, 5xx without an error envelope, discovery that does not match the
        pinned manifest) is retried with backoff. Live imports, including normalization, produce no
        diagnostic for these outages even after the plugin leaves the active Pipeline Plan; the Receipt
        shows plugin_unavailable while it retries.

        - pinned_plugin_unavailable: an older plan's plugin exhausted the deployment's attempt budget
          during an Operation or after ingestion invocation deadlines, or its ingestion owner could no
          longer serve the work. Live imports
          and normalization now retain their pin and retry reachability outages until the exact build
          returns; they never silently move to its replacement. A Version with this diagnostic is
          quarantined, or keeps its searchable text while enrichment stops. plan, plugin and
          plugin_version name the original plan and plugin.
        - pinned_plan_stopped: the processing of this Version started on a Pipeline Plan that an operator
          rolled back with pinned_work=stop. At its next call to a plugin that left the active plan, the
          work stopped instead of calling it, with the same outcome and fields as
          pinned_plugin_unavailable.

        Quarantined Versions keep their input reference and reason. An operator lists them and reprocesses
        them with the active plan (listQuarantinedVersions, reprocessQuarantine); a reprocess that fails
        again replaces the reason.
      properties:
        code:
          type: string
          minLength: 1
        message:
          type: string
          minLength: 1
        retryable:
          type: boolean
          description: Whether the same input may succeed if processed again.
        plugin:
          type: string
          minLength: 1
          description: Plugin id of the invocation.
        plugin_version:
          type: string
          minLength: 1
          description: Plugin version of a pinned_plugin_unavailable or pinned_plan_stopped diagnostic.
        plan:
          type: string
          minLength: 1
          description: Pipeline Plan the stopped work was pinned to, in a pinned_plugin_unavailable or
            pinned_plan_stopped diagnostic.
        contribution:
          type: string
          minLength: 1
        invocation_id:
          type: string
          minLength: 1
      required:
      - code
      - message
      - retryable
    Extensions:
      $ref: ../../shared/v0/manifest.schema.json#/$defs/Extensions
    TextContent:
      $ref: ../../shared/v0/manifest.schema.json#/$defs/TextContent
    BlobContent:
      $ref: ../../shared/v0/manifest.schema.json#/$defs/BlobContent
    Part:
      $ref: ../../shared/v0/manifest.schema.json#/$defs/Part
    RelationInput:
      $ref: ../../shared/v0/manifest.schema.json#/$defs/RelationInput
    ManifestContent:
      $ref: ../../shared/v0/manifest.schema.json#/$defs/ManifestContent
    Provenance:
      $ref: ../../shared/v0/manifest.schema.json#/$defs/Provenance
    NormalizationProvenance:
      $ref: ../../shared/v0/manifest.schema.json#/$defs/NormalizationProvenance
    IngestCommand:
      type: object
      additionalProperties: false
      properties:
        idempotency_key:
          type: string
          minLength: 1
        source:
          $ref: '#/components/schemas/SourceIdentity'
        source_revision:
          type: string
          minLength: 1
        source_position:
          type: string
          pattern: ^[0-9]+$
          description: Optional monotonic source position, encoded as decimal text to avoid JSON numeric
            precision loss.
        content:
          oneOf:
          - $ref: '#/components/schemas/TextContent'
          - $ref: '#/components/schemas/BlobContent'
          - $ref: '#/components/schemas/ManifestContent'
          discriminator:
            propertyName: kind
            mapping:
              text: '#/components/schemas/TextContent'
              blob: '#/components/schemas/BlobContent'
              manifest: '#/components/schemas/ManifestContent'
        extensions:
          $ref: '#/components/schemas/Extensions'
        provenance:
          $ref: '#/components/schemas/Provenance'
      required:
      - idempotency_key
      - source
      - content
      description: Initial request shape. Same source identity creates or corrects a Record. Same external
        revision with different canonical content conflicts. No revision means canonical Manifest digest
        identity; no source position means durable acceptance order. Single and batch entry replay share
        route_family=ingestion. A blob content accepts a verified text/* Blob, read at acceptance, or a
        Blob whose media type the installation routes to an external normalizer; that normalizer runs after
        acceptance and its output is the published Manifest, while the Version identity still derives from
        the submitted Blob. When the normalizer fails, the Version is quarantined with a Diagnostic on the
        Version read (or, on an optional text/* route, published through the built-in text path with
        provenance.normalization.fallback). Other media types are rejected with unverified_blob.
        provenance.normalization is engine-owned and rejected on input. Extension namespaces owned by the
        pinned plugin are written only by its normalizer output, published on the Version; a submission
        writing one, top-level or on a Part, is rejected with 422 extension_namespace_owned.
    WithdrawalCommand:
      type: object
      additionalProperties: false
      properties:
        idempotency_key:
          type: string
          minLength: 1
        source:
          $ref: '#/components/schemas/SourceIdentity'
        reason:
          type: string
          minLength: 1
      required:
      - idempotency_key
      - source
    Availability:
      type: object
      additionalProperties: false
      properties:
        state:
          type: string
          enum:
          - materialized
          - building_baseline
          - retrieval_ready
          - quarantined
        is_current:
          type: boolean
        searchable:
          type: boolean
      required:
      - state
      - is_current
      - searchable
    Receipt:
      type: object
      additionalProperties: false
      properties:
        receipt_id:
          type: string
          minLength: 1
        state:
          type: string
          enum:
          - pending
          - resolved
        outcome:
          type: string
          enum:
          - created
          - duplicate
          - withdrawal_applied
          - conflict
        record_id:
          type: string
          minLength: 1
        version_id:
          type: string
          minLength: 1
        availability:
          $ref: '#/components/schemas/Availability'
        diagnostics:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          maxItems: 20
        source:
          $ref: '#/components/schemas/SourceIdentity'
        processing:
          $ref: '#/components/schemas/ProcessingSummary'
      required:
      - receipt_id
      - state
      - diagnostics
      - source
      - processing
      description: Durable acceptance outcome, not workflow state. Availability is a separate authorized
        live read view; omitted before a linked version exists. Infrastructure retry never resolves a
        Receipt as failed.
      if:
        properties:
          state:
            const: pending
      then:
        not:
          required:
          - outcome
      else:
        required:
        - outcome
    BatchRequest:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items: {}
          minItems: 1
          maxItems: 100
      required:
      - items
      description: Envelope validation checks items array and batch/body limits only. Each raw entry is
        independently validated as IngestCommand; even a missing required field or wrong JSON type returns
        an entry error. SDK convenience builders may type valid entries as IngestCommand, but server envelope
        validation must not reject the entire batch for an invalid entry.
    BatchItem:
      type: object
      additionalProperties: false
      properties:
        index:
          type: integer
          minimum: 0
        receipt:
          $ref: '#/components/schemas/Receipt'
        error:
          $ref: '#/components/schemas/Error'
      required:
      - index
      if:
        required:
        - receipt
      then:
        not:
          required:
          - error
      else:
        required:
        - error
    BatchResult:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BatchItem'
          maxItems: 100
      required:
      - items
    Record:
      type: object
      additionalProperties: false
      properties:
        record_id:
          type: string
          minLength: 1
        source:
          $ref: '#/components/schemas/SourceIdentity'
        withdrawn:
          type: boolean
        current_version_id:
          type: string
          minLength: 1
      required:
      - record_id
      - source
      - withdrawn
    Version:
      type: object
      additionalProperties: false
      properties:
        record_id:
          type: string
          minLength: 1
        version_id:
          type: string
          minLength: 1
        accepted_at:
          type: string
          format: date-time
          description: When Quivr accepted the revision this Version publishes, before any processing.
        manifest:
          $ref: '#/components/schemas/ManifestContent'
        extensions:
          $ref: '#/components/schemas/Extensions'
        provenance:
          $ref: '#/components/schemas/Provenance'
        availability:
          $ref: '#/components/schemas/Availability'
        relations:
          type: array
          items:
            $ref: '#/components/schemas/ResolvedRelation'
        processing:
          $ref: '#/components/schemas/ProcessingSummary'
        steps:
          $ref: '#/components/schemas/VersionSteps'
        diagnostics:
          type: array
          items:
            $ref: '#/components/schemas/Diagnostic'
          maxItems: 20
          description: Why the Version needs attention. A quarantined Version lists its reason first. A
            Version published through an optional route's fallback lists the normalizer failure it fell
            back from, and a recorded normalizer_conflict is listed on the Version whose output was kept.
            Omitted when there is nothing to report.
      required:
      - record_id
      - version_id
      - manifest
      - availability
      - relations
      - processing
    VersionSteps:
      type: object
      additionalProperties: false
      description: When each processing step of the Version finished, written once by the transaction that
        commits the step. A step not finished yet is omitted. Versions materialized before step times were
        recorded carry only accepted_at, and withdrawn_at for a withdrawal after; history is not reconstructed.
      properties:
        accepted_at:
          type: string
          format: date-time
          description: Quivr accepted the revision.
        materialized_at:
          type: string
          format: date-time
          description: The Version was published from normalized content.
        segmented_at:
          type: string
          format: date-time
          description: The Version was first cut into segments.
        retrieval_ready_at:
          type: string
          format: date-time
          description: The Version first became searchable.
        enriched_at:
          type: string
          format: date-time
          description: Vectors were first attached to the Version.
        evaluated_at:
          type: string
          format: date-time
          description: Every Subscription asked to evaluate the Version had decided; one that waits for
            vectors decides on their round. Omitted when no Subscription evaluated it, or when one waiting
            for vectors was disabled before they arrived. With more than 100
            Subscriptions on one Corpus it can be set once the first 100 have decided.
        quarantined_at:
          type: string
          format: date-time
          description: The Version was quarantined.
        withdrawn_at:
          type: string
          format: date-time
          description: The Version's Record was withdrawn.
    AdminDocument:
      type: object
      additionalProperties: false
      properties:
        version_id:
          type: string
          minLength: 1
        record_id:
          type: string
          minLength: 1
        corpus_id:
          type: string
          minLength: 1
        source_namespace:
          type: string
        record_key:
          type: string
        title:
          type: string
          description: The inline title Part of the accepted command, truncated to 200 characters; omitted
            when there is none.
        state:
          type: string
          enum:
          - received
          - materialized
          - building_baseline
          - retrieval_ready
          - quarantined
          - withdrawn
          description: received until the Version is materialized, then its Version Availability state, and
            withdrawn once its Record is.
        is_current:
          type: boolean
        steps:
          $ref: '#/components/schemas/VersionSteps'
        evaluation:
          type: string
          enum:
          - applicable
          - not_applicable
          description: Whether alert evaluation applies to the Version. applicable when it was evaluated
            (steps.evaluated_at), an evaluation of it is pending, or an enabled Subscription covers its Corpus
            at the time of the read; not_applicable otherwise, so no evaluated step is coming. Judged at read
            time, not when the Version became searchable; a Subscription created, re-enabled or widened to
            the Corpus since makes an older Version applicable although it never evaluates it.
      required:
      - version_id
      - record_id
      - corpus_id
      - source_namespace
      - record_key
      - state
      - is_current
      - steps
      - evaluation
    AdminDocumentPage:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AdminDocument'
        next_page_cursor:
          type: string
          minLength: 1
      required:
      - items
    TimelineStep:
      type: object
      additionalProperties: false
      properties:
        step:
          type: string
          enum:
          - accepted
          - materialized
          - segmented
          - retrieval_ready
          - enriched
          - evaluated
          - quarantined
          - withdrawn
        at:
          type: string
          format: date-time
        since:
          type: string
          description: The step the duration is measured from. Each step is timed from the step that causes
            it; enriched and evaluated both follow retrieval_ready, and quarantined follows the latest step
            finished before it. Omitted for accepted and withdrawn, and when that step has no time or a later
            one.
        duration_ms:
          type: integer
          minimum: 0
        plugin_id:
          type: string
          description: The plugin that ran the step, when known. materialized names the normalizer whose
            output was published; segmented, retrieval_ready and enriched name the ingestion plugin whose
            segments the Corpus serves.
        plugin_version:
          type: string
      required:
      - step
      - at
    DocumentTimeline:
      type: object
      additionalProperties: false
      properties:
        document:
          $ref: '#/components/schemas/AdminDocument'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/TimelineStep'
      required:
      - document
      - steps
    UploadRequest:
      type: object
      additionalProperties: false
      properties:
        size_bytes:
          type: integer
          minimum: 1
          maximum: 1073741824
        sha256:
          type: string
          pattern: ^[a-f0-9]{64}$
        media_type:
          type: string
          minLength: 1
      required:
      - size_bytes
      - sha256
      - media_type
    Upload:
      type: object
      additionalProperties: false
      properties:
        upload_id:
          type: string
          minLength: 1
        state:
          type: string
          enum:
          - awaiting_upload
          - verifying
          - verified
          - rejected
          - expired
        upload_url:
          type: string
          format: uri
        upload_headers:
          type: object
          additionalProperties:
            type: string
        expires_at:
          type: string
          format: date-time
        blob_id:
          type: string
          minLength: 1
        error:
          $ref: '#/components/schemas/Error'
        upload_method:
          type: string
          enum:
          - PUT
      required:
      - upload_id
      - state
      description: Upload URL and headers are transfer capabilities. Only verified uploads expose a usable
        Blob ID. Repeated confirmation of the same session observes the same verification, never a second
        upload.
      allOf:
      - if:
          properties:
            state:
              const: verified
        then:
          required:
          - blob_id
        else:
          not:
            required:
            - blob_id
    Blob:
      type: object
      additionalProperties: false
      properties:
        blob_id:
          type: string
          minLength: 1
        size_bytes:
          type: integer
          minimum: 1
        sha256:
          type: string
          pattern: ^[a-f0-9]{64}$
        media_type:
          type: string
          minLength: 1
      required:
      - blob_id
      - size_bytes
      - sha256
      - media_type
    PluginActivationRequest:
      type: object
      additionalProperties: false
      properties:
        idempotency_key:
          type: string
          minLength: 1
          maxLength: 200
    OperationAdmin:
      type: object
      additionalProperties: false
      description: Routing command target and successful cutover result. Administrative Operations have no corpus_id and require plugins:admin to follow. Their kinds are vector_space_promotion, plugin_activation and plugin_rollback.
      properties:
        target:
          type: string
        plan_id:
          type: string
        previous_plan_id:
          type: string
        served_space_id:
          type: string
        previous_space_id:
          type: string
    Operation:
      type: object
      additionalProperties: false
      properties:
        operation_id:
          type: string
          minLength: 1
        kind:
          type: string
          minLength: 1
        state:
          type: string
          enum:
          - queued
          - running
          - paused
          - succeeded
          - failed
          - cancel_requested
          - canceled
        progress:
          type: number
          minimum: 0
          maximum: 1
          description: Approximate fraction, omitted when unknown.
        counters:
          type: object
          additionalProperties:
            type: integer
            minimum: 0
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          maxItems: 20
        previous_operation_id:
          type: string
          minLength: 1
        corpus_id:
          type: string
          minLength: 1
        result:
          $ref: '#/components/schemas/ProjectionRebuildResult'
        admin:
          $ref: '#/components/schemas/OperationAdmin'
        backfill:
          $ref: '#/components/schemas/OperationBackfill'
        quarantine_reprocess:
          $ref: '#/components/schemas/OperationQuarantineReprocess'
      required:
      - operation_id
      - kind
      - state
      - counters
      - errors
      description: Administrative execution only. Retries keep identity. Intentional terminal rerun has
        a new ID and previous_operation_id. Cancellation does not promise universal rollback; already-terminal
        state and racing completion may win. projection_rebuild, retrieval_configuration and backfill
        Operations require corpus_id; when succeeded they require result naming the activated logical
        generation, or for a backfill the generation it filled. A backfill also carries backfill, and its
        counters versions_in_scope, versions_done, versions_skipped (with skipped_<reason>) and segments.
        A quarantine_reprocess carries corpus_id and quarantine_reprocess, and its counters
        versions_in_scope, versions_recovered, versions_quarantined and versions_skipped (with
        skipped_<reason>); it has no result. Only a backfill and a quarantine_reprocess can be paused.
        vector_space_promotion, plugin_activation and plugin_rollback carry admin, with no corpus_id.
        Their counters records_scanned, versions_missing and segments_missing describe the preflight;
        required_missing excludes gaps retained from an earlier rollback. Success publishes routing;
        rollback recovery continues in the background after success.
      if:
        properties:
          kind:
            enum:
            - projection_rebuild
            - retrieval_configuration
            - backfill
        required:
        - kind
      then:
        required:
        - corpus_id
        if:
          properties:
            state:
              const: succeeded
          required:
          - state
        then:
          required:
          - result
    FieldMapping:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
        source_pointer:
          type: string
          minLength: 1
        type:
          type: string
          enum:
          - string
          - number
          - boolean
          - datetime
          - string_array
        boost:
          type: integer
          minimum: 1
          maximum: 100
          default: 1
          description: Positive integer BM25F weight, allowed only with the search role. For ratios 3/2/2/1.5/1 use 6/4/4/3/2.
        analyzer:
          type: string
          enum: [folded, french_light]
          description: Keyword analyzer for a separate copy of the field, also applied to queries. folded lowercases and folds accents and ligatures in any language; french_light also removes French stopwords and lightly stems. Omit for no copy; canonical text and vectors are unchanged.
        part_role:
          type: string
          enum: [title, body, caption, transcript]
          description: Collect canonical text Parts of this role instead of source_pointer. Requires the search role.
        part_key_prefix:
          type: string
          maxLength: 200
          description: Optional key prefix to narrow part_role, for example slugline-.
        value_pointer:
          type: string
          minLength: 1
          description: For a string_array source, select this JSON Pointer from each array entry and flatten its string or string-array values.
        roles:
          type: array
          items:
            type: string
            enum:
            - search
            - filter
          minItems: 1
      required:
      - name
      - type
      - roles
      description: v0 logical field mapping. name is a logical name matching ^[a-z][a-z0-9_]{0,63}$,
        never a search-engine field name. source_pointer is an RFC 6901 JSON Pointer into the canonical
        source view of a Version, rooted at /manifest, /provenance or /extensions/{namespace} with a
        declared namespace (built in, or owned by the startup-pinned plugin); other roots are rejected
        as invalid_mapping. Exactly one of source_pointer and part_role is required; Core validates this as invalid_mapping, along with
        role/type compatibility (search requires string or string_array). A search field named title
        replaces the projected title; other search fields add text once per Record Version. Filter roles are consumed by SearchFilter.metadata. New generations index each search field once per item with its boost; older generations retain passage scoring until rebuilt.
    RetrievalConfig:
      type: object
      additionalProperties: false
      properties:
        plugin_profile:
          type: string
          minLength: 1
        fields:
          type: array
          items:
            $ref: '#/components/schemas/FieldMapping'
      required: []
      description: Pin a plugin-provided profile when resolving config. Explicit fields override default
        fields by logical name; unmapped source data remains preserved. getCorpus returns the effective
        resolved fields. The only built-in profile, example.editorial, is illustrative (paired with the example
        extension namespace), not a product default; an uninstalled profile is 422 unsupported_profile.
    ConnectorKind:
      type: string
      pattern: ^[a-z][a-z0-9_]{0,31}$
      description: Connector kind, provided by a pinned connector plugin; listConnectorKinds
        lists the kinds this deployment accepts. First-party connector plugins provide rss (RSS 2.0,
        RSS 1.0, Atom and JSON Feed documents; config url, optional honor_ttl; optional credential
        username+password or token), x_list (an X list) and m365_mail (Microsoft 365 mailboxes). Another kind is
        refused with 422 unsupported_connector_kind.
    CredentialDeposit:
      type: object
      additionalProperties: false
      properties:
        secret:
          type: object
          writeOnly: true
          description: Kind-specific secret, validated by the kind's credential JSON Schema, encrypted at
            rest with the deployment credential key and never returned or logged. Without a configured
            credential key the request is refused with 503 credentials_unavailable.
        expires_at:
          type: string
          format: date-time
      required:
      - secret
    CredentialReplace:
      type: object
      additionalProperties: false
      properties:
        idempotency_key:
          type: string
          minLength: 1
        secret:
          type: object
          writeOnly: true
        expires_at:
          type: string
          format: date-time
      required:
      - idempotency_key
      - secret
    ConnectorSchedule:
      type: object
      additionalProperties: false
      properties:
        interval_seconds:
          type: integer
          minimum: 1
          maximum: 86400
          description: Polling interval. Defaults to the kind's declared interval (rss 300, m365_mail 60, x_list 120);
            values below the deployment floor (30 s by default) are 422 invalid_interval.
    ConnectorRunRequest:
      type: object
      additionalProperties: false
      properties:
        connector_id:
          type: string
        run_at:
          type: string
          format: date-time
          description: When the requested run is due; now unless the interval floor or the source's
            Retry-After defers it.
      required:
      - connector_id
      - run_at
    ScheduleChange:
      type: object
      additionalProperties: false
      properties:
        interval_seconds:
          type: integer
          description: Seconds between runs. Bounds are the deployment floor and 86400; values outside
            them are 422 invalid_interval with field /interval_seconds.
      required:
      - interval_seconds
    ConnectorKindDescription:
      type: object
      additionalProperties: false
      properties:
        kind:
          type: string
          minLength: 1
          description: Kind identifier accepted by createConnector for this deployment. A plain string so kinds
            added by future providers need no contract change here.
        title:
          type: string
          minLength: 1
          description: Display name, from the config schema's title annotation (the kind when absent).
        description:
          type: string
          description: Short explanation, from the config schema's description annotation.
        config_schema:
          type: object
          description: JSON Schema (2020-12) validating config. Annotations (title, description, examples)
            are informational.
        credential_schema:
          type: object
          description: JSON Schema validating credential.secret. Members annotated writeOnly are secrets.
            Absent when the kind takes no credential.
        credential:
          type: string
          enum:
          - none
          - optional
          - required
          description: Whether an instance of this kind takes, may take or needs a Deposited Credential.
        default_interval_seconds:
          type: integer
          minimum: 1
      required:
      - kind
      - title
      - config_schema
      - credential
      - default_interval_seconds
    PluginRegistration:
      type: object
      additionalProperties: false
      properties:
        registration_id:
          type: string
          minLength: 1
        plugin_id:
          type: string
          minLength: 1
        version:
          type: string
          minLength: 1
        endpoint:
          type: string
          minLength: 1
          description: Base URL where the operator runs this plugin version.
        manifest_digest:
          type: string
          minLength: 1
        artifact_digest:
          type: string
          minLength: 1
          description: Artifact digest the plugin reports, recorded as information. Absent when it reports
            none.
        contributions:
          type: array
          items:
            type: string
        roles:
          type: array
          items:
            type: string
          description: Roles the manifest declares it can serve, such as normalizer:application/pdf,
            subscription:<plugin id> or connector:<kind>. The active plan says which it serves.
        state:
          type: string
          enum:
          - registered
          - validated
          - active
          - draining
          - inactive
          - rejected
          description: registered while the Contract Runner checks it, then validated or rejected; active
            while the active plan names it. Once a later plan leaves it out it is draining while
            pinned_work or subscriptions is above zero, then inactive.
        pinned_work:
          type: integer
          minimum: 0
          description: Unfinished work pinned to a Pipeline Plan that names this registration, such as the
            processing of a receipt, a connector run or a rebuild. Work finishes on the plan it started
            on, so a registration a plan change left out keeps being called until this reaches zero. For an
            alert-rule plugin it also counts the pending evaluations of Subscription Versions that pin its
            version.
        subscriptions:
          type: integer
          minimum: 0
          description: For an alert-rule plugin, the Subscriptions of every Organization that are not deleted,
            enabled or disabled, whose current Version pins this plugin version. They keep it until
            migrateSubscriptionEvaluators moves them; 0 for other plugins.
        check:
          $ref: '#/components/schemas/PluginCheckReport'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - registration_id
      - plugin_id
      - version
      - endpoint
      - manifest_digest
      - contributions
      - roles
      - state
      - pinned_work
      - subscriptions
      - created_at
      - updated_at
    PluginRegistrationRequest:
      type: object
      additionalProperties: false
      properties:
        idempotency_key:
          type: string
          minLength: 1
          maxLength: 200
        endpoint:
          type: string
          minLength: 1
          maxLength: 2048
          description: Base URL where the operator runs the plugin, such as http://127.0.0.1:9900. A connector
            plugin needs https unless it is on loopback.
        manifest:
          type: string
          minLength: 1
          maxLength: 262144
          description: The exact text of the quivr-plugin.yaml the plugin was built from; its sha256 must be
            the manifest digest the plugin's discovery reports.
        configuration:
          type: object
          description: Plugin configuration, validated against the manifest's configuration schema.
        routes:
          type: array
          maxItems: 100
          description: Media types routed to the plugin's normalizer.
          items:
            type: object
            additionalProperties: false
            properties:
              media_type:
                type: string
                minLength: 1
              mode:
                type: string
                enum:
                - required
                - optional
            required:
            - media_type
        kinds:
          type: array
          maxItems: 100
          description: Alert kinds offered, a subset of those the manifest declares; absent offers them all.
          items:
            type: string
            minLength: 1
        spaces:
          type: object
          description: Vector spaces of an ingestion plugin by space id, served or evaluation; absent serves
            the only declared space.
          additionalProperties:
            type: string
            enum:
            - served
            - evaluation
        fixtures:
          type: object
          maxProperties: 100
          description: The plugin's own test files, by path inside its fixtures folder (such as events.json
            or inputs/events.csv), each base64-encoded; at most 4 MiB decoded in total. The check runs them
            as quivr plugin test runs that folder, so a connector, or a normalizer for a media type without a
            normative fixture, can be certified. They are stored with the registration; a new idempotency
            key for a rejected registration checks it again with that request's fixtures.
          propertyNames:
            minLength: 1
            maxLength: 255
          additionalProperties:
            type: string
            contentEncoding: base64
            maxLength: 5592408
      required:
      - idempotency_key
      - endpoint
      - manifest
    PluginCheckReport:
      type: object
      additionalProperties: false
      description: What the Contract Runner reported on a registration; certified plugins are validated.
      properties:
        certified:
          type: boolean
        checked_at:
          type: string
          format: date-time
        passed:
          type: integer
          minimum: 0
        failed:
          type: integer
          minimum: 0
        skipped:
          type: integer
          minimum: 0
        checks:
          type: array
          items:
            $ref: '#/components/schemas/PluginCheck'
      required:
      - certified
      - checked_at
      - passed
      - failed
      - skipped
      - checks
    PluginCheck:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          minLength: 1
        title:
          type: string
          minLength: 1
        contribution:
          type: string
          minLength: 1
        status:
          type: string
          enum:
          - pass
          - fail
          - skip
        fixture:
          type: string
          minLength: 1
          description: The fixture the check ran, such as fixtures/events.json, or a normative fixture
            prefixed with contracts:.
        issues:
          type: array
          items:
            $ref: '#/components/schemas/PluginIssue'
      required:
      - id
      - title
      - status
      - issues
    PluginIssue:
      type: object
      additionalProperties: false
      properties:
        code:
          type: string
          minLength: 1
        path:
          type: string
        message:
          type: string
          minLength: 1
      required:
      - code
      - message
    PluginRegistrationList:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/PluginRegistration'
      required:
      - items
    PipelinePlanRole:
      type: object
      additionalProperties: false
      properties:
        role:
          type: string
          minLength: 1
        registration_id:
          type: string
          minLength: 1
        plugin_id:
          type: string
          minLength: 1
        version:
          type: string
          minLength: 1
      required:
      - role
      - registration_id
      - plugin_id
      - version
    PipelinePlanList:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/PipelinePlan'
      required:
      - items
    BackfillRequest:
      type: object
      additionalProperties: false
      properties:
        idempotency_key:
          type: string
          minLength: 1
          maxLength: 200
        corpus_id:
          type: string
          minLength: 1
        accepted_after:
          type: string
          format: date-time
          description: Only Versions Quivr accepted at or after this time; absent, from the first.
        accepted_before:
          type: string
          format: date-time
          description: Only Versions Quivr accepted before this time; absent, up to now.
        registration_id:
          type: string
          minLength: 1
          description: The ingestion plugin registration to run; absent, the active plan's default. Any ingestion member of the active plan is accepted; a registration outside it is 409 registration_not_active.
        spaces:
          type: array
          minItems: 1
          maxItems: 8
          uniqueItems: true
          items:
            type: string
            minLength: 1
          description: The vector spaces to fill, which the plugin declares and the deployment serves or
            evaluates; absent, the deployment's evaluation spaces the plugin owns.
        dry_run:
          type: boolean
          description: true reports the estimate and records it; false starts the backfill a dry run with
            the same key and scope preceded.
        confirm_cost:
          type: boolean
          default: false
          description: Accept an estimated cost above the deployment's
            backfill.max_cost_without_confirmation.
      required:
      - idempotency_key
      - corpus_id
      - dry_run
    BackfillEstimate:
      type: object
      additionalProperties: false
      properties:
        registration_id:
          type: string
          minLength: 1
        spaces:
          type: array
          items:
            type: string
            minLength: 1
        versions:
          type: integer
          minimum: 0
          description: Versions in scope that miss a vector in a target space.
        segments:
          type: integer
          minimum: 0
          description: Their segments, which the plugin embeds.
        input_tokens:
          type: integer
          minimum: 0
          description: Estimated tokens the plugin embeds, one per four code points of segment text.
        estimated_seconds:
          type: number
          format: double
          minimum: 0
          description: How long the backfill should take, at the deployment's backfill.rate or the recent
            throughput, whichever is slower.
        duration_basis:
          type: string
          enum:
          - rate
          - recent_backfills
          - recent_plugin_calls
          description: What the duration comes from.
        estimated_cost_usd:
          type: number
          format: double
          minimum: 0
          description: Estimated cost in US dollars, rounded up to the cent, of the target spaces that declare
            an input_price in the plugin manifest; a space without one adds nothing. Absent when none declares
            one, so the cost is unknown.
        confirmation_required:
          type: boolean
          description: The cost exceeds backfill.max_cost_without_confirmation, so starting the backfill
            needs confirm_cost.
      required:
      - registration_id
      - spaces
      - versions
      - segments
      - input_tokens
      - estimated_seconds
      - duration_basis
      - confirmation_required
    OperationBackfill:
      type: object
      additionalProperties: false
      description: What a backfill fills and how far it got.
      properties:
        registration_id:
          type: string
          minLength: 1
        spaces:
          type: array
          items:
            type: string
            minLength: 1
        accepted_after:
          type: string
          format: date-time
        accepted_before:
          type: string
          format: date-time
        plan_id:
          type: string
          minLength: 1
          description: The Pipeline Plan the backfill is pinned to, once it started.
        checkpoint:
          type: string
          minLength: 1
          description: The last Version id it finished; it resumes after it, in Version id order.
        estimate:
          $ref: '#/components/schemas/BackfillEstimate'
      required:
      - registration_id
      - spaces
      - estimate
    QuarantinedVersion:
      type: object
      additionalProperties: false
      description: A Record Version stuck in quarantine.
      properties:
        version_id:
          type: string
          minLength: 1
        record_id:
          type: string
          minLength: 1
        corpus_id:
          type: string
          minLength: 1
        receipt_id:
          type: string
          minLength: 1
        stage:
          type: string
          enum:
          - normalization
          - ingestion
          description: The step it failed at, which a reprocess reruns. normalization - its normalizer
            failed or its route was removed, and it was published with its submitted input; ingestion - its
            segmentation through the ingestion plugin was refused or stopped.
        reason:
          $ref: '#/components/schemas/Diagnostic'
        quarantined_at:
          type: string
          format: date-time
      required:
      - version_id
      - record_id
      - corpus_id
      - receipt_id
      - stage
      - reason
      - quarantined_at
    QuarantinePage:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/QuarantinedVersion'
        next_page_cursor:
          type: string
          minLength: 1
          description: Present while more Versions may follow.
      required:
      - items
    QuarantineReprocessRequest:
      type: object
      additionalProperties: false
      properties:
        idempotency_key:
          type: string
          minLength: 1
          maxLength: 200
        corpus_id:
          type: string
          minLength: 1
        plugin:
          type: string
          minLength: 1
          description: Only Versions whose quarantine reason names this plugin id.
        code:
          type: string
          minLength: 1
          description: Only Versions quarantined with this reason code.
        quarantined_after:
          type: string
          format: date-time
          description: Only Versions quarantined at or after this time.
        quarantined_before:
          type: string
          format: date-time
          description: Only Versions quarantined before this time.
        from_stage:
          type: string
          enum: [normalization]
          x-enum-varnames: [QuarantineReprocessRequestFromStageNormalization]
          description: Restart from the stored source Blob through normalization, then ingestion. Omit to
            retry the step that failed. Inputs that cannot be republished stay quarantined and are skipped.
        dry_run:
          type: boolean
          description: true reports the count and records it; false starts the reprocess a dry run with the
            same key and scope preceded.
      required:
      - idempotency_key
      - corpus_id
      - dry_run
    QuarantineReprocessEstimate:
      type: object
      additionalProperties: false
      properties:
        versions:
          type: integer
          minimum: 0
          description: Stuck Versions in scope.
        stages:
          type: object
          description: Of them, how many failed at each step.
          properties:
            normalization:
              type: integer
              minimum: 0
            ingestion:
              type: integer
              minimum: 0
          required:
          - normalization
          - ingestion
          additionalProperties: false
        codes:
          type: object
          description: Of them, how many by reason code.
          additionalProperties:
            type: integer
            minimum: 0
      required:
      - versions
      - stages
      - codes
    OperationQuarantineReprocess:
      type: object
      additionalProperties: false
      description: What a quarantine reprocess covers, the plan it runs with and the dry run it followed.
      properties:
        plugin:
          type: string
          minLength: 1
        code:
          type: string
          minLength: 1
        quarantined_after:
          type: string
          format: date-time
        quarantined_before:
          type: string
          format: date-time
        from_stage:
          type: string
          enum: [normalization]
          x-enum-varnames: [OperationQuarantineReprocessFromStageNormalization]
          description: The requested restart stage; omitted when retrying the failed step.
        plan_id:
          type: string
          minLength: 1
          description: The Pipeline Plan it runs with, the one active when it was accepted.
        estimate:
          $ref: '#/components/schemas/QuarantineReprocessEstimate'
      required:
      - plan_id
      - estimate
    VectorSpacePromotionRequest:
      type: object
      additionalProperties: false
      properties:
        idempotency_key:
          type: string
          minLength: 1
          maxLength: 200
        force:
          type: boolean
          default: false
          description: Promote even though some current segments have no vector in the space; those lose
            their semantic hits until a backfill fills them.
    VectorSpacePromotion:
      type: object
      additionalProperties: false
      properties:
        served_space_id:
          type: string
          minLength: 1
        previous_space_id:
          type: string
          description: The space it replaced, now for evaluation; empty when none was served.
        generations_switched:
          type: integer
          minimum: 0
          description: Generations that now serve the space.
        corpora_incomplete:
          type: integer
          minimum: 0
          description: Corpora whose routed generation lacks the space or a vector in it.
        segments_missing:
          type: integer
          minimum: 0
          description: Current segments without a vector in the space.
      required:
      - served_space_id
      - previous_space_id
      - generations_switched
      - corpora_incomplete
      - segments_missing
    SubscriptionEvaluatorMigrationRequest:
      type: object
      additionalProperties: false
      properties:
        plugin_id:
          type: string
          minLength: 1
          maxLength: 256
          description: The alert-rule plugin, such as alerts.
        from_version:
          type: string
          minLength: 1
          maxLength: 256
          description: The version the Subscriptions to move pin now.
        dry_run:
          type: boolean
          description: true validates and lists what would move, without moving anything.
        limit:
          type: integer
          minimum: 1
          maximum: 500
          default: 100
          description: The most Subscriptions this call looks at.
        after:
          type: string
          minLength: 1
          description: Continue after this Subscription id, the next_after of the previous call.
      required:
      - plugin_id
      - from_version
      - dry_run
    SubscriptionEvaluatorMigration:
      type: object
      additionalProperties: false
      properties:
        plugin_id:
          type: string
        from_version:
          type: string
        to_version:
          type: string
          description: The version the active plan serves, which moved Subscriptions pin.
        dry_run:
          type: boolean
        moved:
          type: array
          description: The Subscriptions moved, or that would move in a dry run.
          items:
            $ref: '#/components/schemas/SubscriptionEvaluatorMove'
        refused:
          type: array
          description: The Subscriptions left on from_version. code is invalid_expression or
            invalid_subscription_configuration when the served version's schemas refuse them (field and
            message name the first issue), or subscription_changed when the Subscription got another Version
            during the call.
          items:
            $ref: '#/components/schemas/SubscriptionEvaluatorRefusal'
        next_after:
          type: string
          description: Present when more Subscriptions may pin from_version; pass it as after.
      required:
      - plugin_id
      - from_version
      - to_version
      - dry_run
      - moved
      - refused
    SubscriptionEvaluatorMove:
      type: object
      additionalProperties: false
      properties:
        subscription_id:
          type: string
        from_version_id:
          type: string
          description: The Subscription Version that pinned from_version.
        version_id:
          type: string
          description: The new current Subscription Version; absent in a dry run.
      required:
      - subscription_id
      - from_version_id
    SubscriptionEvaluatorRefusal:
      type: object
      additionalProperties: false
      properties:
        subscription_id:
          type: string
        version_id:
          type: string
          description: Its current Subscription Version, which keeps from_version.
        code:
          type: string
        field:
          type: string
        message:
          type: string
      required:
      - subscription_id
      - version_id
      - code
    PipelinePlanRollbackRequest:
      type: object
      additionalProperties: false
      properties:
        idempotency_key:
          type: string
          minLength: 1
          maxLength: 200
        plan_id:
          type: string
          minLength: 1
          description: The plan whose roles become active again; absent returns to the plan the active
            one replaced (its previous_plan_id).
        pinned_work:
          type: string
          enum:
          - drain
          - stop
          default: drain
          description: What happens to work pinned to a plan naming a plugin version the rollback takes out.
            drain lets it finish on that version, which stays draining meanwhile. stop keeps it from calling
            that version again once each process follows the new plan (within plugin_plan_poll). Its next
            call fails instead. The processing of a Version then stops with the diagnostic pinned_plan_stopped,
            with the outcome of pinned_plugin_unavailable, and a rebuild fails with that code. A connector run
            fails as when its plugin is unavailable, and its next run uses the active plan.
      required:
      - idempotency_key
    PipelinePlan:
      type: object
      additionalProperties: false
      properties:
        plan_id:
          type: string
          minLength: 1
        created_at:
          type: string
          format: date-time
        activated_at:
          type: string
          format: date-time
        source:
          type: string
          enum:
          - configuration
          - activation
          - rollback
          description: What recorded the plan, and so why the plan changed. configuration is the startup
            configuration, which applies the roles its pins changed since it last applied, even over an
            earlier activation of the same role. activation is an operator activation. rollback is an
            operator rollback to an earlier plan's roles.
        previous_plan_id:
          type: string
          minLength: 1
          description: The plan this one replaced; absent for the first plan of the deployment.
        roles:
          type: array
          description: One entry per role, sorted by role.
          items:
            $ref: '#/components/schemas/PipelinePlanRole'
      required:
      - plan_id
      - created_at
      - activated_at
      - source
      - roles
    ActivePluginList:
      type: object
      additionalProperties: false
      properties:
        plan_activated_at:
          type: string
          format: date-time
          description: When the active plan was activated; absent when no plan is active.
        items:
          type: array
          description: One entry per plugin version in the plan, sorted by plugin id then version.
          items:
            $ref: '#/components/schemas/ActivePlugin'
      required:
      - items
    ActivePlugin:
      type: object
      additionalProperties: false
      properties:
        plugin_id:
          type: string
          minLength: 1
        version:
          type: string
          minLength: 1
        roles:
          type: array
          description: The plan's roles this version serves, sorted, for example ingestion, retrieval, normalizer:<media
            type>, subscription:<plugin id> or connector:<kind>.
          items:
            type: string
            minLength: 1
      required:
      - plugin_id
      - version
      - roles
    StatsSummary:
      type: object
      additionalProperties: false
      description: A series over the whole window. Latencies are in milliseconds and present only when count
        is positive.
      properties:
        count:
          type: integer
          minimum: 0
        errors:
          type: integer
          minimum: 0
        p50_ms:
          type: number
          minimum: 0
        p95_ms:
          type: number
          minimum: 0
        mean_ms:
          type: number
          minimum: 0
        last_error_code:
          type: string
          minLength: 1
        last_error_at:
          type: string
          format: date-time
      required:
      - count
      - errors
    StatsPoint:
      type: object
      additionalProperties: false
      description: One non-empty bucket, starting at start and lasting the list's resolution_seconds.
      properties:
        start:
          type: string
          format: date-time
        count:
          type: integer
          minimum: 1
        errors:
          type: integer
          minimum: 0
        p50_ms:
          type: number
          minimum: 0
        p95_ms:
          type: number
          minimum: 0
      required:
      - start
      - count
      - errors
      - p50_ms
      - p95_ms
    PluginCallStats:
      type: object
      additionalProperties: false
      properties:
        plugin_id:
          type: string
          minLength: 1
        plugin_version:
          type: string
          minLength: 1
        operation:
          type: string
          enum:
          - normalize
          - segment_and_embed
          - embed_query
          - search_round
          - connector_fetch
          - connector_receive
          - check_credential
          - describe_attachment
          - upload_attachment
          - evaluate_subscription
        summary:
          $ref: '#/components/schemas/StatsSummary'
        points:
          type: array
          description: Non-empty buckets, oldest first.
          items:
            $ref: '#/components/schemas/StatsPoint'
      required:
      - plugin_id
      - plugin_version
      - operation
      - summary
      - points
    SearchStats:
      type: object
      additionalProperties: false
      properties:
        mode:
          type: string
          enum:
          - lexical
          - semantic
          - hybrid
        profile:
          type: string
          minLength: 1
        results:
          type: integer
          minimum: 0
          description: Results returned by these searches in total.
        over_objective:
          type: integer
          minimum: 0
          description: Searches that took longer than the profile's latency objective, its max_latency_ms. They
            still answered.
        summary:
          $ref: '#/components/schemas/StatsSummary'
        points:
          type: array
          description: Non-empty buckets, oldest first.
          items:
            $ref: '#/components/schemas/StatsPoint'
      required:
      - mode
      - profile
      - results
      - over_objective
      - summary
      - points
    StepStats:
      type: object
      additionalProperties: false
      properties:
        step:
          type: string
          minLength: 1
        summary:
          $ref: '#/components/schemas/StatsSummary'
        points:
          type: array
          description: Non-empty buckets, oldest first.
          items:
            $ref: '#/components/schemas/StatsPoint'
      required:
      - step
      - summary
      - points
    PluginCallStatsList:
      type: object
      additionalProperties: false
      properties:
        window:
          $ref: '#/components/schemas/StatsWindowName'
        resolution_seconds:
          type: integer
          minimum: 1
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        items:
          type: array
          items:
            $ref: '#/components/schemas/PluginCallStats'
      required:
      - window
      - resolution_seconds
      - from
      - to
      - items
    SearchStatsList:
      type: object
      additionalProperties: false
      properties:
        window:
          $ref: '#/components/schemas/StatsWindowName'
        resolution_seconds:
          type: integer
          minimum: 1
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        items:
          type: array
          items:
            $ref: '#/components/schemas/SearchStats'
      required:
      - window
      - resolution_seconds
      - from
      - to
      - items
    StepStatsList:
      type: object
      additionalProperties: false
      properties:
        window:
          $ref: '#/components/schemas/StatsWindowName'
        resolution_seconds:
          type: integer
          minimum: 1
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        items:
          type: array
          items:
            $ref: '#/components/schemas/StepStats'
      required:
      - window
      - resolution_seconds
      - from
      - to
      - items
    CountPoint:
      type: object
      additionalProperties: false
      description: One non-empty bucket, starting at start and lasting the list's resolution_seconds.
      properties:
        start:
          type: string
          format: date-time
        count:
          type: integer
          minimum: 1
      required:
      - start
      - count
    ReceivedStats:
      type: object
      additionalProperties: false
      properties:
        source_namespace:
          type: string
          minLength: 1
        count:
          type: integer
          minimum: 1
        points:
          type: array
          description: Non-empty buckets, oldest first.
          items:
            $ref: '#/components/schemas/CountPoint'
      required:
      - source_namespace
      - count
      - points
    ReceivedStatsList:
      type: object
      additionalProperties: false
      properties:
        window:
          $ref: '#/components/schemas/StatsWindowName'
        resolution_seconds:
          type: integer
          minimum: 1
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        total:
          type: integer
          minimum: 0
          description: Documents received from every source namespace, listed or not.
        sources:
          type: integer
          minimum: 0
          description: Source namespaces that received at least one document, listed or not.
        items:
          type: array
          description: Most documents first.
          items:
            $ref: '#/components/schemas/ReceivedStats'
      required:
      - window
      - resolution_seconds
      - from
      - to
      - total
      - sources
      - items
    MatchStats:
      type: object
      additionalProperties: false
      properties:
        evaluator:
          type: string
          minLength: 1
          description: Plugin id of the evaluator of the Subscriptions that matched.
        count:
          type: integer
          minimum: 1
        points:
          type: array
          description: Non-empty buckets, oldest first.
          items:
            $ref: '#/components/schemas/CountPoint'
      required:
      - evaluator
      - count
      - points
    MatchStatsList:
      type: object
      additionalProperties: false
      properties:
        window:
          $ref: '#/components/schemas/StatsWindowName'
        resolution_seconds:
          type: integer
          minimum: 1
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        total:
          type: integer
          minimum: 0
          description: Matches of every evaluator.
        items:
          type: array
          description: Most Matches first.
          items:
            $ref: '#/components/schemas/MatchStats'
      required:
      - window
      - resolution_seconds
      - from
      - to
      - total
      - items
    StatsWindowName:
      type: string
      enum:
      - 1h
      - 24h
      - 7d
    TopQuery:
      type: object
      additionalProperties: false
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 200
        count:
          type: integer
          minimum: 1
        points:
          type: array
          description: Non-empty hourly buckets, oldest first.
          items:
            $ref: '#/components/schemas/CountPoint'
      required:
      - query
      - count
      - points
    TopQueryList:
      type: object
      additionalProperties: false
      properties:
        window:
          $ref: '#/components/schemas/StatsWindowName'
        resolution_seconds:
          type: integer
          minimum: 1
          description: Length of a bucket of points; query text is counted per hour.
        recording:
          type: boolean
          description: Whether this deployment records query text (observability.record_query_text).
        items:
          type: array
          description: Most frequent first.
          items:
            $ref: '#/components/schemas/TopQuery'
      required:
      - window
      - resolution_seconds
      - recording
      - items
    ConnectorKindCatalog:
      type: object
      additionalProperties: false
      properties:
        credential_deposits:
          type: string
          enum:
          - available
          - unavailable
          description: unavailable on a deployment without a credential key, where credential deposits and
            rotations are refused with 503 credentials_unavailable.
        min_interval_seconds:
          type: integer
          minimum: 1
          description: Shortest polling interval this deployment accepts.
        items:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorKindDescription'
      required:
      - credential_deposits
      - min_interval_seconds
      - items
    ConnectorHealthPolicy:
      type: object
      additionalProperties: false
      properties:
        silent_after_seconds:
          type: integer
          minimum: 1
          maximum: 2592000
          description: No new item for this long makes the source silent. Default 86400.
        credential_warning_seconds:
          type: integer
          minimum: 0
          maximum: 31536000
          description: A credential expiring within this window is credential_expiring. Default 1209600.
    ConnectorPushStats:
      type: object
      additionalProperties: false
      properties:
        connector_id: {type: string}
        outcome: {type: string, enum: [received, refused]}
        count: {type: integer, minimum: 0}
        points:
          type: array
          items: {$ref: '#/components/schemas/CountPoint'}
      required: [connector_id, outcome, count, points]
    ConnectorPushStatsList:
      type: object
      additionalProperties: false
      properties:
        window: {$ref: '#/components/schemas/StatsWindowName'}
        resolution_seconds: {type: integer, minimum: 1}
        from: {type: string, format: date-time}
        to: {type: string, format: date-time}
        total: {type: integer, minimum: 0}
        items:
          type: array
          items: {$ref: '#/components/schemas/ConnectorPushStats'}
      required: [window, resolution_seconds, from, to, total, items]
    ConnectorPushPolicy:
      type: object
      additionalProperties: false
      description: >-
        Engine-owned protection of declared source API routes, separate from plugin config.
        Missing fields inherit deployment defaults; configure at instance creation.
      properties:
        rate_per_second:
          type: number
          format: double
          minimum: 0.001
          maximum: 100000
          description: Token refill rate per second (deployment default 10).
        burst:
          type: integer
          minimum: 1
          maximum: 100000
          description: Token bucket capacity (deployment default 100).
        allowed_cidrs:
          type: array
          maxItems: 256
          items: {type: string, minLength: 1}
          description: Allowed IPv4/IPv6 CIDRs; absent or empty permits every address.
    QueueStatus:
      type: object
      additionalProperties: false
      properties:
        waiting: {type: integer, format: int64, minimum: 0}
        in_progress: {type: integer, format: int64, minimum: 0}
        oldest_waiting_age_seconds: {type: number, format: double, minimum: 0}
      required: [waiting, in_progress, oldest_waiting_age_seconds]
    QueueBacklog:
      type: object
      additionalProperties: false
      properties:
        queues:
          type: object
          additionalProperties: false
          properties:
            live: {$ref: '#/components/schemas/QueueStatus'}
            bulk: {$ref: '#/components/schemas/QueueStatus'}
          required: [live, bulk]
      required: [queues]
    ConnectorCreate:
      type: object
      additionalProperties: false
      properties:
        idempotency_key:
          type: string
          minLength: 1
        corpus_id:
          type: string
          minLength: 1
        source_namespace:
          type: string
          minLength: 1
          maxLength: 200
        kind:
          $ref: '#/components/schemas/ConnectorKind'
        push_policy:
          $ref: '#/components/schemas/ConnectorPushPolicy'
        work_queue:
          type: string
          enum: [live, bulk]
          description: Workload class for scheduled acquisition and its documents. Push deliveries always use live.
        config:
          type: object
          description: Kind-specific configuration validated by the kind's JSON Schema. Holds no secret.
        schedule:
          $ref: '#/components/schemas/ConnectorSchedule'
        health_policy:
          $ref: '#/components/schemas/ConnectorHealthPolicy'
        credential:
          $ref: '#/components/schemas/CredentialDeposit'
      required:
      - idempotency_key
      - corpus_id
      - source_namespace
      - kind
      - config
    CredentialMetadata:
      type: object
      additionalProperties: false
      properties:
        version:
          type: integer
          minimum: 1
        deposited_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
      required:
      - version
      - deposited_at
      description: Metadata of the current Deposited Credential; the secret itself is never returned.
    ConnectorError:
      type: object
      additionalProperties: false
      properties:
        code:
          type: string
          minLength: 1
        at:
          type: string
          format: date-time
      required:
      - code
      - at
    ConnectorUsage:
      type: object
      additionalProperties: false
      properties:
        day:
          type: string
          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
          description: Current UTC calendar day (YYYY-MM-DD).
        items_read:
          type: integer
          minimum: 0
          description: Source resources read during the current UTC day, counted as the source bills them
            (for x_list, an estimate of billed post reads after X's per-UTC-day deduplication).
        previous_day_items_read:
          type: integer
          minimum: 0
      required:
      - day
      - items_read
      - previous_day_items_read
      description: Per-UTC-day source read counters, present only for kinds that report reads.
    ConnectorHealth:
      type: object
      additionalProperties: false
      properties:
        state:
          type: string
          enum:
          - active
          - silent
          - access_error
          - credential_expiring
          - disabled
        evaluated_at:
          type: string
          format: date-time
        last_success_at:
          type: string
          format: date-time
        last_item_at:
          type: string
          format: date-time
        last_error:
          $ref: '#/components/schemas/ConnectorError'
        usage:
          $ref: '#/components/schemas/ConnectorUsage'
        diagnostics:
          type: object
          description: Kind-defined diagnostics from the latest acquisition page, documented on the kind's
            operator guide page (for x_list, the deletion recheck coverage). Informational; never holds a
            secret or source content.
        push:
          $ref: '#/components/schemas/ConnectorPush'
      required:
      - state
      - evaluated_at
      description: Last committed Connector Health, evaluated at each acquisition run, credential replacement
        and disable; evaluated_at shows its age. Precedence disabled, access_error, credential_expiring,
        silent, active. access_error means the source refused access (distinct from silent, which means
        no new item within the threshold), including a push channel refused access while polling carries
        the collection. Other failures appear only as last_error.
    ConnectorPush:
      type: object
      additionalProperties: false
      properties:
        state:
          type: string
          enum:
          - active
          - pending
          - degraded
          description: active, deliveries are expected; pending, the kind has not set its push channel up
            yet; degraded, the setup failed or deliveries fail or miss items, and polling at the instance's
            interval carries the collection.
        error:
          $ref: '#/components/schemas/ConnectorPushError'
        last_delivery_at:
          type: string
          format: date-time
          description: Last delivery the connector plugin accepted.
        poll_interval_seconds:
          type: integer
          minimum: 1
          description: While push is active, polling runs at most this often, as a safety net.
      required:
      - state
      description: Push delivery health, present once a kind that declares the push mode reports its push
        channel.
    ConnectorPushError:
      type: object
      additionalProperties: false
      properties:
        class:
          type: string
          enum:
          - access
          - transient
          - source
        code:
          type: string
          minLength: 1
          description: For example webhook_invalid (the source invalidated the webhook), plugin_unavailable
            (a delivery found the plugin down) or missed_deliveries (polling found items no delivery brought).
        at:
          type: string
          format: date-time
      required:
      - class
      - code
      - at
    Connector:
      type: object
      additionalProperties: false
      properties:
        connector_id:
          type: string
          minLength: 1
        corpus_id:
          type: string
          minLength: 1
        source_namespace:
          type: string
          minLength: 1
        kind:
          $ref: '#/components/schemas/ConnectorKind'
        push_policy:
          $ref: '#/components/schemas/ConnectorPushPolicy'
        work_queue:
          type: string
          enum: [live, bulk]
          description: Workload class for scheduled acquisition; push deliveries stay live.
        config:
          type: object
        schedule:
          type: object
          additionalProperties: false
          properties:
            interval_seconds:
              type: integer
              minimum: 1
          required:
          - interval_seconds
        health_policy:
          type: object
          additionalProperties: false
          properties:
            silent_after_seconds:
              type: integer
              minimum: 1
            credential_warning_seconds:
              type: integer
              minimum: 0
          required:
          - silent_after_seconds
          - credential_warning_seconds
        enabled:
          type: boolean
        created_at:
          type: string
          format: date-time
        disabled_at:
          type: string
          format: date-time
        paused_at:
          type: string
          format: date-time
          description: Present while scheduled acquisition is paused. Inbound push routes remain available.
        credential:
          $ref: '#/components/schemas/CredentialMetadata'
        health:
          $ref: '#/components/schemas/ConnectorHealth'
        webhook_url:
          type: string
          format: uri
          description: Public address of the instance's webhook route, present when its kind declares the
            push mode and the deployment sets public_url. The kind's plugin registers it with the source.
      required:
      - connector_id
      - corpus_id
      - source_namespace
      - kind
      - config
      - schedule
      - health_policy
      - enabled
      - created_at
      - health
    ConnectorPage:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Connector'
        next_page_cursor:
          type: string
          minLength: 1
      required:
      - items
    CorpusRequest:
      type: object
      additionalProperties: false
      properties:
        idempotency_key:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
        retrieval:
          $ref: '#/components/schemas/RetrievalConfig'
      required:
      - idempotency_key
      - name
    CorpusRenameRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: A nonblank corpus name without embedded NUL characters.
          minLength: 1
          maxLength: 256
      required: [name]
    Corpus:
      type: object
      additionalProperties: false
      properties:
        archived:
          type: boolean
          description: Reversible visibility fence; archived corpora retain all data.
        corpus_id:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
        effective_retrieval:
          $ref: '#/components/schemas/RetrievalConfig'
      required:
      - corpus_id
      - name
      - effective_retrieval
    VectorSpaceList:
      type: object
      additionalProperties: false
      properties:
        projection_generation_id:
          type: string
          minLength: 1
        segments:
          type: integer
          minimum: 0
          description: Background snapshot of segments the generation projects; zero before coverage is known. Counts may be stale.
        items:
          type: array
          items:
            $ref: '#/components/schemas/VectorSpace'
        coverage_unknown:
          type: boolean
          description: True until a background coverage snapshot completes; counts are placeholders.
        coverage_age_ms:
          type: integer
          minimum: 0
          description: Age of the background coverage snapshot. Counts may be stale during refresh or dependency failure.
      required:
      - projection_generation_id
      - segments
      - items
    VectorSpace:
      type: object
      additionalProperties: false
      properties:
        vector_space_id:
          type: string
          minLength: 1
          description: The space's identity, as search hits report it. A plugin space is <name>@<version>.
        name:
          type: string
          minLength: 1
        version:
          type: string
        owner:
          type: object
          additionalProperties: false
          properties:
            kind:
              type: string
              enum:
              - engine
              - plugin
            plugin_id:
              type: string
              minLength: 1
            plugin_version:
              type: string
              minLength: 1
          required:
          - kind
        model:
          type: string
        dimensions:
          type: integer
          minimum: 0
        metric:
          type: string
          enum:
          - cosine
          - dot
          - l2
        indexes:
          type: array
          items:
            type: string
        query_modalities:
          type: array
          items:
            type: string
        role:
          type: string
          enum:
          - served
          - evaluation
        coverage:
          type: object
          additionalProperties: false
          properties:
            segments:
              type: integer
              minimum: 0
            total_segments:
              type: integer
              minimum: 0
              description: Snapshot segments in this plugin's own projection; different plugins may cut the same Version differently.
            versions_covered:
              type: integer
              minimum: 0
              description: Snapshot eligible Versions whose entire projection has vectors in this space.
            unknown:
              type: boolean
              description: True until a background snapshot completes; counts are placeholders.
            age_ms:
              type: integer
              minimum: 0
              description: Age of this space's coverage snapshot. Coverage is informational and may be stale.
          required:
          - segments
      required:
      - vector_space_id
      - name
      - version
      - owner
      - model
      - dimensions
      - metric
      - indexes
      - query_modalities
      - role
      - coverage
    CorpusPage:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Corpus'
        next_page_cursor:
          type: string
          minLength: 1
      required:
      - items
    CorpusStats:
      type: object
      additionalProperties: false
      required: [corpus_id, total, catalog_total, undated_total, catalog_undated_total, observed_at, approximate, complete]
      properties:
        corpus_id: {type: string}
        total: {type: integer, format: int64, minimum: 0}
        catalog_total: {type: integer, format: int64, minimum: 0}
        undated_total: {type: integer, format: int64, minimum: 0}
        catalog_undated_total: {type: integer, format: int64, minimum: 0}
        first_catalog_hour:
          type: string
          format: date-time
          description: First occupied catalog UTC hour; not the exact first acceptance time. Absent for an undated or empty corpus.
        last_catalog_hour:
          type: string
          format: date-time
          description: Last occupied catalog UTC hour; not the exact last acceptance time.
        observed_at: {type: string, format: date-time}
        approximate: {type: boolean}
        complete: {type: boolean}
        histogram: {$ref: '#/components/schemas/CorpusStatsHistogram'}
        sources: {$ref: '#/components/schemas/CorpusStatsSources'}
    CorpusStatsHistogram:
      type: object
      additionalProperties: false
      required: [from, to, resolution_seconds, items]
      properties:
        from: {type: string, format: date-time}
        to: {type: string, format: date-time}
        resolution_seconds: {type: integer, enum: [3600, 86400]}
        items:
          type: array
          maxItems: 10000
          items:
            type: object
            additionalProperties: false
            required: [start, count, catalog_count]
            properties:
              start: {type: string, format: date-time}
              count: {type: integer, format: int64, minimum: 0}
              catalog_count: {type: integer, format: int64, minimum: 0}
        next_page_cursor: {type: string, minLength: 1}
    CorpusStatsSources:
      type: object
      additionalProperties: false
      required: [items]
      properties:
        items:
          type: array
          maxItems: 1000
          items:
            type: object
            additionalProperties: false
            required: [namespace, connector_id, count, catalog_count]
            properties:
              namespace: {type: string}
              connector_id:
                type: string
                description: Trusted accepting connector instance, or the explicit unknown bucket for historical/public submissions.
              count: {type: integer, format: int64, minimum: 0}
              catalog_count: {type: integer, format: int64, minimum: 0}
        next_page_cursor: {type: string, minLength: 1}
    RecordCount:
      type: object
      additionalProperties: false
      properties:
        count:
          type: integer
          format: int64
          minimum: 0
        observed_at: {type: string, format: date-time}
        approximate: {type: boolean}
        complete: {type: boolean}
      required:
      - count
    RecordPage:
      type: object
      additionalProperties: false
      properties:
        excluded_corpora:
          type: array
          items:
            $ref: '#/components/schemas/CorpusExclusion'
        items:
          type: array
          items:
            $ref: '#/components/schemas/Record'
        next_page_cursor:
          type: string
          minLength: 1
      required:
      - items
    ConfigUpdate:
      type: object
      additionalProperties: false
      properties:
        idempotency_key:
          type: string
          minLength: 1
        retrieval:
          $ref: '#/components/schemas/RetrievalConfig'
      required:
      - idempotency_key
      - retrieval
    ActionRequest:
      type: object
      additionalProperties: false
      properties:
        idempotency_key:
          type: string
          minLength: 1
      required:
      - idempotency_key
    RenameRequest:
      type: object
      additionalProperties: false
      properties:
        idempotency_key:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
      required:
      - idempotency_key
      - name
      description: New display name of a Saved Query or Subscription.
    EvaluationBacklogPage:
      type: object
      additionalProperties: false
      required:
      - items
      properties:
        items:
          type: array
          maxItems: 500
          items:
            $ref: '#/components/schemas/EvaluationCounts'
        next_after:
          type: string
          minLength: 1
    EvaluationCounts:
      type: object
      additionalProperties: false
      required:
      - plugin_id
      - version
      - pending
      - erroring
      - unavailable
      - retired
      properties:
        plugin_id:
          type: string
        version:
          type: string
        pending:
          type: integer
          minimum: 0
        erroring:
          type: integer
          minimum: 0
        unavailable:
          type: integer
          minimum: 0
        retired:
          type: integer
          minimum: 0
    EvaluationRetirementRequest:
      type: object
      additionalProperties: false
      required:
      - key
      - plugin_id
      - version
      - reason
      - dry_run
      properties:
        key:
          type: string
          minLength: 1
          maxLength: 128
        plugin_id:
          type: string
          minLength: 1
          maxLength: 128
        version:
          type: string
          minLength: 1
          maxLength: 128
        reason:
          type: string
          minLength: 1
          maxLength: 1024
          description: The operator's explanation for deliberately abandoning these evaluations.
        dry_run:
          type: boolean
        limit:
          type: integer
          minimum: 1
          maximum: 500
          default: 100
    EvaluationRetirement:
      type: object
      additionalProperties: false
      required:
      - key
      - plugin_id
      - version
      - reason
      - dry_run
      - limit
      - retirement_id
      - outcome
      - items
      - remaining
      - leased
      properties:
        key:
          type: string
        plugin_id:
          type: string
        version:
          type: string
        reason:
          type: string
        dry_run:
          type: boolean
        limit:
          type: integer
          minimum: 1
          maximum: 500
        retirement_id:
          type: string
          minLength: 1
        created_at:
          type: string
          format: date-time
        outcome:
          type: string
          enum:
          - evaluator_retired
        items:
          type: array
          maxItems: 500
          items:
            $ref: '#/components/schemas/RetiredEvaluation'
        remaining:
          type: integer
          minimum: 0
          description: Unavailable pending evaluations remaining in this request's scope, including leased ones.
        leased:
          type: integer
          minimum: 0
          description: Unavailable pending evaluations skipped because their leases have not expired.
    RetiredEvaluation:
      type: object
      additionalProperties: false
      required:
      - subscription_id
      - subscription_version_id
      - sequence
      - corpus_id
      - record_id
      - record_version_id
      properties:
        subscription_id:
          type: string
        subscription_version_id:
          type: string
        sequence:
          type: integer
          format: int64
          description: The original trigger's Organization journal position.
        corpus_id:
          type: string
        record_id:
          type: string
        record_version_id:
          type: string
        event_id:
          type: string
          minLength: 1
          description: The evaluation.retired event; absent for a dry run.
    ResourceReference:
      type: object
      additionalProperties: false
      properties:
        kind:
          type: string
          minLength: 1
        id:
          type: string
          minLength: 1
        corpus_id:
          type: string
          minLength: 1
      required:
      - kind
      - id
    ChangeEvent:
      type: object
      additionalProperties: false
      properties:
        event_id:
          type: string
          minLength: 1
        type:
          type: string
          minLength: 1
        schema_version:
          type: string
          minLength: 1
        occurred_at:
          type: string
          format: date-time
        resource:
          $ref: '#/components/schemas/ResourceReference'
        cursor:
          type: string
          minLength: 1
        monitoring:
          $ref: '#/components/schemas/MonitoringReferences'
      required:
      - event_id
      - type
      - schema_version
      - occurred_at
      - resource
      - cursor
      description: Every change to a Record catalog entry emits an event with resource.kind=record and
        resource.id=the affected Record ID. Additional resource-specific events do not replace this invalidation.
        Consumers reread current state; payload detail belongs to THE-547. Monitoring notice types mirror
        WebhookEvent and include monitoring references; event_id identifies that same committed notice.
        Delivery status changes emit delivery.updated events only to the feed, never recursive webhooks.
    ChangePage:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ChangeEvent'
        next_cursor:
          type: string
          minLength: 1
        has_more:
          type: boolean
      required:
      - items
      - next_cursor
      - has_more
    ResolvedRelation:
      type: object
      additionalProperties: false
      required:
      - source_reference
      - status
      properties:
        source_reference:
          $ref: '#/components/schemas/RelationInput'
        status:
          type: string
          enum:
          - available
          - unavailable
        target_record_id:
          type: string
        target_version_id:
          type: string
      description: Separate live view, not a mutation of the source Manifest. Unavailable covers missing,
        unready, withdrawn and inaccessible without distinguishing existence or revealing resolved target
        IDs.
      if:
        properties:
          status:
            const: available
      then:
        required:
        - target_record_id
        - target_version_id
      else:
        not:
          anyOf:
          - required:
            - target_record_id
          - required:
            - target_version_id
    ProcessingSummary:
      type: object
      additionalProperties: false
      required:
      - state
      properties:
        state:
          type: string
          enum:
          - queued
          - running
          - retrying
          - blocked
          - idle
        phase:
          type: string
          enum:
          - materialization
          - baseline
          - enrichment
        message:
          type: string
      description: Live read view, not a Receipt lifecycle or public workflow identifier. blocked means
        an outstanding contribution needs intervention; diagnostics describe why. idle means no work currently
        pending, not a promise of final enrichment. Phase is omitted when idle; required and optional
        progress do not override Version Availability.
    SavedQueryDefinition:
      type: object
      additionalProperties: false
      properties:
        corpus_ids:
          type: array
          items:
            type: string
            minLength: 1
          minItems: 1
          uniqueItems: true
        expression:
          type: object
          additionalProperties: true
        retrieval_profile:
          type: string
          minLength: 1
          description: A search profile the deployment answers (listSearchProfiles), recorded as sent;
            an unserved profile is 422 unsupported_profile. The profile is checked only when a definition is written, so a
            Version keeps its profile and keeps evaluating after the profile stops being served.
        temporal_policy:
          type: string
          enum:
          - from_activation
      required:
      - corpus_ids
      - expression
      - retrieval_profile
      - temporal_policy
      description: Immutable query definition. Expression semantics belong to the evaluator plugin; no
        core keyword or semantic threshold is implied. All Corpora belong to the authorized Organization.
    SavedQueryCreate:
      type: object
      additionalProperties: false
      properties:
        idempotency_key:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
        definition:
          $ref: '#/components/schemas/SavedQueryDefinition'
      required:
      - idempotency_key
      - name
      - definition
    SavedQueryVersionCreate:
      type: object
      additionalProperties: false
      properties:
        idempotency_key:
          type: string
          minLength: 1
        definition:
          $ref: '#/components/schemas/SavedQueryDefinition'
      required:
      - idempotency_key
      - definition
      description: New immutable definition of an existing Saved Query. The name is unchanged (rename
        changes it).
    SavedQueryVersion:
      type: object
      additionalProperties: false
      properties:
        saved_query_id:
          type: string
          minLength: 1
        version_id:
          type: string
          minLength: 1
        definition:
          $ref: '#/components/schemas/SavedQueryDefinition'
      required:
      - saved_query_id
      - version_id
      - definition
    SavedQuery:
      type: object
      additionalProperties: false
      properties:
        saved_query_id:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
        deleted:
          type: boolean
          description: Logically deleted; the Saved Query and its Versions stay readable.
        current_version:
          $ref: '#/components/schemas/SavedQueryVersion'
      required:
      - saved_query_id
      - name
      - deleted
      - current_version
    EvaluatorConfig:
      type: object
      additionalProperties: false
      properties:
        plugin_id:
          type: string
          minLength: 1
        version:
          type: string
          minLength: 1
        configuration:
          type: object
          additionalProperties: true
      required:
      - plugin_id
      - version
      - configuration
      description: Pins an installed evaluator by plugin id and version, and its configuration. Evaluators
        are the subscription Contributions of the plugins pinned at startup (Plugin Protocol v0). The
        configuration must satisfy the evaluator's declared configuration schema.
    SubscriptionCreate:
      type: object
      additionalProperties: false
      properties:
        idempotency_key:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
        saved_query_id:
          type: string
          minLength: 1
        saved_query_version_id:
          type: string
          minLength: 1
        evaluator:
          $ref: '#/components/schemas/EvaluatorConfig'
        destination_id:
          type: string
          minLength: 1
        owner:
          $ref: '#/components/schemas/SubscriptionOwner'
      required:
      - idempotency_key
      - name
      - saved_query_id
      - saved_query_version_id
      - evaluator
      description: Create enabled from-now Subscription. An optional owner makes it the Subscription of
        one end user of the client application; without one it is global to the Organization. The owner
        is fixed for the Subscription's life and part of the idempotent request. An optional deployment-configured destination per version
        belongs to this Organization. Omit destination_id to record Matches and change-feed notices
        without creating Deliveries or sending webhooks. URL and signing key are provisioned outside this API
        and not returned. No inline secret or dynamic destination registry in the tracer.
    SubscriptionVersionCreate:
      type: object
      additionalProperties: false
      properties:
        idempotency_key:
          type: string
          minLength: 1
        saved_query_version_id:
          type: string
          minLength: 1
        evaluator:
          $ref: '#/components/schemas/EvaluatorConfig'
        destination_id:
          type: string
          minLength: 1
      required:
      - idempotency_key
      - saved_query_version_id
      - evaluator
      description: New immutable configuration of an existing Subscription. The Saved Query and name
        are unchanged (rename changes the name); saved_query_version_id is the current Version of that
        Saved Query. Omit destination_id for no delivery, including when replacing a Version that
        had a destination; omission does not inherit the previous destination.
    SubscriptionVersion:
      type: object
      additionalProperties: false
      properties:
        subscription_id:
          type: string
          minLength: 1
        version_id:
          type: string
          minLength: 1
        saved_query_id:
          type: string
          minLength: 1
        saved_query_version_id:
          type: string
          minLength: 1
        evaluator:
          $ref: '#/components/schemas/EvaluatorConfig'
        destination_id:
          type: string
          minLength: 1
        owner:
          $ref: '#/components/schemas/SubscriptionOwner'
      required:
      - subscription_id
      - version_id
      - saved_query_id
      - saved_query_version_id
      - evaluator
      description: Immutable Subscription configuration. Every Version keeps the Subscription's owner,
        absent for a global Subscription. destination_id is absent when this Version records Matches
        and change-feed notices without webhook delivery.
    Subscription:
      type: object
      additionalProperties: false
      properties:
        subscription_id:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
        enabled:
          type: boolean
        deleted:
          type: boolean
          description: Logically deleted for good; a deleted Subscription is also disabled and stays
            readable with its Versions, Matches and Deliveries.
        current_version:
          $ref: '#/components/schemas/SubscriptionVersion'
        owner:
          $ref: '#/components/schemas/SubscriptionOwner'
      required:
      - subscription_id
      - name
      - enabled
      - deleted
      - current_version
      description: Absent owner means a global, organization-wide Subscription.
    SubscriptionOwner:
      type: string
      minLength: 1
      maxLength: 128
      description: Subscription Owner, an opaque end-user reference defined by the client application
        (for example user-123). Quivr stores, filters and echoes it without interpreting it. At most 128
        characters without control characters; none is reserved for the listing filter. A refused owner is 422
        invalid_owner, in a creation body as in the listing filter.
    SubscriptionPage:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
        next_page_cursor:
          type: string
          minLength: 1
      required:
      - items
    SubscriptionPreviewRequest:
      type: object
      additionalProperties: false
      properties:
        definition:
          $ref: '#/components/schemas/SavedQueryDefinition'
        saved_query_id:
          type: string
          minLength: 1
        saved_query_version_id:
          type: string
          minLength: 1
        evaluator:
          $ref: '#/components/schemas/EvaluatorConfig'
        limit:
          type: integer
          minimum: 1
          maximum: 50
          default: 20
          description: The most Record Versions to judge, newest first. Each one costs an evaluator call.
        accepted_after:
          type: string
          format: date-time
          description: Judge only revisions accepted after this instant.
      required:
      - evaluator
      description: A proposed Subscription to preview. Give either definition, an inline Saved Query
        definition, or saved_query_id with saved_query_version_id, an existing Saved Query Version; not
        both.
    SubscriptionPreviewMatch:
      type: object
      additionalProperties: false
      properties:
        corpus_id:
          type: string
          minLength: 1
        record_id:
          type: string
          minLength: 1
        record_version_id:
          type: string
          minLength: 1
        accepted_at:
          type: string
          format: date-time
        evidence:
          $ref: '#/components/schemas/MatchEvidence'
      required:
      - corpus_id
      - record_id
      - record_version_id
      - accepted_at
      - evidence
      description: A Record Version the proposed Subscription would have matched, with the evidence a
        Match would carry. It is not a Match and is not stored.
    SubscriptionPreview:
      type: object
      additionalProperties: false
      properties:
        evaluated:
          type: integer
          minimum: 0
          description: Record Versions the evaluator decided.
        matched:
          type: integer
          minimum: 0
        not_ready:
          type: integer
          minimum: 0
          description: Record Versions the evaluator could not decide yet (for example before enrichment).
        complete:
          type: boolean
          description: False when the time budget ran out before every listed Record Version was decided.
        oldest_accepted_at:
          type: string
          format: date-time
          description: When the oldest decided Record Version was accepted; absent when none was decided.
        matches:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/SubscriptionPreviewMatch'
          description: Most recently accepted first.
      required:
      - evaluated
      - matched
      - not_ready
      - complete
      - matches
      description: What a proposed Subscription would have matched among recent Record Versions.
    MatchEvidence:
      type: object
      additionalProperties: false
      properties:
        evaluator:
          $ref: '#/components/schemas/EvaluatorConfig'
        explanation:
          type: string
          maxLength: 4096
        part_keys:
          type: array
          items:
            type: string
            minLength: 1
          maxItems: 100
        details:
          type: object
          additionalProperties: true
      required:
      - evaluator
      - explanation
      description: Immutable evidence for a positive result, including evaluator version/configuration.
        History retention may expire the entire evidence payload; historical reads then return 410
        evidence_expired rather than a successful response with modified evidence.
        Details are plugin-defined, bounded to 16 KiB and schema-validated by its adapter; core checks
        referenced Parts. Access is rechecked on reads.
    Match:
      type: object
      additionalProperties: false
      properties:
        match_id:
          type: string
          minLength: 1
        subscription_id:
          type: string
          minLength: 1
        subscription_version_id:
          type: string
          minLength: 1
        saved_query_id:
          type: string
          minLength: 1
        saved_query_version_id:
          type: string
          minLength: 1
        record_id:
          type: string
          minLength: 1
        record_version_id:
          type: string
          minLength: 1
        previous_match_id:
          type: string
          minLength: 1
        owner:
          $ref: '#/components/schemas/SubscriptionOwner'
        evidence:
          $ref: '#/components/schemas/MatchEvidence'
      required:
      - match_id
      - subscription_id
      - subscription_version_id
      - saved_query_id
      - saved_query_version_id
      - record_id
      - record_version_id
      - evidence
      description: Immutable positive historical determination, not a claim of current eligibility. Unique
        subscription-version/record-version. Correction/withdrawal notifications reference history; no
        Match is fabricated for negative decisions. owner is the Subscription's owner, absent when global.
    MatchPage:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Match'
        next_page_cursor:
          type: string
          minLength: 1
      required:
      - items
    MonitoringReferences:
      type: object
      additionalProperties: false
      properties:
        match_id:
          type: string
          minLength: 1
        record_id:
          type: string
          minLength: 1
        record_version_id:
          type: string
          minLength: 1
        subscription_id:
          type: string
          minLength: 1
        subscription_version_id:
          type: string
          minLength: 1
        delivery_id:
          type: string
          minLength: 1
        previous_match_id:
          type: string
          minLength: 1
        owner:
          $ref: '#/components/schemas/SubscriptionOwner'
      required:
      - match_id
      - record_id
      - record_version_id
      - subscription_id
      - subscription_version_id
      description: owner is the Subscription Owner, so a client routes the notice to its user; absent
        for a global Subscription and in notices committed before owners existed. match_id is the new Match for created/corrected, prior positive Match for no_longer_matches/withdrawn.
        record_version_id is the causal correction version for corrected/no_longer_matches, otherwise
        the matched version. delivery_id is present only when a destination created a Delivery.
        References alone confer no access.
    WebhookEvent:
      type: object
      additionalProperties: false
      properties:
        event_id:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
        type:
          type: string
          enum:
          - match.created
          - match.corrected
          - match.no_longer_matches
          - match.withdrawn
        schema_version:
          type: string
          enum:
          - '1'
        occurred_at:
          type: string
          format: date-time
        references:
          $ref: '#/components/schemas/MonitoringReferences'
      required:
      - event_id
      - type
      - schema_version
      - occurred_at
      - references
      description: Immutable reference-only notification. Retries preserve event_id and the exact stored
        body bytes; signing timestamp changes per attempt. No document content, excerpt, explanation,
        cursor or secret is embedded.
    DeliveryAdmission:
      type: object
      additionalProperties: false
      properties:
        allowed:
          type: boolean
        reason:
          type: string
          enum:
          - subscription_disabled
          - subscription_deleted
          - record_withdrawn
          - superseded
          - access_denied
          - destination_unavailable
          - terminal
      required:
      - allowed
      description: Current derived admission view, separate from durable Delivery state. A disallowed
        pending Delivery makes no new network attempt; it does not become a new lifecycle state.
        destination_unavailable means its destination is no longer configured for the Organization.
        subscription_disabled lasts until a re-enable; subscription_deleted is permanent. record_withdrawn refuses match.created, match.corrected and match.no_longer_matches; match.withdrawn
        is admitted for a withdrawn Record. superseded refuses an undelivered match.created or
        match.corrected once a later match.corrected or match.no_longer_matches exists for the same
        Subscription and Record, and an undelivered match.no_longer_matches once a later match.corrected
        exists; match.withdrawn is never superseded.
    Delivery:
      type: object
      additionalProperties: false
      properties:
        delivery_id:
          type: string
          minLength: 1
        match_id:
          type: string
          minLength: 1
        destination_id:
          type: string
          minLength: 1
        state:
          type: string
          enum:
          - pending
          - delivering
          - delivered
          - exhausted
        event:
          $ref: '#/components/schemas/WebhookEvent'
        attempt_count:
          type: integer
          minimum: 0
        admission:
          $ref: '#/components/schemas/DeliveryAdmission'
        last_error:
          $ref: '#/components/schemas/Error'
        next_attempt_at:
          type: string
          format: date-time
          description: When the next automatic attempt becomes eligible. Present only while the Delivery
            is pending and admission is allowed; a retry waits with jittered exponential backoff (or a
            valid Retry-After on 429/503), never beyond the delivery window.
      required:
      - delivery_id
      - match_id
      - destination_id
      - state
      - event
      - attempt_count
      - admission
    DeliveryAttempt:
      type: object
      additionalProperties: false
      properties:
        attempt_id:
          type: string
          minLength: 1
        delivery_id:
          type: string
          minLength: 1
        number:
          type: integer
          minimum: 1
        outcome:
          type: string
          enum:
          - in_flight
          - acknowledged
          - retryable_error
          - permanent_error
          - unknown
        http_status:
          type: integer
          minimum: 100
          maximum: 599
        error:
          $ref: '#/components/schemas/Error'
      required:
      - attempt_id
      - delivery_id
      - number
      - outcome
      description: Read view of append-only admission/outcome facts. Unknown network result can be retried
        with the same event ID; no response body, signature or signing key is exposed.
    DeliveryAttemptPage:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DeliveryAttempt'
        next_page_cursor:
          type: string
          minLength: 1
      required:
      - items
    FacetRequest:
      type: object
      additionalProperties: false
      required: [corpus_ids, fields]
      properties:
        corpus_ids:
          type: array
          minItems: 1
          maxItems: 16
          uniqueItems: true
          items:
            type: string
            minLength: 1
        fields:
          type: array
          minItems: 1
          maxItems: 16
          items:
            $ref: '#/components/schemas/FacetField'
          description: Distinct logical metadata field names, in response order.
        filter:
          $ref: '#/components/schemas/FacetFilter'
        accepted_after:
          type: string
          format: date-time
          description: Inclusive current-Version acceptance-time lower bound, as in listing.
        accepted_before:
          type: string
          format: date-time
          description: Exclusive current-Version acceptance-time upper bound, as in listing.
        accuracy:
          type: string
          enum: [exact, fast]
          description: >-
            Absent or exact counts every current document now. fast is best effort: Quivr may
            answer sooner, usually within a few seconds, from stored snapshots (as_of), a uniform
            sample (approximate), or an exact count that ended within about a second (neither
            marker). The 25-second request deadline still applies.
    FacetField:
      type: object
      additionalProperties: false
      required: [field]
      properties:
        field:
          type: string
          pattern: '^(metadata\.)?[a-z][a-z0-9_]{0,63}$'
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        interval:
          type: string
          enum: [day, month, year]
          description: Required only for datetime fields; bucket start in UTC.
    FacetResponse:
      type: object
      additionalProperties: false
      required: [items]
      properties:
        items:
          type: array
          maxItems: 16
          items:
            $ref: '#/components/schemas/Facet'
        excluded_corpora:
          type: array
          maxItems: 16
          items:
            $ref: '#/components/schemas/CorpusExclusion'
        as_of:
          type: string
          format: date-time
          description: >-
            Fast requests only. Counts come from stored per-Corpus snapshots, each exact when it
            was taken; this is the oldest snapshot's time. Changes since a Corpus's snapshot are
            missing from its counts, and newer snapshots of other Corpora include their later changes.
        approximate:
          type: boolean
          description: Fast requests only; present and true when counts are estimates scaled from a uniform sample of Records.
        sample_fraction:
          type: number
          format: double
          exclusiveMinimum: 0
          exclusiveMaximum: 1
          x-go-type: float64
          description: Share of the Corpora's Records counted when approximate.
    Facet:
      type: object
      additionalProperties: false
      required: [field, buckets]
      properties:
        field:
          type: string
        buckets:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/FacetBucket'
    FacetBucket:
      type: object
      additionalProperties: false
      required: [value, count]
      properties:
        value:
          oneOf:
          - type: string
          - type: number
            format: double
            x-go-type: float64
          - type: boolean
          description: Typed scalar value, array member, or RFC 3339 UTC date bucket start.
        count:
          type: integer
          format: int64
          minimum: 1
    SearchRequest:
      type: object
      additionalProperties: false
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 8192
          description: At most 8192 code points on the wire. A semantic or hybrid query is also limited
            by the owner of the searched vector space (the first-party core.ingest plugin accepts at
            most 256 tokens of its model's tokenizer); a longer query is refused with 422
            query_too_long, whose message names the limit, never truncated.
        corpus_ids:
          type: array
          items:
            type: string
            minLength: 1
          minItems: 1
          maxItems: 16
          uniqueItems: true
        mode:
          type: string
          enum:
          - lexical
          - semantic
          - hybrid
          default: hybrid
        profile:
          type: string
          minLength: 1
          default: default
          description: A configured short name or a full plugin/profile name this deployment answers
            (listSearchProfiles). retrieval.profiles maps short names, including default, to full names.
            An unknown profile returns 422 unsupported_profile.
        limit:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
        evaluation_plugin:
          type: string
          minLength: 1
          description: Ingestion plugin whose independent projection to measure. Requires evaluation_space; omitted searches follow served routing.
        evaluation_space:
          type: string
          minLength: 1
          description: Vector space owned by evaluation_plugin. Both fields are required together; invalid selections return 422 unsupported_search.
        filter:
          $ref: '#/components/schemas/SearchFilter'
      required:
      - query
      - corpus_ids
      description: Text-only top-k query. Resolve all Corpora in the authenticated Organization and require
        read/search permission for every requested Corpus before querying. Never silently drop an unauthorized
        Corpus. Unknown/unsupported profile or mode returns 422; a dependency outage is an error, not
        an empty successful result. Query token limits are checked against the resolved profile; no silent
        truncation. An optional filter narrows candidates inside the engine query, before ranking and
        the limit, in every mode. The first-party retrieval plugin returns each Record once, with its best matching passage; custom plugins can request individual passages. Pagination is outside this surface.
    FacetFilter:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        source_namespaces:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 200
          minItems: 1
          maxItems: 50
          uniqueItems: true
          description: Keep only Records whose Source Namespace is one of these values. Ranking
            and the limit apply within the filtered set, so a source's best matches are returned
            even when other sources outrank them.
        metadata:
          type: array
          minItems: 1
          maxItems: 16
          items:
            $ref: '#/components/schemas/MetadataFilter'
          description: ANDed typed filters. Common fields use metadata.language, metadata.published_at, metadata.source_type, metadata.source, metadata.author, metadata.subjects, metadata.tags, metadata.country and metadata.place. Other names require the filter role in the Corpus's effective retrieval mapping. Corpora missing a requested filter field are excluded and reported. A metadata-capable generation is required; rebuild older Corpora first (422 metadata_filter_unavailable).
      description: Candidate filter applied before ranking. Every present condition must hold.
        A requested Corpus served by a Projection Generation built before source filtering existed
        returns 422 source_filter_unavailable; rebuild that Corpus once (rebuildCorpusProjection)
        to enable it. Unfiltered search is unaffected.
    SearchFilter:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        source_namespaces:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 200
          minItems: 1
          maxItems: 50
          uniqueItems: true
          description: Keep only Records whose Source Namespace is one of these values. Ranking
            and the limit apply within the filtered set, so a source's best matches are returned
            even when other sources outrank them.
        record_ids:
          type: array
          minItems: 1
          maxItems: 50
          uniqueItems: true
          items: {type: string, minLength: 1, maxLength: 200}
          description: Exact canonical Record identities. Requires an item-keyword generation; rebuild older Corpora first (422 metadata_filter_unavailable).
        version_ids:
          type: array
          minItems: 1
          maxItems: 50
          uniqueItems: true
          items: {type: string, minLength: 1, maxLength: 200}
          description: Exact canonical Version identities; currentness and authorization still apply.
        metadata:
          type: array
          minItems: 1
          maxItems: 16
          items:
            $ref: '#/components/schemas/MetadataFilter'
          description: ANDed typed filters. Common fields use metadata.language, metadata.published_at, metadata.source_type, metadata.source, metadata.author, metadata.subjects, metadata.tags, metadata.country and metadata.place. Other names require the filter role in the Corpus's effective retrieval mapping. Corpora missing a requested filter field are excluded and reported. A metadata-capable generation is required; rebuild older Corpora first (422 metadata_filter_unavailable).
      description: Candidate filter applied before ranking. Every present condition must hold.
        A requested Corpus served by a Projection Generation built before source filtering existed
        returns 422 source_filter_unavailable; rebuild that Corpus once (rebuildCorpusProjection)
        to enable it. Unfiltered search is unaffected.
    MetadataFilter:
      type: object
      additionalProperties: false
      properties:
        field:
          type: string
          pattern: '^(metadata\.)?[a-z][a-z0-9_]{0,63}$'
        any_of:
          type: array
          minItems: 1
          maxItems: 50
          items:
            anyOf:
            - type: string
              minLength: 1
              maxLength: 200
            - type: number
              x-go-type: float64
            - type: boolean
          description: Exact equality (one value) or any-of equality. String-array fields match any element; values retain their declared type. Datetime equality uses RFC3339 strings.
        gte:
          type: string
          format: date-time
          description: Inclusive lower datetime bound. Requires a datetime field.
        lte:
          type: string
          format: date-time
          description: Inclusive upper datetime bound. Requires a datetime field.
      required: [field]
      anyOf:
      - required: [any_of]
      - required: [gte]
      - required: [lte]
      description: Every present condition must hold. Field names are unique within a request; at most 16 predicates. Wrong types and reversed bounds return 422 invalid_query. Missing/mistyped source values do not match. Datetimes are normalized to UTC milliseconds (submillisecond digits are truncated).
    CorpusExclusion:
      type: object
      additionalProperties: false
      properties:
        corpus_id:
          type: string
        fields:
          type: array
          items:
            type: string
      required: [corpus_id, fields]
      description: Authorized Corpus excluded because these logical fields are not declared with the filter role. Common metadata fields are always declared.
    SearchProfile:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
        version:
          type: string
          minLength: 1
        degraded:
          type: array
          minItems: 1
          maxItems: 16
          items:
            $ref: '#/components/schemas/SearchDegradation'
          description: Omitted when fully served. Ordinary hybrid searches report the authorized, non-excluded Corpora
            whose vector half is unavailable and whose results use keywords. Present even when no documents match.
      required:
      - name
      - version
      description: Resolved retrieval profile identity. Name is the requested short or full name (default when
        the request named none). Version identifies what ranked as
        plugin:<plugin id>@<version>/<profile>, naming the retrieval plugin, its version and the profile.
    SearchDegradation:
      type: object
      additionalProperties: false
      properties:
        reason:
          type: string
          enum: [vectors_unavailable]
          description: No usable served vector route or current coverage confirms no vectors; keywords remain available. Stale and unknown counts do not disable current routes.
        corpus_ids:
          type: array
          minItems: 1
          maxItems: 16
          uniqueItems: true
          items:
            type: string
            minLength: 1
      required: [reason, corpus_ids]
    SearchProfileList:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SearchProfileDescription'
          minItems: 1
      required:
      - items
    SearchProfileDescription:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
        full_name:
          type: string
          minLength: 1
          description: Full plugin/profile name, accepted directly by search.
        aliases:
          type: array
          items:
            type: string
            minLength: 1
          uniqueItems: true
          description: Configured short names that select this profile; empty for an unaliased profile.
        description:
          type: string
        max_latency_ms:
          type: integer
          minimum: 1
          description: Latency objective (p95 target) of one search under this profile. A slower search still answers; the hard bound is four times this value, at least 2 s and at most 9 s.
        max_cost_cents:
          type: number
          minimum: 0
          description: Most a search may spend on paid calls.
        provider:
          type: object
          additionalProperties: false
          properties:
            kind:
              type: string
              enum:
              - engine
              - plugin
              description: plugin, the retrieval plugin that answers the profile. engine is no longer
                returned since the engine's own search moved into core.retrieve.
            plugin_id:
              type: string
              minLength: 1
            plugin_version:
              type: string
              minLength: 1
          required:
          - kind
      required:
      - name
      - full_name
      - aliases
      - provider
    SearchUsage:
      type: object
      additionalProperties: false
      properties:
        rounds:
          type: integer
          minimum: 1
          maximum: 3
        elapsed_ms:
          type: integer
          minimum: 0
        paid_calls:
          type: integer
          minimum: 0
        cost_cents:
          type: number
          minimum: 0
        profiles:
          type: array
          maxItems: 65
          items:
            $ref: '#/components/schemas/SearchProfileUsage'
          description: Each profile invocation, outer first; paid calls and cost belong to that plugin only.
        phases:
          $ref: '#/components/schemas/SearchPhases'
      required:
      - rounds
      - elapsed_ms
      - paid_calls
      - cost_cents
      description: What a search answered by a retrieval plugin spent; rounds of the plugin, elapsed
        time, the paid calls and total cost across all profiles, and the time spent in each phase.
    SearchProfileUsage:
      type: object
      additionalProperties: false
      required: [profile, plugin_version, rounds, paid_calls, cost_cents]
      properties:
        profile:
          type: string
          description: Full plugin/profile name.
        plugin_version:
          type: string
        rounds:
          type: integer
          minimum: 1
          maximum: 3
        paid_calls:
          type: integer
          minimum: 0
        cost_cents:
          type: number
          minimum: 0
      description: Own usage of one profile invocation; aggregate SearchUsage totals include every level.
    SearchPhases:
      type: object
      additionalProperties: false
      properties:
        routing_ms:
          type: integer
          minimum: 0
        coverage_ms:
          type: integer
          minimum: 0
        plugin_rounds_ms:
          type: integer
          minimum: 0
        query_encoding_ms:
          type: integer
          minimum: 0
        index_query_ms:
          type: integer
          minimum: 0
        hydration_ms:
          type: integer
          minimum: 0
      required:
      - routing_ms
      - coverage_ms
      - plugin_rounds_ms
      - query_encoding_ms
      - index_query_ms
      - hydration_ms
      description: Milliseconds a search spent in each phase. routing_ms authorizes the request and
        routes it to projection generations; coverage_ms reads the vector spaces and their coverage;
        plugin_rounds_ms waits for the retrieval plugin's rounds; query_encoding_ms encodes the query
        with the plugin that owns each vector space, 0 when no candidate request needs a vector;
        index_query_ms queries the index; hydration_ms rechecks and reads candidates from canonical
        storage. The phases do not add up to elapsed_ms, which also counts the engine's own work
        between them.
    SearchExcerpt:
      type: object
      additionalProperties: false
      properties:
        text:
          type: string
          maxLength: 4096
        start:
          type: integer
          minimum: 0
        end:
          type: integer
          minimum: 0
        coordinate_system:
          type: string
          enum:
          - unicode_codepoint
      required:
      - text
      - start
      - end
      - coordinate_system
      description: Exact canonical normalized Part text slice [start,end), using Unicode code points,
        not UTF-8 bytes or UTF-16 units. End must be >= start and end-start must equal the excerpt code-point
        length. Bounds are checked against the referenced immutable Part. No synthetic highlights or rewritten
        snippets.
    SearchHit:
      type: object
      additionalProperties: false
      properties:
        record_id:
          type: string
          minLength: 1
        version_id:
          type: string
          minLength: 1
        part_key:
          type: string
          minLength: 1
        segment_id:
          type: string
          minLength: 1
        segmentation_id:
          type: string
          minLength: 1
        projection_generation_id:
          type: string
          minLength: 1
        embedding_artifact_id:
          type: string
          minLength: 1
        vector_space_id:
          type: string
          minLength: 1
        rank:
          type: integer
          minimum: 1
        excerpt:
          $ref: '#/components/schemas/SearchExcerpt'
        passage_text:
          type: string
          maxLength: 16384
          description: Exact packed passage text used for the hit, when source-range metadata is available.
        source_excerpts:
          type: array
          maxItems: 256
          items:
            type: object
            additionalProperties: false
            properties:
              part_key:
                type: string
                minLength: 1
              text:
                type: string
                maxLength: 4096
              start:
                type: integer
                minimum: 0
              end:
                type: integer
                minimum: 0
              coordinate_system:
                type: string
                enum:
                - unicode_codepoint
            required:
            - part_key
            - text
            - start
            - end
            - coordinate_system
        availability:
          $ref: '#/components/schemas/Availability'
        explanation:
          type: string
          minLength: 1
          maxLength: 1024
          description: Why the retrieval plugin ranked this hit here, when it says so.
      required:
      - record_id
      - version_id
      - part_key
      - segment_id
      - segmentation_id
      - projection_generation_id
      - rank
      - excerpt
      - availability
      description: One authorized segment hit. Rehydrate from canonical storage and recheck Organization/Corpus
        access, currentness, quarantine and Tombstone before returning. Rank is contiguous and one-based
        after hydration/filtering. Projection Generation, segmentation, segment and optional Embedding
        Artifact/Vector Space are logical durable IDs, not physical collection names or workflow IDs.
        Embedding references are omitted when that segment has lexical coverage only. They do not assert
        that the dense branch contributed to its rank. All hits inherit the response retrieval profile.
        Raw scores/explainScore stay internal.
      if:
        required:
        - embedding_artifact_id
      then:
        required:
        - vector_space_id
      else:
        not:
          required:
          - vector_space_id
    SearchResponse:
      type: object
      additionalProperties: false
      properties:
        excluded_corpora:
          type: array
          items:
            $ref: '#/components/schemas/CorpusExclusion'
        items:
          type: array
          items:
            $ref: '#/components/schemas/SearchHit'
          maxItems: 50
        retrieval_profile:
          $ref: '#/components/schemas/SearchProfile'
        usage:
          $ref: '#/components/schemas/SearchUsage'
      required:
      - items
      - retrieval_profile
      description: Bounded top-k results after canonical rechecks. May contain fewer hits than requested;
        no total count, completeness promise or stable pagination snapshot. Empty results still name the
        resolved profile.
    ProjectionRebuildResult:
      type: object
      additionalProperties: false
      properties:
        projection_generation_id:
          type: string
          minLength: 1
      required:
      - projection_generation_id
      description: Logical generation activated for the requested Corpus. Opaque ID, never a physical
        search collection name.
webhooks:
  monitoringNotification:
    post:
      operationId: receiveMonitoringNotification
      description: Receiver endpoint, not a Quivr API route. Verify Standard Webhooks v1 HMAC-SHA256 over
        webhook-id + dot + webhook-timestamp + dot + raw body before parsing. Timestamp refreshed per
        attempt; body event_id equals webhook-id. See monitoring contract for retry defaults.
      security: []
      parameters:
      - name: webhook-id
        in: header
        required: true
        schema:
          type: string
          minLength: 1
      - name: webhook-timestamp
        in: header
        required: true
        schema:
          type: string
          minLength: 1
      - name: webhook-signature
        in: header
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEvent'
      responses:
        2XX:
          description: Receiver durably accepted/deduplicated this event.
        default:
          description: Transport retry policy applies; do not create another Match.