> ## Documentation Index > Fetch the complete documentation index at: https://docs.quivr.thevibecompany.co/llms.txt > Use this file to discover all available pages before exploring further. # Configure retrieval > 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. ## OpenAPI ````yaml /openapi.yaml put /v0/corpora/{corpus_id}/retrieval 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. servers: [] security: - ApiKey: [] paths: /v0/corpora/{corpus_id}/retrieval: put: tags: - Corpora summary: Configure retrieval 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. operationId: configureRetrieval parameters: - name: corpus_id in: path required: true schema: type: string minLength: 1 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConfigUpdate' 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' components: schemas: ConfigUpdate: type: object additionalProperties: false properties: idempotency_key: type: string minLength: 1 retrieval: $ref: '#/components/schemas/RetrievalConfig' required: - idempotency_key - retrieval Operation: type: object additionalProperties: false properties: operation_id: type: string minLength: 1 kind: type: string minLength: 1 state: type: string enum: - queued - running - 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' 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 and retrieval_configuration Operations require corpus_id; when succeeded they require result naming the activated logical generation. This result shape covers those two command kinds only. if: properties: kind: enum: - projection_rebuild - retrieval_configuration required: - kind then: required: - corpus_id if: properties: state: const: succeeded required: - state then: required: - result Error: type: object additionalProperties: false properties: 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 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. 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. 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 roles: type: array items: type: string enum: - search - filter minItems: 1 required: - name - source_pointer - 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. Core validates 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 validated and preserved; no public filter API consumes them in v0. securitySchemes: 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. ````