Import endpoint: POST /api/v1/quotes/import

[DutchJaFO]

Add a dedicated bulk import endpoint, separate from the single-record write endpoints (#16).

Import is a distinct operation: it validates a batch, detects duplicates, resolves field-level conflicts, and commits atomically — none of which map cleanly onto repeated POST /api/v1/quotes calls.

Endpoint

POST /api/v1/quotes/import

Request

{
  "format": "json" | "csv",
  "enrich": false,
  "conflictStrategy": "skip" | "overwrite" | "review",
  "data": "<raw JSON array or CSV string>"
}

Alternatively, multipart/form-data with a file upload — both should be supported.

conflictStrategy

Controls what happens when an imported record matches an existing record (same quote + source text) but has different field values.

Strategy	Behaviour
skip	Keep existing record unchanged. Default — safe for automated imports.
overwrite	Replace all differing fields with imported values, regardless of what is currently stored.
review	Do not write conflicting records. Return the conflicts in the response for the user to resolve manually (see conflict resolution flow below).

A record with no field differences is always silently skipped — it is identical to what already exists.

enrich

Optional (default false). When true, runs the enrichment service (#19) on each successfully imported row after writing.

Response

{
  "imported": 10,
  "skipped": 2,
  "enriched": 7,
  "errors": [
    { "row": 4, "field": "type", "message": "Unknown type 'videogame'" }
  ],
  "conflicts": [
    {
      "importId": "client-assigned-id-or-row-index",
      "existingId": "uuid-of-existing-record",
      "fields": [
        { "field": "date", "existingValue": "1994", "importedValue": "1995" },
        { "field": "genres", "existingValue": ["drama"], "importedValue": ["drama", "thriller"] }
      ]
    }
  ]
}

conflicts is populated only when conflictStrategy: "review". Each conflict includes enough information for the UI to render a side-by-side comparison.

Conflict resolution endpoint

POST /api/v1/quotes/import/resolve

Accepts per-field resolutions for conflicts returned by a prior review import. The user decides each field independently.

{
  "resolutions": [
    {
      "existingId": "uuid",
      "fields": [
        { "field": "date", "resolution": "keep" | "replace" },
        { "field": "genres", "resolution": "keep" | "replace" }
      ]
    }
  ]
}

Each resolution is recorded in the audit log (#56) with ActorType='user', Action='updated', and old/new values — giving a clear record of who decided what and why.

General behaviour

• IDs always generated server-side — never trusted from the payload
• createdAt and updatedAt set to time of import — source timestamps ignored
• Valid rows committed in a single transaction per batch; one bad row does not abort the batch
• Unknown fields in the payload silently ignored
• originalLanguage defaults to "en" if absent
• When enrich: true, enrichment runs after commit; a failed lookup leaves the row as-is without rolling back the import

Formats supported

• JSON — array of objects in the canonical quotes.json schema
• CSV — columns: quote, source, author, character, type, genres, date, originalLanguage

Existing sources as the format reference

The two seed datasets (vilaboim/movie-quotes and NikhilNamal17/popular-movie-quotes) conform to the JSON schema after seed script normalisation. The import endpoint must accept that output directly.

Enrichment integration

Shared with the enrichment script (#19) via Quotinator.Enrichment. The import endpoint calls the same service when enrich: true. Design decision on library vs. project resolved in #19.

Auth

Requires API key authentication (#15) — same policy as write endpoints.

[DutchJaFO]

Flagging a terminology/design overlap found while reconciling #64 (import conflict resolution policy).

This issue's spec independently defines its own `conflictStrategy: skip|overwrite|review` plus a separate `POST /api/v1/quotes/import/resolve` endpoint for field-level conflict resolution. #64 has now been reconciled to define five policies (`skip`, `newest-wins`, `merge-ours`, `merge-theirs`, `review`) as the durable conflict-resolution data model for the whole milestone, including a new `System_ImportConflicts` table (Data-owned, logs every detected conflict with a `resolved`/`pending` status) that this endpoint can build on. See #64's latest comment and `docs/milestones/data-import-sources/64-conflict-resolution-plan.md` for the full design.

Before implementing this issue, its spec likely needs a refresh to:

• Use `newest-wins` instead of `overwrite` for terminology consistency
• Decide whether `conflictStrategy` should just be Import conflict resolution: per-import policy with configurable defaults #64's `DuplicateResolutionPolicy` passed through as a query parameter, rather than a separate, narrower enum
• Wire the `review` strategy and `/resolve` endpoint against `System_ImportConflicts` rather than inventing separate storage

Not prescribing the resolution here — just flagging it so this issue's own planning session accounts for it.

[DutchJaFO]

Scope reconciliation update (implementation now complete)

Supplementing the earlier reconciliation comment (from #64's own scope work) with the deviations decided during #45's actual implementation:

• Request shape: the original {"format", "conflictStrategy", "data"} JSON envelope and ?conflictPolicy=/?preview=true query parameters are replaced by multipart/form-data (file + a settings JSON text field), reusing the manifest DTOs (SourceImportSettingsDto/ManifestPolicyDto) built for Import manifest: ordered file list for bundled sources and user imports #63/Import conflict resolution: per-import policy with configurable defaults #64 instead of inventing new fields.
• Matching is Id-based, not content-based. The original "same quote+source text" duplicate matching was never built — Import conflict resolution: per-import policy with configurable defaults #64's engine matches by Id (deterministic via QuoteIdentity.StableId), and Import endpoint: POST /api/v1/quotes/import #45 reuses that engine unmodified.
• No sameId/sameText split in the response — since matching is purely Id-based, sameText never applies. The response's conflicts[] mirrors a System_ImportConflicts row directly instead.
• Two endpoints instead of a preview=true flag — POST /api/v1/quotes/import and POST /api/v1/quotes/import/preview share one handler and an identical response contract. See Import endpoint: preview/dry-run mode #65's own plan doc, updated to match.
• Auth is X-Api-Key, not Authorization: Bearer — every other admin-tier endpoint in this codebase already uses X-Api-Key; the original issue text (and Auth: API key authentication for write endpoints and MCP #15, not yet implemented) described a mechanism this codebase doesn't actually use anywhere.
• The /resolve manual-review endpoint and its audit-log integration are deferred to a new follow-up issue — it depends on Audit log: provenance and change history across all entity types #56 (audit log), which hasn't started. Import endpoint: POST /api/v1/quotes/import #45 ships duplicate detection + automatic policy application only, not the manual-review workflow.
• Bonus, not originally requested: manifest.json file entries can now declare their own per-file duplicateResolution override (cascading file → manifest → config), a free side effect of reusing the shared settings DTO as ManifestFileEntryDto's base class.
• enrich=true stays out of scope, deferred to Enrichment script: fill missing quote fields using TMDB, Open Library, and Wikidata #19 — restating the standing decision from earlier planning.

Full detail: docs/milestones/data-import-sources/45-import-endpoint-plan.md.

Implementation is complete and verified: T1 (Visual Studio) ✅, T2 (Docker) ✅, 826 tests passing. Not yet merged to main or included in a release.

[DutchJaFO]

Released in v1.8.0.

#	Status	Requirement	Method	Verification
1	✅	Both endpoints accept multipart/form-data (file + optional settings)	Unit test	ImportEndpointTests.Import_CorrectKeyAndValidFile_Returns200WithResultShape, ImportPreview_CorrectKeyAndValidFile_Returns200WithPreviewTrue
2-3	✅	settings.converter/settings.duplicateResolution work as designed	Unit test	QuoteImportServiceTests (5 policy tests + converter test)
4	✅	Duplicate detection against the live database, all 5 policies	Unit test	QuoteImportServiceTests.ImportAsync_Skip/NewestWins/MergeOurs/MergeTheirs/Review_...
5	✅	Ids never server-generated; deterministic when absent	Unit test	CsvQuoteConverterTests.ConvertAsync_NoIdColumnValue_DerivesStableId
6	✅	A bad row is skipped and reported; rest of file still imports	Unit test	QuoteImportServiceTests.ImportAsync_OneRowMissingSource_SkipsItButImportsTheRest
7	✅	One ImportBatch row per non-preview run	Unit test	QuoteImportServiceTests.ImportAsync_FreshDatabase_InsertsNewQuote
8	✅	Preview rolls back all writes	Unit test	QuoteImportServiceTests.ImportAsync_Preview_LeavesZeroTrace, ImportAsync_PreviewWithConflict_NoConflictRowsPersisted
9	✅	X-Api-Key required, rate limited	Unit test	ImportEndpointTests.Import_NoKeyConfigured_Returns401
10	✅	enrich: true → 501, checked before file read	Unit test	ImportEndpointTests.Import_EnrichTrue_Returns501_BeforeCallingService
11	✅	Malformed settings/unknown converter/unparseable content → 422	Unit test	ImportEndpointTests (multiple 422 cases)
12	✅	Per-file duplicateResolution cascades file → manifest → config	Unit test	ManifestPolicyTests.Resolve_ThreeTierCascade_...
13	✅	QuoteSeedWriter extraction behaviour-preserving; live-DB existence-check bug fixed	Unit test	DatabaseInitializerTests, ConflictResolutionTests, ImportBatchesTests all pass unmodified
14	✅	CSV converter: header mapping, id precedence, malformed-row tolerance	Unit test	CsvQuoteConverterTests (11 tests)
15-16	✅	T1/T2 — VS and Docker smoke tests	Live	Confirmed 2026-07-05

Full solution dotnet test --configuration Release: 821 tests, 0 warnings, 0 errors.