{"components":{"parameters":{"receipts_ReceiptsListOptionsParams":{"description":"Page size and cursor, sent as ordinary query parameters.","explode":true,"in":"query","name":"options","schema":{"additionalProperties":false,"properties":{"cursor":{"description":"Previous next_cursor; keep the same filters and limit. Omit for the first page.","type":"string","x-go-type-skip-optional-pointer":false},"limit":{"description":"Number of receipts per page, from 1 to 100; defaults to 50.","maximum":100,"minimum":1,"type":"integer","x-go-type":"int","x-go-type-skip-optional-pointer":false}},"type":"object","x-go-type-skip-optional-pointer":false},"style":"form"},"receipts_ReceiptsSelectionParams":{"description":"Optional receipt filters, sent as ordinary query parameters.","explode":true,"in":"query","name":"selection","schema":{"additionalProperties":false,"properties":{"category":{"description":"Category key to match, including its subcategories.","type":"string","x-go-type-skip-optional-pointer":false},"end_date":{"description":"Purchase date before this day (YYYY-MM-DD); excludes unknown dates.","type":"string","x-go-type-skip-optional-pointer":false},"merchant_id":{"description":"Merchant ID from GET /merchants; use instead of merchant_search.","type":"string","x-go-type-skip-optional-pointer":false},"merchant_search":{"description":"Search by merchant name; use instead of merchant_id.","type":"string","x-go-type-skip-optional-pointer":false},"product":{"description":"Exact normalized line name; use instead of product_search.","type":"string","x-go-type-skip-optional-pointer":false},"product_search":{"description":"Search receipt line names; use instead of product.","type":"string","x-go-type-skip-optional-pointer":false},"start_date":{"description":"Purchase date on or after this day (YYYY-MM-DD); excludes unknown dates.","type":"string","x-go-type-skip-optional-pointer":false},"status":{"description":"Processing group: requires_attention or processing; omit for all receipts.","type":"string","x-go-type-skip-optional-pointer":false}},"type":"object","x-go-type-skip-optional-pointer":false},"style":"form"}},"responses":{"content_contracts_facturai_shared_errors_RequestError":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_errors_RequestError"}]}}},"description":"The request could not be completed; see error and code for details.","x-go-name":"RequestErrorResponse"}},"schemas":{"content_contracts_facturai_shared_errors_RequestError":{"additionalProperties":false,"properties":{"blockers":{"description":"Conditions that prevent this action, when provided.","items":{"type":"string"},"type":"array"},"code":{"description":"Error code for automation; use it instead of matching message text.","type":"string"},"error":{"description":"Short explanation of the error; wording may change.","type":"string"},"message":{"description":"Optional details, which may be translated.","type":"string"}},"required":["error"],"title":"RequestError","type":"object"},"content_contracts_facturai_shared_exports_ExportCreate":{"additionalProperties":false,"description":"Export format and retry UUID; the UUID can also be sent in Idempotency-Key.","properties":{"format":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_exports_ExportFormat"}],"description":"File format: json, csv or excel (XLSX)."},"idempotency_key":{"description":"UUID for this export request; reuse for retries. A different format returns 409.","type":"string","x-go-name":"IdempotencyKey"}},"required":["format"],"title":"ExportCreate","type":"object"},"content_contracts_facturai_shared_exports_ExportDownload":{"additionalProperties":false,"description":"Temporary download URL and expiry time for a succeeded export.","properties":{"expires_at":{"description":"Download URL expiry time; request a new URL after this time.","format":"date-time","type":"string"},"url":{"description":"Temporary signed URL; download without sending the FacturAI API key.","type":"string","x-go-name":"URL"}},"required":["url","expires_at"],"title":"ExportDownload","type":"object"},"content_contracts_facturai_shared_exports_ExportFormat":{"enum":["json","csv","excel"],"title":"ExportFormat","type":"string"},"content_contracts_facturai_shared_exports_ExportPage":{"additionalProperties":false,"properties":{"items":{"description":"Exports on this page; empty or null if none.","items":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_exports_ExportRun"}]},"nullable":true,"type":"array","x-go-name":"Items"},"page":{"description":"One-based current page number.","type":"integer","x-go-name":"Page","x-go-type":"int"},"page_size":{"description":"Configured maximum number of runs per page.","type":"integer","x-go-name":"PageSize","x-go-type":"int"},"total_items":{"description":"Total number of export runs visible to this Household.","type":"integer","x-go-name":"TotalItems","x-go-type":"int"},"total_pages":{"description":"Total number of pages at the current page_size.","type":"integer","x-go-name":"TotalPages","x-go-type":"int"}},"required":["items","page","page_size","total_items","total_pages"],"title":"ExportPage","type":"object"},"content_contracts_facturai_shared_exports_ExportRun":{"additionalProperties":false,"description":"Export progress and file information, not the file contents.","properties":{"artifact_size_bytes":{"description":"Export file size in bytes; null until available.","nullable":true,"type":"integer","x-go-name":"ArtifactSizeBytes","x-go-type":"int64","x-go-type-skip-optional-pointer":false},"author":{"description":"Name of the user or API key that started the export; not a unique ID.","type":"string","x-go-name":"ActorLabel"},"completed_at":{"description":"Time the export finished, successfully or with an error; null while processing.","format":"date-time","nullable":true,"type":"string","x-go-name":"CompletedAt","x-go-type-skip-optional-pointer":false},"created_at":{"description":"Time the export was requested.","format":"date-time","type":"string","x-go-name":"CreatedAt"},"format":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_exports_ExportFormat"}],"description":"Requested file format.","x-go-name":"Format"},"id":{"description":"Export ID used for progress and download requests.","type":"string","x-go-name":"ID"},"last_error_code":{"description":"Most recent safe failure code, when one is recorded.","type":"string","x-go-name":"LastErrorCode"},"started_at":{"description":"Timestamp at which processing started; null while the run is queued.","format":"date-time","nullable":true,"type":"string","x-go-name":"StartedAt","x-go-type-skip-optional-pointer":false},"state":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_exports_ExportState"}],"description":"Progress: queued, running, succeeded or failed. Download is available only after success.","x-go-name":"State"}},"required":["id","format","state","created_at"],"title":"ExportRun","type":"object"},"content_contracts_facturai_shared_exports_ExportState":{"enum":["queued","running","succeeded","failed"],"title":"ExportState","type":"string"},"content_contracts_facturai_shared_household_CurrencySyncState":{"properties":{"last_attempt_at":{"description":"Last exchange-rate refresh attempt, or null.","nullable":true,"type":"string","x-go-type-skip-optional-pointer":false},"last_error":{"description":"Current exchange-rate refresh error, or null.","nullable":true,"type":"string","x-go-type-skip-optional-pointer":false},"last_success_at":{"description":"Last successful exchange-rate refresh, or null.","nullable":true,"type":"string","x-go-type-skip-optional-pointer":false},"refresh_needed":{"description":"Whether exchange rates are missing or need refreshing; this read does not refresh them.","type":"boolean"}},"required":["last_attempt_at","last_success_at","last_error","refresh_needed"],"title":"CurrencySyncState","type":"object"},"content_contracts_facturai_shared_household_HouseholdCurrency":{"properties":{"code":{"description":"Selected currency code.","type":"string"},"example_minor_units":{"description":"Value in this currency's minor units for 1000 base-currency minor units; omitted if no rate is available.","format":"int64","type":"integer","x-go-type-skip-optional-pointer":false},"rate_date":{"description":"Exchange-rate date (YYYY-MM-DD), when available.","type":"string","x-go-type-skip-optional-pointer":false},"rate_synced_at":{"description":"Last refresh time for this exchange rate, when available.","type":"string","x-go-type-skip-optional-pointer":false},"sort_order":{"description":"Zero-based display order among the Household's selected currencies.","type":"integer"}},"required":["code","sort_order"],"title":"HouseholdCurrency","type":"object"},"content_contracts_facturai_shared_household_HouseholdSettings":{"properties":{"base_currency":{"description":"Household base currency used for conversions.","type":"string"},"currencies":{"description":"Selected currencies in display order; empty or null before setup.","items":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_household_HouseholdCurrency"}]},"nullable":true,"type":"array"},"currency_catalog":{"description":"Currency codes available for Household configuration.","items":{"type":"string"},"nullable":true,"type":"array"},"currency_setup_required":{"description":"Whether the Household still needs its currency configuration completed.","type":"boolean"},"rates_sync":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_household_CurrencySyncState"}],"description":"Exchange-rate refresh status; reading it does not change settings."}},"required":["base_currency","currency_setup_required","currencies","currency_catalog","rates_sync"],"title":"HouseholdSettings","type":"object"},"content_contracts_facturai_shared_ledger-connections_LedgerAccount":{"additionalProperties":false,"properties":{"closed":{"description":"Whether the connected ledger marks this account as closed.","type":"boolean"},"currency":{"description":"Account currency code when reported by the provider; null when unavailable.","nullable":true,"type":"string","x-go-type-skip-optional-pointer":false},"ledger_connection_account_id":{"description":"Account ID used by FacturAI receipt payment fields.","type":"string","x-go-name":"LedgerConnectionAccountID"},"name":{"description":"Account display name from the local provider snapshot.","type":"string"},"off_budget":{"description":"Whether the provider marks the account as off-budget.","type":"boolean"},"provider":{"description":"Ledger provider identifier, such as actual.","type":"string"},"provider_account_id":{"description":"Provider-owned account identity; distinct from ledger_connection_account_id.","type":"string","x-go-name":"ProviderAccountID"}},"required":["ledger_connection_account_id","provider","provider_account_id","name","off_budget","closed","currency"],"title":"LedgerAccount","type":"object"},"content_contracts_facturai_shared_ledger-connections_LedgerAccountList":{"additionalProperties":false,"properties":{"accounts":{"description":"Saved accounts from the connected ledger.","items":{"$ref":"#/components/schemas/content_contracts_facturai_shared_ledger-connections_LedgerAccount"},"type":"array"}},"required":["accounts"],"title":"LedgerAccountList","type":"object"},"content_contracts_facturai_shared_ledger-connections_LedgerCategory":{"additionalProperties":false,"properties":{"group_name":{"description":"Provider category-group display name.","type":"string"},"ledger_connection_category_id":{"description":"Ledger category ID in FacturAI; not a FacturAI category key.","type":"string","x-go-name":"LedgerConnectionCategoryID"},"name":{"description":"Provider category display name.","type":"string"},"provider_category_id":{"description":"Category ID in the connected ledger; not a FacturAI category key.","type":"string","x-go-name":"ProviderCategoryID"}},"required":["ledger_connection_category_id","provider_category_id","name","group_name"],"title":"LedgerCategory","type":"object"},"content_contracts_facturai_shared_ledger-connections_LedgerCategoryList":{"additionalProperties":false,"properties":{"categories":{"description":"Saved ledger categories; empty if no data is available.","items":{"$ref":"#/components/schemas/content_contracts_facturai_shared_ledger-connections_LedgerCategory"},"type":"array"}},"required":["categories"],"title":"LedgerCategoryList","type":"object"},"content_contracts_facturai_shared_merchants_Merchant":{"additionalProperties":false,"properties":{"display_name":{"description":"Current merchant display name; may change without changing id.","type":"string"},"id":{"description":"Stable Household merchant UUID, usable as the exact merchant_id receipt filter.","type":"string","x-go-name":"ID"}},"required":["id","display_name"],"title":"Merchant","type":"object"},"content_contracts_facturai_shared_merchants_MerchantList":{"additionalProperties":false,"properties":{"merchants":{"description":"Merchants known to the current Household; identities are not shared across Households.","items":{"$ref":"#/components/schemas/content_contracts_facturai_shared_merchants_Merchant"},"type":"array"}},"required":["merchants"],"title":"MerchantList","type":"object"},"content_contracts_facturai_shared_probes_Liveness":{"additionalProperties":false,"properties":{"status":{"description":"ok means the API is responding; connected services are not checked.","type":"string"}},"required":["status"],"title":"Liveness","type":"object"},"content_contracts_facturai_shared_probes_Readiness":{"additionalProperties":false,"properties":{"database":{"description":"Database readiness indicator for this API process.","type":"string"},"status":{"description":"Readiness status; an unavailable database also returns HTTP 503.","type":"string"}},"required":["status","database"],"title":"Readiness","type":"object"},"content_contracts_facturai_shared_receipts_Actor":{"additionalProperties":false,"description":"User, API key or system responsible for an operation.","properties":{"id":{"description":"Stable actor identifier, not a credential.","type":"string","x-go-name":"ID"},"kind":{"description":"Actor category.","enum":["user","api","system"],"type":"string","x-enum-varnames":["ActorUser","ActorAPI","ActorSystem"]},"label":{"description":"Safe display label captured at the time of the operation.","type":"string"}},"required":["id","kind","label"],"title":"Actor","type":"object"},"content_contracts_facturai_shared_receipts_DetailDeletionWorkflow":{"additionalProperties":false,"properties":{"has_budget_artifacts":{"description":"Whether linked ledger entries remain and may need cleanup after deletion.","type":"boolean","x-go-name":"HasBudgetArtifacts"},"last_error_code":{"description":"Latest deletion or cleanup error code, or null.","nullable":true,"type":"string","x-go-name":"LastErrorCode","x-go-type-skip-optional-pointer":false}},"required":["has_budget_artifacts","last_error_code"],"title":"DetailDeletionWorkflow","type":"object"},"content_contracts_facturai_shared_receipts_DetailDestination":{"additionalProperties":false,"properties":{"category_name":{"description":"Linked ledger category name, or null.","nullable":true,"type":"string","x-go-name":"CategoryName","x-go-type-skip-optional-pointer":false},"ledger_connection_category_id":{"description":"Linked ledger category ID in FacturAI, or null.","nullable":true,"type":"string","x-go-name":"LedgerConnectionCategoryID","x-go-type-skip-optional-pointer":false},"ledger_connection_id":{"description":"Ledger connection ID for this category, or null.","nullable":true,"type":"string","x-go-name":"LedgerConnectionID","x-go-type-skip-optional-pointer":false},"scope":{"description":"Where the ledger category was chosen, such as receipt or product; null if unresolved.","nullable":true,"type":"string","x-go-name":"Scope","x-go-type-skip-optional-pointer":false},"source":{"description":"How the ledger category was selected, or null.","nullable":true,"type":"string","x-go-name":"Source","x-go-type-skip-optional-pointer":false}},"required":["ledger_connection_id","ledger_connection_category_id","scope"],"title":"DetailDestination","type":"object"},"content_contracts_facturai_shared_receipts_DetailDocument":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_ReceiptDocumentSummary"},{"properties":{"bank_transaction_waiting":{"description":"Whether the receipt is set to wait for a matching bank transaction.","type":"boolean","x-go-name":"BankTransactionWaiting"},"ledger_connection_pending_account_id":{"description":"Selected ledger account ID in FacturAI, or null.","nullable":true,"type":"string","x-go-name":"LedgerConnectionPendingAccountID","x-go-type-skip-optional-pointer":false},"ledger_connection_pending_transaction_id":{"description":"Selected ledger transaction ID, or null; does not confirm synchronization.","nullable":true,"type":"string","x-go-name":"LedgerConnectionPendingTransactionID","x-go-type-skip-optional-pointer":false},"line_order":{"description":"Line IDs in display order; use this to order entries from lines.","items":{"type":"string"},"nullable":true,"type":"array","x-go-name":"LineOrder"},"lines":{"additionalProperties":{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_DetailLine"},"description":"Receipt lines keyed by ID; use that ID, not a position, in JSON Patch paths.","nullable":true,"type":"object","x-go-name":"Lines"},"payment_mode_source":{"description":"How payment mode was selected: recognition, operator or default.","nullable":true,"type":"string","x-go-name":"PaymentModeSource","x-go-type-skip-optional-pointer":false}},"required":["payment_mode_source","ledger_connection_pending_account_id","ledger_connection_pending_transaction_id","bank_transaction_waiting","lines","line_order"],"type":"object"}],"title":"DetailDocument"},"content_contracts_facturai_shared_receipts_DetailLine":{"additionalProperties":false,"properties":{"amount_cents":{"description":"Signed line total in currency minor units; null if unknown. Discounts may be negative.","nullable":true,"type":"integer","x-go-name":"AmountCents","x-go-type":"int64","x-go-type-skip-optional-pointer":false},"destination":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_DetailDestination"}],"description":"Linked ledger category, separate from the FacturAI category.","x-go-name":"Destination"},"kind":{"description":"Line kind, such as item, discount or payment_adjustment.","type":"string","x-go-name":"Kind"},"name":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_DetailName"}],"description":"Original, normalized and localized representations of the line's name.","x-go-name":"Name"},"parent_id":{"description":"Parent line ID in document.lines; null for a top-level line.","nullable":true,"type":"string","x-go-name":"ParentID","x-go-type-skip-optional-pointer":false},"payment_role":{"description":"Payment-side interpretation for applicable lines; absent or null when not applicable.","nullable":true,"type":"string","x-go-name":"PaymentRole","x-go-type-skip-optional-pointer":false},"quantity":{"description":"Quantity, including fractions; null if unknown.","format":"double","nullable":true,"type":"number","x-go-name":"Quantity","x-go-type-skip-optional-pointer":false},"taxonomy":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_DetailTaxonomy"}],"description":"FacturAI category and how it was selected; null if unavailable.","nullable":true,"x-go-name":"Taxonomy","x-go-type-skip-optional-pointer":false},"taxonomy_editable":{"description":"Whether this line's FacturAI category can be edited.","type":"boolean","x-go-name":"TaxonomyEditable"},"unit_price_cents":{"description":"Unit price in currency minor units; null if unknown. The line total may differ.","nullable":true,"type":"integer","x-go-name":"UnitPriceCents","x-go-type":"int64","x-go-type-skip-optional-pointer":false}},"required":["parent_id","kind","name","quantity","unit_price_cents","amount_cents","taxonomy","taxonomy_editable","destination"],"title":"DetailLine","type":"object"},"content_contracts_facturai_shared_receipts_DetailMerchant":{"additionalProperties":false,"properties":{"id":{"description":"Household merchant ID; null if unknown.","nullable":true,"type":"string","x-go-name":"ID","x-go-type-skip-optional-pointer":false},"name":{"description":"Merchant display name; may be empty before recognition.","type":"string","x-go-name":"Name"}},"required":["id","name"],"title":"DetailMerchant","type":"object"},"content_contracts_facturai_shared_receipts_DetailName":{"additionalProperties":false,"properties":{"localized":{"description":"Server-provided localized display name; not a stable product identifier.","type":"string","x-go-name":"Localized"},"normalized":{"description":"Normalized name used for matching and the exact product filter.","type":"string","x-go-name":"Normalized"},"raw":{"description":"Original line text from recognition or an edit.","type":"string","x-go-name":"Raw"}},"required":["raw","normalized","localized"],"title":"DetailName","type":"object"},"content_contracts_facturai_shared_receipts_DetailSource":{"additionalProperties":false,"properties":{"available":{"description":"Whether the source file can be downloaded through /receipts/{id}/image.","type":"boolean","x-go-name":"Available"},"type":{"description":"Source kind: image, pdf, text or email; empty if unavailable. Not a MIME type.","type":"string","x-go-name":"Type"},"uploaded_at":{"description":"Receipt ingestion time, not the purchase date.","type":"string","x-go-name":"UploadedAt"}},"required":["available","type","uploaded_at"],"title":"DetailSource","type":"object"},"content_contracts_facturai_shared_receipts_DetailSyncWorkflow":{"additionalProperties":false,"properties":{"error":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_DetailWorkflowError"}],"description":"Current synchronization failure details; null when no failure is reported.","nullable":true,"x-go-name":"Error","x-go-type-skip-optional-pointer":false},"ledger_connection_account_id":{"description":"Currently linked ledger account ID, or null if no matching link exists.","nullable":true,"type":"string","x-go-name":"LedgerConnectionAccountID","x-go-type-skip-optional-pointer":false},"ledger_connection_transaction_id":{"description":"Currently linked ledger transaction ID, or null if no matching link exists.","nullable":true,"type":"string","x-go-name":"LedgerConnectionTransactionID","x-go-type-skip-optional-pointer":false}},"required":["ledger_connection_account_id","ledger_connection_transaction_id","error"],"title":"DetailSyncWorkflow","type":"object"},"content_contracts_facturai_shared_receipts_DetailTaxonomy":{"additionalProperties":false,"properties":{"key":{"description":"FacturAI category key; null if unassigned. Not a ledger category ID.","nullable":true,"type":"string","x-go-name":"Key","x-go-type-skip-optional-pointer":false},"source":{"description":"How the category was selected, such as recognition or operator; null if unknown.","nullable":true,"type":"string","x-go-name":"Source","x-go-type-skip-optional-pointer":false}},"required":["key","source"],"title":"DetailTaxonomy","type":"object"},"content_contracts_facturai_shared_receipts_DetailWorkflowError":{"additionalProperties":false,"properties":{"code":{"description":"Error code to use in automation, rather than message text.","type":"string","x-go-name":"Code"},"message":{"description":"Optional explanation of the failure; wording may change.","type":"string","x-go-name":"Message"},"retry_allowed":{"description":"Whether a retry is allowed; not whether one is scheduled.","type":"boolean","x-go-name":"RetryAllowed"}},"required":["code","retry_allowed"],"title":"DetailWorkflowError","type":"object"},"content_contracts_facturai_shared_receipts_ReceiptDocumentSummary":{"description":"Purchase facts shared by receipt summaries and full documents.","properties":{"currency":{"description":"Receipt currency; all _cents amounts use its minor units.","type":"string","x-go-name":"Currency"},"date":{"description":"Purchase date in YYYY-MM-DD format; null until known.","nullable":true,"type":"string","x-go-name":"Date","x-go-type-skip-optional-pointer":false},"merchant":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_DetailMerchant"}],"description":"Merchant ID and display name.","x-go-name":"Merchant"},"payment_mode":{"description":"Payment mode: bank or cash; null if unknown.","nullable":true,"type":"string","x-go-name":"PaymentMode","x-go-type-skip-optional-pointer":false},"time":{"description":"Purchase time printed on the receipt; null until known.","nullable":true,"type":"string","x-go-name":"Time","x-go-type-skip-optional-pointer":false},"total_cents":{"description":"Printed total in currency minor units; null if unknown.","nullable":true,"type":"integer","x-go-name":"TotalCents","x-go-type":"int64","x-go-type-skip-optional-pointer":false}},"required":["merchant","date","time","currency","total_cents","payment_mode"],"title":"ReceiptDocumentSummary","type":"object"},"content_contracts_facturai_shared_receipts_ReceiptMeta":{"additionalProperties":false,"description":"Document version, record timestamps and who created or updated it.","properties":{"author":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_Actor"}],"description":"Who created the receipt; system if unknown."},"created_at":{"description":"Time the receipt record was created in FacturAI, in UTC.","format":"date-time","type":"string","x-go-type":"string"},"updated_at":{"description":"Last record update in UTC, including background processing and locks.","format":"date-time","type":"string","x-go-type":"string"},"updater":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_Actor"}],"description":"Who last updated the record, including background processing."},"version":{"description":"Receipt mutation version used by ETag and If-Match.","minimum":1,"type":"integer","x-go-type":"int"}},"required":["version","created_at","updated_at","author","updater"],"title":"ReceiptMeta","type":"object"},"content_contracts_facturai_shared_receipts_ReceiptPatchOperation":{"additionalProperties":false,"properties":{"from":{"description":"Source JSON Pointer for move or copy, relative to the patch's starting document.","type":"string"},"op":{"description":"JSON Patch operation (RFC 6902); only supported paths and values can be edited.","enum":["add","remove","replace","move","copy","test"],"type":"string"},"path":{"description":"Target JSON Pointer relative to the patch's starting document.","type":"string"},"value":{"description":"New value for add, replace or test."}},"required":["op","path"],"title":"ReceiptPatchOperation","type":"object"},"content_contracts_facturai_shared_receipts_ReceiptUpload":{"additionalProperties":false,"properties":{"image":{"description":"Receipt image (JPEG or PNG) or PDF, sent as a multipart file.","format":"binary","type":"string"},"source_sha256":{"description":"Optional SHA-256 of the original file; if invalid, FacturAI hashes the uploaded bytes.","type":"string"}},"required":["image"],"title":"ReceiptUpload","type":"object"},"content_contracts_facturai_shared_taxonomy_CategoryCopy":{"additionalProperties":false,"properties":{"description":{"description":"Category description in this locale.","maxLength":200,"type":"string"},"label":{"description":"Category name in this locale.","maxLength":30,"minLength":1,"type":"string"}},"required":["label","description"],"title":"CategoryCopy","type":"object"},"content_contracts_facturai_shared_taxonomy_CategoryCreate":{"additionalProperties":false,"properties":{"emoji":{"description":"Category emoji; omit to use the default.","maxLength":16,"type":"string"},"llm_descriptions":{"additionalProperties":{"maxLength":300,"type":"string"},"description":"Optional recognition guidance, keyed by locale.","type":"object"},"parent_key":{"description":"Key of the parent category.","type":"string"},"translations":{"additionalProperties":{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_CategoryCopy"},"description":"Names and descriptions keyed by locale, such as en-US or ru-RU. At least one is required.","maxProperties":8,"minProperties":1,"type":"object"}},"required":["parent_key","translations"],"title":"CategoryCreate","type":"object"},"content_contracts_facturai_shared_taxonomy_CategoryCreated":{"additionalProperties":false,"properties":{"category":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomyCategory"}],"description":"Created category and its generated key."},"revision":{"description":"Updated category revision; send it with your next change.","format":"int64","type":"integer"},"taxonomy_version":{"description":"Version of FacturAI's built-in category tree.","type":"integer"}},"required":["category","revision","taxonomy_version"],"title":"CategoryCreated","type":"object"},"content_contracts_facturai_shared_taxonomy_TaxonomyCategory":{"additionalProperties":false,"properties":{"archived":{"description":"Whether the category is hidden; existing assignments are preserved.","type":"boolean"},"emoji":{"description":"Category emoji used for display.","type":"string"},"key":{"description":"Stable category key; unchanged when renamed or moved.","type":"string"},"llm_descriptions":{"additionalProperties":{"type":"string"},"description":"Recognition guidance keyed by locale; null when none is supplied.","nullable":true,"type":"object"},"parent_key":{"description":"Current parent category key.","type":"string"},"translations":{"additionalProperties":{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_CategoryCopy"},"description":"Names and descriptions keyed by locale.","type":"object"}},"required":["key","parent_key","emoji","translations","llm_descriptions","archived"],"title":"TaxonomyCategory","type":"object"},"content_contracts_facturai_shared_taxonomy_TaxonomyNode":{"additionalProperties":false,"properties":{"archived":{"description":"Whether this node is hidden from ordinary category choices.","type":"boolean"},"assignable":{"description":"Whether this category can be assigned to a receipt line.","type":"boolean"},"children":{"description":"Subcategories in display order.","items":{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomyNode"},"type":"array"},"description":{"description":"Category description in the selected display language.","type":"string"},"emoji":{"description":"Category emoji in the effective tree, when provided.","type":"string"},"key":{"description":"Stable category key; use this instead of the display name.","type":"string"},"label":{"description":"Category name in the selected display language.","type":"string"},"parent_key":{"description":"Parent category key, when available.","type":"string"},"read_only":{"description":"Whether this is a built-in category that cannot be edited.","type":"boolean"}},"required":["key","label","description","assignable","read_only","children"],"title":"TaxonomyNode","type":"object"},"content_contracts_facturai_shared_taxonomy_TaxonomyProblem":{"additionalProperties":false,"properties":{"emoji":{"description":"Recovered emoji, if available.","type":"string"},"key":{"description":"Recovered category key; use record_id, not this key, for cleanup.","type":"string"},"label":{"description":"Recovered display name, if available.","type":"string"},"reason":{"description":"Reason this category record cannot be used.","type":"string"},"record_id":{"description":"Record ID to use for cleanup, rather than the category key.","type":"string","x-go-name":"RecordID"}},"required":["reason"],"title":"TaxonomyProblem","type":"object"},"content_contracts_facturai_shared_taxonomy_TaxonomyProblems":{"additionalProperties":false,"properties":{"problems":{"description":"Custom category records that cannot be used, with reasons.","items":{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomyProblem"},"type":"array"},"revision":{"description":"Current revision for removal previews and cleanup.","format":"int64","type":"integer"}},"required":["revision","problems"],"title":"TaxonomyProblems","type":"object"},"content_contracts_facturai_shared_taxonomy_TaxonomyRemoval":{"additionalProperties":false,"properties":{"effect":{"description":"hide preserves assignments; delete removes the category and may require receipt corrections.","enum":["hide","delete"],"type":"string"},"keep_subcategories":{"default":false,"description":"Promote children instead of removing the whole descendant branch.","type":"boolean"},"revision":{"description":"Latest category revision; a stale value returns 409.","format":"int64","minimum":0,"type":"integer"}},"required":["revision","effect"],"title":"TaxonomyRemoval","type":"object"},"content_contracts_facturai_shared_taxonomy_TaxonomyRemovalImpact":{"additionalProperties":false,"properties":{"receipts":{"description":"Number of receipts affected by this removal; the preview makes no changes.","format":"int64","type":"integer"}},"required":["receipts"],"title":"TaxonomyRemovalImpact","type":"object"},"content_contracts_facturai_shared_taxonomy_TaxonomyRevision":{"additionalProperties":false,"properties":{"revision":{"description":"Latest category revision; a stale value returns 409.","format":"int64","minimum":0,"type":"integer"}},"required":["revision"],"title":"TaxonomyRevision","type":"object"},"content_contracts_facturai_shared_taxonomy_TaxonomySettings":{"additionalProperties":false,"properties":{"asset_id":{"description":"Built-in category tree ID; preserve it when saving settings.","type":"string","x-go-name":"AssetID"},"can_manage":{"description":"Whether the caller can manage categories; not a category property.","type":"boolean"},"categories":{"description":"Household custom categories, including hidden ones; excludes built-in categories.","items":{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomyCategory"},"type":"array"},"created_key":{"description":"New category key, when this response follows creation.","type":"string"},"localized_entries":{"additionalProperties":{"additionalProperties":{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_CategoryCopy"},"type":"object"},"description":"Category names and descriptions, indexed by category key and then locale.","type":"object"},"problems":{"description":"Invalid custom category records; use the problems endpoint for cleanup.","items":{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomyProblem"},"type":"array"},"revision":{"description":"Current revision; send it with the next change, or read again after a conflict.","format":"int64","type":"integer"},"root":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomyNode"}],"description":"Built-in and custom categories available to this Household."},"taxonomy_version":{"description":"Version of the built-in category tree.","type":"integer"}},"required":["asset_id","revision","categories","taxonomy_version","root","can_manage","localized_entries"],"title":"TaxonomySettings","type":"object"},"content_contracts_facturai_shared_taxonomy_TaxonomySettingsWrite":{"additionalProperties":false,"properties":{"asset_id":{"description":"Built-in category tree ID from the latest settings response.","type":"string","x-go-name":"AssetID"},"categories":{"description":"Complete custom-category list; include every category you want to keep.","items":{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomyCategory"},"type":"array"},"problems":{"description":"Optional legacy field; ignored. Use the problems endpoint for cleanup.","items":{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomyProblem"},"type":"array"},"revision":{"description":"Revision from the latest settings response; a stale value returns 409.","format":"int64","minimum":0,"type":"integer"}},"required":["asset_id","revision","categories"],"title":"TaxonomySettingsWrite","type":"object"},"content_contracts_facturai_shared_taxonomy_TaxonomyTree":{"additionalProperties":false,"properties":{"can_manage":{"description":"Whether this caller has permission to manage categories.","type":"boolean"},"revision":{"description":"Current category revision; send it with category changes.","format":"int64","type":"integer"},"root":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomyNode"}],"description":"Built-in and Household custom categories in the selected display language."},"taxonomy_version":{"description":"Version of the built-in category tree.","type":"integer"}},"required":["taxonomy_version","revision","root","can_manage"],"title":"TaxonomyTree","type":"object"},"receipts_Receipt":{"additionalProperties":false,"description":"Receipt details and full purchase document.","properties":{"document":{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_DetailDocument"},"id":{"description":"Stable receipt UUID.","type":"string","x-go-name":"ID"},"meta":{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_ReceiptMeta"},"recognition_locale":{"description":"Locale used for recognition.","type":"string"},"source":{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_DetailSource"}},"required":["id","meta","recognition_locale","source","document"],"title":"Receipt","type":"object"},"receipts_ReceiptCreate":{"additionalProperties":false,"description":"Purchase data for creating a receipt without recognition. Unknown fields are rejected.","example":{"currency":"EUR","date":"2026-10-18","lines":[{"amount_cents":150,"name":"Milk","quantity":1},{"amount_cents":200,"name":"Bread","quantity":1}],"merchant":"Local grocery","payment_mode":"cash","total_cents":350},"properties":{"currency":{"description":"Supported currency code for all amounts, for example EUR; see /household/settings.","maxLength":3,"minLength":3,"type":"string"},"date":{"description":"Purchase date (YYYY-MM-DD), not the record creation date.","format":"date","type":"string","x-go-type":"string"},"lines":{"description":"Ordered lines; the server generates receipt and line IDs.","items":{"$ref":"#/components/schemas/receipts_ReceiptCreateLine"},"maxItems":150,"minItems":1,"type":"array"},"merchant":{"description":"Merchant name; omit if unknown.","maxLength":300,"type":"string"},"payment_mode":{"description":"Payment mode: bank or cash; omit if unknown. This does not confirm ledger synchronization.","enum":["bank","cash"],"type":"string","x-go-type-skip-optional-pointer":false},"time":{"description":"Purchase time (HH:MM or HH:MM:SS); omit if unknown.","type":"string","x-go-type-skip-optional-pointer":false},"total_cents":{"description":"Printed total in minor units, including zero; may differ from the line sum.","maximum":100000000,"minimum":-100000000,"type":"integer","x-go-type":"*int64"}},"required":["date","currency","total_cents","lines"],"title":"ReceiptCreate","type":"object"},"receipts_ReceiptCreateLine":{"additionalProperties":false,"description":"One receipt line, supplied in document order.","properties":{"amount_cents":{"description":"Signed line total in minor units; only item/other may omit it or use null.","maximum":100000000,"minimum":-100000000,"nullable":true,"type":"integer","x-go-type":"int64","x-go-type-skip-optional-pointer":false},"kind":{"description":"Line kind; defaults to item.","enum":["item","discount","deposit","rounding","loyalty_purchase","loyalty_redemption","other"],"type":"string"},"name":{"description":"Original line name; matching and translated names are generated automatically.","maxLength":500,"minLength":1,"type":"string"},"parent_index":{"description":"Parent's zero-based index in lines. Must not point to this line or create a cycle.","minimum":0,"type":"integer","x-go-type":"int","x-go-type-skip-optional-pointer":false},"quantity":{"description":"Positive quantity, including fractions; null or omitted if unknown.","exclusiveMinimum":true,"format":"double","minimum":0,"nullable":true,"type":"number","x-go-type-skip-optional-pointer":false},"taxonomy_key":{"description":"Selectable category key; if omitted, FacturAI classifies the line or marks it for review.","type":"string","x-go-type-skip-optional-pointer":false},"unit_price_cents":{"description":"Signed unit price in currency minor units; null or omitted if unknown.","maximum":100000000,"minimum":-100000000,"nullable":true,"type":"integer","x-go-type":"int64","x-go-type-skip-optional-pointer":false}},"required":["name"],"title":"ReceiptCreateLine","type":"object"},"receipts_ReceiptDocumentPatch":{"description":"JSON Patch with paths relative to receipt.document.","items":{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_ReceiptPatchOperation"},"title":"ReceiptDocumentPatch","type":"array"},"receipts_ReceiptList":{"additionalProperties":false,"description":"One page of receipt summaries.","properties":{"items":{"description":"Compact receipts, newest first; read by ID for the full document.","items":{"$ref":"#/components/schemas/receipts_ReceiptSummary"},"type":"array"},"next_cursor":{"description":"Cursor for the next page, or null. Keep the same filters and limit.","nullable":true,"type":"string","x-go-type-skip-optional-pointer":false}},"required":["items","next_cursor"],"title":"ReceiptList","type":"object"},"receipts_ReceiptResponse":{"additionalProperties":false,"description":"Receipt and its full document.","properties":{"receipt":{"allOf":[{"$ref":"#/components/schemas/receipts_Receipt"}],"description":"Receipt details, source and full document."}},"required":["receipt"],"title":"ReceiptResponse","type":"object"},"receipts_ReceiptSummary":{"additionalProperties":false,"description":"Receipt ID, metadata and purchase summary.","properties":{"document":{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_ReceiptDocumentSummary"},"id":{"description":"Stable receipt UUID.","type":"string","x-go-name":"ID"},"meta":{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_ReceiptMeta"}},"required":["id","meta","document"],"title":"ReceiptSummary","type":"object"},"receipts_ReceiptWorkflow":{"additionalProperties":false,"description":"Recognition, receipt and ledger synchronization status.","properties":{"deletion":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_DetailDeletionWorkflow"}],"description":"Deletion errors and remaining ledger entries."},"display_status":{"description":"Combined receipt and processing status; see the status filter guide.","type":"string"},"receipt_id":{"description":"Current receipt ID; may change when duplicate receipts are merged.","type":"string","x-go-name":"ReceiptID"},"receipt_version":{"description":"Document version used for this status. Read the receipt's ETag before editing.","type":"integer","x-go-type":"int"},"recognition_attempts":{"description":"Number of recorded recognition attempts, including retries.","type":"integer","x-go-type":"int"},"recognition_error":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_DetailWorkflowError"}],"description":"Current recognition failure details, or null.","nullable":true,"x-go-type-skip-optional-pointer":false},"recognition_last_attempt_at":{"description":"Timestamp of last recognition attempt; null before the first attempt.","nullable":true,"type":"string","x-go-type-skip-optional-pointer":false},"recognition_next_attempt_at":{"description":"Next scheduled recognition retry, or null.","nullable":true,"type":"string","x-go-type-skip-optional-pointer":false},"recognition_status":{"description":"Recognition status: processing, complete or failed.","type":"string"},"state":{"description":"Receipt status; done does not mean the ledger is synchronized.","type":"string"},"sync":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_DetailSyncWorkflow"}],"description":"Linked ledger account, transaction and any synchronization error."},"sync_status":{"description":"Ledger synchronization: pending, synced, failed, or null if not applicable.","nullable":true,"type":"string","x-go-type-skip-optional-pointer":false},"sync_waiting_for":{"description":"What synchronization is waiting for: account, bank_transaction, or null.","nullable":true,"type":"string","x-go-type-skip-optional-pointer":false}},"required":["receipt_id","receipt_version","state","display_status","recognition_status","recognition_attempts","recognition_last_attempt_at","recognition_next_attempt_at","recognition_error","sync_status","sync_waiting_for","sync","deletion"],"title":"ReceiptWorkflow","type":"object"}},"securitySchemes":{"APIKeyBearer":{"description":"Household API key with permissions for the requested operation.","scheme":"bearer","type":"http"}}},"info":{"description":"Create and read receipts, recognize uploaded images or PDFs, manage categories\nand export your Household's purchase history.\n\n## Get started\n\n1. As a Household administrator, open **Household settings → Developer → API**.\n   Create a key and choose the permissions your integration needs.\n2. Enter it under **Authentication** in this reference. Requests use\n   `Authorization: Bearer \u003cyour-api-key\u003e`.\n3. Try **List receipts**, then read a receipt using its ID.\n\nRequests go directly to this API. Paths have no `/api` prefix. The playground\nkeeps your key only for the current page session. Never put real keys in URLs,\nsource control or shared examples.\n\n## API keys and permissions\n\nEach key belongs to one Household. You do not need to send a Household ID,\nand a browser sign-in session cannot be used as an API key. Create a separate\nkey for each integration. Selecting write also enables the matching read permission.\nTo stop an integration's access, delete its key in Household settings.\n\n| Permission | Access |\n| --- | --- |\n| `receipts:read` | List and read receipts, check processing and download source files |\n| `receipts:write` | Create, upload, edit and delete receipts |\n| `taxonomy:read` | Read category settings, problems and removal previews |\n| `taxonomy:write` | Create, edit, move, hide, restore and delete custom categories |\n| `references:read` | Read categories, merchants, ledger accounts and currencies |\n| `exports:read` | List exports, check progress and get download links |\n| `exports:write` | Start exports |\n\n## Receipts: list, document and processing\n\n| Operation | What you get |\n| --- | --- |\n| `GET /receipts` | A page of `items` and `next_cursor`. Each item has `id`, `meta` and a compact `document`, without lines. |\n| `GET /receipts/{id}` | A `receipt` with `id`, `meta`, `recognition_locale`, `source` and the full `document`. |\n| `PATCH /receipts/{id}/document` | Edits to `receipt.document`; returns the updated document only. |\n| `GET /receipts/{id}/workflow` | Processing status, errors, retry information, ledger synchronization and deletion progress. |\n\nCreation and upload return the same `receipt` shape as reading by ID.\nShared purchase fields have the same names in the list and full document:\n`document.date`, `time`, `merchant`, `currency`, `total_cents` and\n`payment_mode`. The full document also has lines and payment details.\nNeither response includes statistics; calculate them in your integration.\nRead `/workflow` separately when you need processing status.\n\nAmounts ending in `_cents` are integers in the receipt currency's minor units.\nA null amount is unknown, not zero. Download the source file through\n`/receipts/{id}/image`; check its `Content-Type`.\n\n### Metadata and date filters\n\n`meta` has the same shape in list and detail responses:\n\n| Field | Meaning |\n| --- | --- |\n| `version` | Document version used for edits |\n| `created_at` | When the receipt was created in FacturAI, in UTC |\n| `updated_at` | Last record update in UTC, including background processing |\n| `author`, `updater` | Who created and last updated the record: a user, API key or system |\n\nActors are non-null objects with `id`, `kind` and `label`. Background work\ncan update `updated_at` and `updater` without changing the document version.\n\nList filters use purchase data, not record creation or update timestamps:\n\n| Filter | Matches |\n| --- | --- |\n| `start_date`, `end_date` | `document.date`: start included, end excluded, in YYYY-MM-DD format |\n| `merchant_id`, `merchant_search` | Merchant ID or name |\n| `product`, `product_search`, `category` | Receipt lines, even though lines are not returned in the list |\n| `status` | Processing groups described below |\n\nEither date bound is optional. A supplied bound excludes receipts with an\nunknown purchase date. Listing is newest purchase date and time first, then\ncreation time and ID. Undated receipts use their creation day for sorting only.\nRecord timestamp and actor filters are not available.\n\n### Processing status\n\nThe list's `status` filter selects a group, not an exact workflow status:\n\n| Filter | Matching `workflow.display_status` values |\n| --- | --- |\n| `requires_attention` | `needs_input`, `recognition_failed`, `sync_failed` |\n| `processing` | `recognizing`, `waiting_for_transaction`, `syncing` |\n| Omitted | All matching receipts, including `saved` and `synced` |\n\nThese are the only filter values; `done` and `completed` are not supported.\nThe workflow response separates three kinds of progress:\n\n| Field | Values |\n| --- | --- |\n| `state` | Receipt status: `processing`, `needs_attention`, `done`, `failed`; older drafts may use `draft` |\n| `recognition_status` | `processing`, `complete` or `failed` |\n| `sync_status` | Ledger synchronization: `pending`, `synced`, `failed`, or null when not applicable |\n\nA receipt can be `done` but still wait for a bank transaction. It then has\n`display_status=waiting_for_transaction` and matches `status=processing`.\nA receipt saved without a ledger has `display_status=saved` and\n`sync_status=null`. A workflow read may be newer than the preceding list.\n\n## Automation examples\n\n### Create a receipt from data you already have\n\nFor a shop integration or expense importer, use `receipts:write`. No image\nor AI recognition is needed. Add `receipts:read` to read the result later.\n\n```http\nPOST /receipts\nAuthorization: Bearer \u003cyour-api-key\u003e\nContent-Type: application/json\nIdempotency-Key: 61f7fc9d-1bea-4b5e-984b-1c65d924637e\n\n{\n  \"merchant\": \"Local grocery\",\n  \"date\": \"2026-10-18\",\n  \"currency\": \"EUR\",\n  \"total_cents\": 350,\n  \"payment_mode\": \"cash\",\n  \"lines\": [\n    {\"name\": \"Milk\", \"quantity\": 1, \"amount_cents\": 150},\n    {\"name\": \"Bread\", \"quantity\": 1, \"amount_cents\": 200}\n  ]\n}\n```\n\nSave `receipt.id` and the response's `Location` and `ETag` headers.\nA new receipt returns `201`. Reusing the UUID with the same JSON returns\n`200` and the same receipt's current data, including any later edits.\nReusing it with different data, or after deleting that receipt, returns `409`.\nWithout `Idempotency-Key`, every request creates a new receipt.\nUse one UUID per receipt, not one for the whole import.\n\n### Recognize an image or PDF\n\nRequires `receipts:write` to upload and `receipts:read` to follow progress.\n\n1. Send `POST /receipts/uploads` with a multipart `image` field containing\n   JPEG, PNG or PDF. Save the returned receipt ID.\n2. `201` means a new source was accepted. `200` means the source matched an\n   existing receipt, which may be reopened. Both return JSON, not a redirect.\n3. Poll `GET /receipts/{id}/workflow` with increasing delays.\n   `recognition_status=complete` means facts are available; `failed` has\n   details in `recognition_error`. A recognized receipt may still need input.\n4. Read `GET /receipts/{id}` for the document.\n\nRecognition can later discover that another upload represents the same\npurchase. Save the current ID from workflow `receipt_id` or the read\nresponse's `Location`, and use it for later edits or deletion.\nThere is no public command to retry recognition. Ledger synchronization\nhas its own status and may continue after recognition is complete.\n\n### Find and edit a receipt\n\nRequires `receipts:read` and `receipts:write`.\n\n1. List purchases with, for example,\n   `GET /receipts?start_date=2026-10-01\u0026end_date=2026-11-01`.\n2. Pass `next_cursor` as `cursor` for the next page, keeping the same\n   filters and limit. Stop when it is null. Cursors are not page numbers.\n3. Read the receipt by ID. Keep its `Location` and `ETag`, then copy\n   `receipt.document` as the starting point for your edits.\n4. Send a JSON Patch against that document. Paths start at the document,\n   not at the response wrapper:\n\n```http\nPATCH /receipts/{id}/document\nAuthorization: Bearer \u003cyour-api-key\u003e\nContent-Type: application/json-patch+json\nIf-Match: \"3\"\n\n[{\"op\":\"replace\",\"path\":\"/merchant/name\",\"value\":\"Corrected shop\"}]\n```\n\nThe response is the updated document, with a new or unchanged `ETag`.\nA `409` means you must read again and reconcile your edit with newer data.\nDo not just replace `If-Match` and resend the old patch.\n\nLines are keyed by UUID: use `/lines/{line_id}/amount_cents`, not `/lines/0`.\nKeep `lines` and `line_order` consistent when adding or removing lines.\nReplacing the whole document, lines map or an existing line is not supported;\nunsupported paths or values return `400 invalid_receipt_patch`.\nMetadata and processing status are read-only.\nRead again if you also need updated metadata. Workflow changes do not always\nchange the document's `ETag`; responses are not cached.\n\n### Look up and manage categories\n\nWith `references:read`, use `GET /taxonomy` for selectable category keys,\n`GET /merchants` for merchant IDs and `GET /household/settings` for currencies.\nLedger accounts and categories are available under\n`/ledger-connections/current/accounts` and `/ledger-connections/current/categories`.\nThese are saved snapshots; reading them does not refresh the connected service.\nLedger category IDs and FacturAI category keys are different identifiers.\n\nTo add a custom category, send `POST /taxonomy/categories` with\n`taxonomy:write`, a `parent_key` and localized `translations`.\nUse the returned `category.key` on receipt lines.\nBefore editing, moving or removing categories, read the latest settings with\n`taxonomy:read` and send their `revision` with your change.\nSaving settings replaces the custom-category list, so include all categories\nyou want to keep. System categories cannot be changed.\n\nPreview removal impact before hiding or deleting a category. Hiding preserves\nexisting assignments; deletion may require receipt corrections.\nOnly hidden categories can be restored. Category creation has no retry key:\nafter an unclear response, check the tree before creating it again.\n\n### Export purchase history\n\nRequires `exports:write` to start and `exports:read` to check and download.\n\n1. Send `POST /exports` with `{\"format\":\"csv\",\"idempotency_key\":\"\u003cuuid\u003e\"}`.\n   Use `json` or `excel` for JSON or XLSX. Reuse the UUID when retrying.\n   You can also supply it in `Idempotency-Key`; if both are present, they must match.\n2. Poll `GET /exports/{id}` with increasing delays. Wait for `succeeded`;\n   `queued` and `running` are not ready, and `failed` may include `last_error_code`.\n3. Request `GET /exports/{id}/download`. It returns `url` and `expires_at`,\n   not the file itself. Download from that URL without forwarding your API key.\n   The URL is a temporary credential; request a new one after it expires.\n\nUse exports for a full-history snapshot. Receipt listing is not a feed of changes.\n\n### Delete a receipt\n\nSend `DELETE /receipts/{id}` with `receipts:write`. A `204` means deletion\nhas finished in FacturAI. A `202` means it will finish after current work;\npoll by ID until `404` if you need confirmation.\nCleanup in a connected ledger can finish later.\n\n## Errors and retries\n\nUse `code` for error handling, when present. The `error` and optional `message`\nfields explain the problem; their wording can change.\n\n| Status | What to do |\n| --- | --- |\n| `401` | Check that the API key is present, valid and not expired or deleted |\n| `403` | Check the key's permissions |\n| `404` | Check the ID and Household; resources in another Household are not visible |\n| `400` / `422` | Fix the request before retrying |\n| `409` | Refresh the document version or category revision, or check retry-key reuse |\n| `429` | Wait before retrying; another key in the same Household does not bypass limits |\n| Network error / `5xx` | Retry reads with backoff; retry manual creation or export with the same saved UUID |\n\nDo not automatically replay other writes after an unclear response.\n","title":"FacturAI API","version":"0.7.0-PREVIEW"},"openapi":"3.0.3","paths":{"/exports":{"get":{"description":"Browse this Household's exports and their current progress.\n\n**Permission:** `exports:read`\n","operationId":"ExportsList","parameters":[{"description":"One-based page number; defaults to 1.","in":"query","name":"page","schema":{"default":1,"minimum":1,"type":"integer","x-go-type":"int","x-go-type-skip-optional-pointer":false}},{"description":"Number of export runs per page: 20 (default), 50 or 100.","in":"query","name":"page_size","schema":{"default":20,"enum":[20,50,100],"type":"integer","x-go-type":"int","x-go-type-skip-optional-pointer":false}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_exports_ExportPage"}]}}},"description":"Export history and page information."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"List export runs","tags":["exports"],"x-required-scopes":["exports:read"]},"post":{"description":"Prepare a JSON, CSV or XLSX file in the background. Supply a UUID in\n`Idempotency-Key` or `idempotency_key` and reuse it for retries.\nIf both are supplied, they must match. Reusing a key with another format\nreturns 409 `idempotency_key_reused`.\n\n**Permission:** `exports:write`\n","operationId":"ExportsCreate","parameters":[{"in":"header","name":"Idempotency-Key","schema":{"description":"UUID; required unless supplied in idempotency_key.","type":"string","x-go-type-skip-optional-pointer":false}}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_exports_ExportCreate"}]}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_exports_ExportRun"}]}}},"description":"Existing export has finished, successfully or with an error."},"202":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_exports_ExportRun"}]}}},"description":"Export queued or still processing."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Start an export","tags":["exports"],"x-required-scopes":["exports:write"]}},"/exports/{id}":{"get":{"description":"Check an export's progress and file information. Poll with increasing\ndelays while queued or running. Only succeeded exports can be downloaded.\n\n**Permission:** `exports:read`\n","operationId":"ExportsGet","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_exports_ExportRun"}]}}},"description":"Current export progress and file information."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Check export progress","tags":["exports"],"x-required-scopes":["exports:read"]}},"/exports/{id}/download":{"get":{"description":"Get a temporary download URL for a succeeded export. The response contains\nthe link, not the file. Download without sending your FacturAI API key.\n\n**Permission:** `exports:read`\n","operationId":"ExportsDownload","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_exports_ExportDownload"}]}}},"description":"Temporary download URL and expiry time."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Get an export download link","tags":["exports"],"x-required-scopes":["exports:read"]}},"/household/settings":{"get":{"description":"Read the Household's base currency, selected currencies and saved exchange\nrates. This does not change settings or refresh rates.\n\n**Permission:** `references:read`\n","operationId":"HouseholdSettingsGet","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_household_HouseholdSettings"}]}}},"description":"Currencies and exchange-rate information."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Read currencies and Household settings","tags":["household"],"x-required-scopes":["references:read"]}},"/ledger-connections/current/accounts":{"get":{"description":"Read saved accounts from the connected ledger. This does not refresh the\nledger or start synchronization.\n\n**Permission:** `references:read`\n","operationId":"LedgerConnectionsAccountsList","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_ledger-connections_LedgerAccountList"}]}}},"description":"Saved ledger accounts."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"List ledger accounts","tags":["ledger-connections"],"x-required-scopes":["references:read"]}},"/ledger-connections/current/categories":{"get":{"description":"Read saved categories from the connected ledger. These are ledger\ncategories, not FacturAI category keys. This does not refresh the ledger.\n\n**Permission:** `references:read`\n","operationId":"LedgerConnectionsCategoriesList","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_ledger-connections_LedgerCategoryList"}]}}},"description":"Saved ledger categories."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"List ledger categories","tags":["ledger-connections"],"x-required-scopes":["references:read"]}},"/merchants":{"get":{"description":"Read merchants known to this Household. Use their IDs in receipt filters.\n\n**Permission:** `references:read`\n","operationId":"MerchantsList","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_merchants_MerchantList"}]}}},"description":"Merchant IDs and names."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"List merchants","tags":["merchants"],"x-required-scopes":["references:read"]}},"/probes/live":{"get":{"description":"Check that the API is running. No API key is required.","operationId":"ProbesLive","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_probes_Liveness"}]}}},"description":"The process is running."}},"security":[],"summary":"Check process liveness","tags":["probes"]}},"/probes/ready":{"get":{"description":"Check that the API can reach its database. No API key is required.","operationId":"ProbesReady","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_probes_Readiness"}]}}},"description":"The database is reachable."},"503":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_probes_Readiness"}]}}},"description":"The database is unavailable."}},"security":[],"summary":"Check database readiness","tags":["probes"]}},"/receipts":{"get":{"description":"Find receipts using purchase filters and pagination. Read by ID for the full\ndocument, or use /receipts/{id}/workflow for processing status.\n","operationId":"ReceiptsList","parameters":[{"$ref":"#/components/parameters/receipts_ReceiptsSelectionParams"},{"$ref":"#/components/parameters/receipts_ReceiptsListOptionsParams"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/receipts_ReceiptList"}]}}},"description":"Receipt summaries and the cursor for the next page."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"List receipts","tags":["receipts"],"x-required-scopes":["receipts:read"]},"post":{"description":"Create a receipt from known facts without AI recognition.\nSupply a UUID Idempotency-Key to safely retry the same creation request.\n","operationId":"ReceiptsCreate","parameters":[{"description":"UUID for this creation request; reuse it with the same JSON when retrying.","in":"header","name":"Idempotency-Key","schema":{"format":"uuid","type":"string","x-go-type":"string","x-go-type-skip-optional-pointer":false}}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/receipts_ReceiptCreate"}]}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/receipts_ReceiptResponse"}]}}},"description":"Current data for the receipt created by the original request.","headers":{"ETag":{"description":"Quoted current receipt version, which may have changed since creation.","schema":{"type":"string"}},"Location":{"description":"Relative URL for reading the existing receipt.","schema":{"type":"string"}}}},"201":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/receipts_ReceiptResponse"}]}}},"description":"Receipt created without recognition.","headers":{"ETag":{"description":"Quoted current receipt version for a subsequent JSON Patch.","schema":{"type":"string"}},"Location":{"description":"Relative URL for reading the created receipt by ID.","schema":{"type":"string"}}}},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Create a receipt from JSON","tags":["receipts"],"x-required-scopes":["receipts:write"]}},"/receipts/uploads":{"post":{"description":"Upload a receipt image or PDF. Recognition runs in the background.\nReturns 201 for a new source, or 200 when the source matches an existing receipt.\n","operationId":"ReceiptsUpload","requestBody":{"content":{"multipart/form-data":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_ReceiptUpload"}]}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/receipts_ReceiptResponse"}]}}},"description":"The source matched an existing receipt.","headers":{"ETag":{"description":"Quoted current receipt version.","schema":{"type":"string"}},"Location":{"description":"Relative read URL for the receipt returned by this upload.","schema":{"type":"string"}}}},"201":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/receipts_ReceiptResponse"}]}}},"description":"New receipt accepted for recognition.","headers":{"ETag":{"description":"Quoted current receipt version; recognition may advance it asynchronously.","schema":{"type":"string"}},"Location":{"description":"Relative read URL for the newly accepted receipt.","schema":{"type":"string"}}}},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Upload a receipt for recognition","tags":["receipts"],"x-required-scopes":["receipts:write"]}},"/receipts/{id}":{"delete":{"description":"Delete a receipt. Returns 204 when finished, or 202 if current processing\nmust finish first. Cleanup in a connected ledger may continue afterward.\n\n**Permission:** `receipts:write`\n","operationId":"ReceiptsDelete","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Deletion accepted; waiting for current processing to finish."},"204":{"description":"Receipt deleted."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Delete a receipt","tags":["receipts"],"x-required-scopes":["receipts:write"]},"get":{"description":"Read the full document and receipt metadata. Edit receipt.document through\nPATCH /receipts/{id}/document; check processing through /receipts/{id}/workflow.\n","operationId":"ReceiptsGet","parameters":[{"description":"Receipt ID from creation, upload or listing.","in":"path","name":"id","required":true,"schema":{"type":"string","x-go-type-skip-optional-pointer":false}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/receipts_ReceiptResponse"}]}}},"description":"Receipt metadata and full document.","headers":{"Cache-Control":{"description":"no-store; receipt responses are not cached.","schema":{"type":"string"}},"ETag":{"description":"Quoted document version; send it as If-Match when editing.","schema":{"type":"string"}},"Location":{"description":"Current receipt URL; use it for later edits if duplicates were merged.","schema":{"type":"string"}}}},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Read a receipt","tags":["receipts"],"x-required-scopes":["receipts:read"]}},"/receipts/{id}/document":{"patch":{"description":"Apply JSON Patch to receipt.document from GET, using its ETag as If-Match.\nPaths are document-relative, such as /merchant/name; success returns the document.\n","operationId":"ReceiptsDocumentPatch","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"header","name":"If-Match","required":true,"schema":{"description":"Quoted positive receipt version, for example \"3\".","type":"string"}}],"requestBody":{"content":{"application/json-patch+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/receipts_ReceiptDocumentPatch"}]}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_receipts_DetailDocument"}]}}},"description":"Updated document.","headers":{"ETag":{"description":"Quoted current receipt version.","schema":{"type":"string"}},"Location":{"description":"Current receipt URL.","schema":{"type":"string"}}}},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Edit a receipt document","tags":["receipts"],"x-required-scopes":["receipts:write"]}},"/receipts/{id}/image":{"get":{"description":"Download the receipt's source file. Check Content-Type for its format:\nthe response may be an image or PDF, rather than JSON.\n\n**Permission:** `receipts:read`\n","operationId":"ReceiptsImageGet","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/octet-stream":{"schema":{"format":"binary","type":"string"}},"application/pdf":{"schema":{"format":"binary","type":"string"}},"image/*":{"schema":{"format":"binary","type":"string"}}},"description":"Receipt source file."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Download receipt source","tags":["receipts"],"x-required-scopes":["receipts:read"]}},"/receipts/{id}/workflow":{"get":{"description":"Check recognition, receipt status, ledger synchronization and errors.\nProcessing status can change without changing the document version.\n","operationId":"ReceiptsWorkflowGet","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/receipts_ReceiptWorkflow"}]}}},"description":"Current processing status and errors.","headers":{"Cache-Control":{"description":"no-store; processing status is not cached.","schema":{"type":"string"}}}},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Read receipt processing status","tags":["receipts"],"x-required-scopes":["receipts:read"]}},"/taxonomy":{"get":{"description":"Read selectable categories, including your Household's custom categories.\nUse category keys to classify receipt lines.\n\n**Permission:** `references:read`\n","operationId":"TaxonomyGet","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomyTree"}]}}},"description":"Selectable category tree."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Read the category tree","tags":["taxonomy"],"x-required-scopes":["references:read"]}},"/taxonomy/categories":{"post":{"description":"Add a custom category with a parent and translated names and descriptions.\nAn emoji and recognition guidance are optional. FacturAI generates its key.\n\n**Permission:** `taxonomy:write`\n","operationId":"TaxonomyCategoriesCreate","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_CategoryCreate"}]}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_CategoryCreated"}]}}},"description":"Created category and updated revision."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Create a category","tags":["taxonomy"],"x-required-scopes":["taxonomy:write"]}},"/taxonomy/categories/{key}/removal":{"post":{"description":"Hide or delete a custom category using the latest revision. Hiding preserves\nexisting assignments; deletion may require receipt corrections.\nPreview the impact first. Receipt data is not rewritten.\n\n**Permission:** `taxonomy:write`\n","operationId":"TaxonomyCategoriesRemove","parameters":[{"in":"path","name":"key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomyRemoval"}]}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomySettings"}]}}},"description":"Category settings after removal."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Hide or delete a category","tags":["taxonomy"],"x-required-scopes":["taxonomy:write"]}},"/taxonomy/categories/{key}/removal-impact":{"get":{"description":"Check how many receipts would be affected by hiding or deleting a category.\nChoose whether to keep its subcategories. This preview makes no changes.\n\n**Permission:** `taxonomy:read`\n","operationId":"TaxonomyCategoriesRemovalImpactGet","parameters":[{"in":"path","name":"key","required":true,"schema":{"type":"string"}},{"description":"Latest category revision; a stale value returns 409.","in":"query","name":"revision","required":true,"schema":{"format":"int64","minimum":0,"type":"integer"}},{"description":"Keep and move children to the parent (true), or include the whole branch (false).","in":"query","name":"keep_subcategories","required":true,"schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomyRemovalImpact"}]}}},"description":"Number of affected receipts."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Preview category removal","tags":["taxonomy"],"x-required-scopes":["taxonomy:read"]}},"/taxonomy/categories/{key}/restore":{"post":{"description":"Make a hidden custom category selectable again, including any required\nparent categories. Permanently deleted categories cannot be restored.\n\n**Permission:** `taxonomy:write`\n","operationId":"TaxonomyCategoriesRestore","parameters":[{"in":"path","name":"key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomyRevision"}]}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomySettings"}]}}},"description":"Category settings after restoration."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Restore a category","tags":["taxonomy"],"x-required-scopes":["taxonomy:write"]}},"/taxonomy/problems":{"get":{"description":"Read category records that cannot be used and why. Use their record IDs\nto preview cleanup; this request does not change categories.\n\n**Permission:** `taxonomy:read`\n","operationId":"TaxonomyProblemsList","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomyProblems"}]}}},"description":"Category problems and current revision."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"List category problems","tags":["taxonomy"],"x-required-scopes":["taxonomy:read"]}},"/taxonomy/problems/{record_id}/removal":{"post":{"description":"Remove a problem record using its record_id and the latest revision.\nPreview its impact first. This does not select a replacement category.\n\n**Permission:** `taxonomy:write`\n","operationId":"TaxonomyProblemsDelete","parameters":[{"in":"path","name":"record_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomyRevision"}]}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomySettings"}]}}},"description":"Category settings after cleanup."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Remove a category problem record","tags":["taxonomy"],"x-required-scopes":["taxonomy:write"]}},"/taxonomy/problems/{record_id}/removal-impact":{"get":{"description":"Check how many receipts would be affected by removing a problem record.\nUse its record_id from the problems list. This preview makes no changes.\n\n**Permission:** `taxonomy:read`\n","operationId":"TaxonomyProblemsRemovalImpactGet","parameters":[{"in":"path","name":"record_id","required":true,"schema":{"type":"string"}},{"description":"Latest revision from the problems list; a stale value returns 409.","in":"query","name":"revision","required":true,"schema":{"format":"int64","minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomyRemovalImpact"}]}}},"description":"Number of affected receipts."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Preview problem cleanup","tags":["taxonomy"],"x-required-scopes":["taxonomy:read"]}},"/taxonomy/settings":{"get":{"description":"Read all custom categories, including hidden categories and problems.\nKeep the revision for your next change.\n\n**Permission:** `taxonomy:read`\n","operationId":"TaxonomySettingsGet","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomySettings"}]}}},"description":"Current category settings."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Read category settings","tags":["taxonomy"],"x-required-scopes":["taxonomy:read"]},"put":{"description":"Save the complete custom-category list using the latest settings revision.\nInclude every category you want to keep. A stale revision returns 409.\n\n**Permission:** `taxonomy:write`\n","operationId":"TaxonomySettingsSave","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomySettingsWrite"}]}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/content_contracts_facturai_shared_taxonomy_TaxonomySettings"}]}}},"description":"Updated category settings."},"default":{"$ref":"#/components/responses/content_contracts_facturai_shared_errors_RequestError"}},"summary":"Edit category settings","tags":["taxonomy"],"x-required-scopes":["taxonomy:write"]}}},"security":[{"APIKeyBearer":[]}],"servers":[{"url":"/"}],"tags":[{"description":"Create receipts from JSON or uploaded files, find purchases and edit their\ndocuments. Check recognition and ledger synchronization through /workflow.\nReading requires `receipts:read`; creation, uploads, edits and deletion\nrequire `receipts:write`.\n","name":"receipts","x-displayName":"Receipts"},{"description":"Look up categories for receipt lines and manage your Household's custom\ncategories. The selectable tree requires `references:read`; settings and\nremoval previews require `taxonomy:read`; changes require `taxonomy:write`.\n","name":"taxonomy","x-displayName":"Categories"},{"description":"Look up merchant IDs and names for receipt filters and purchase history.\nRequires `references:read`.\n","name":"merchants","x-displayName":"Merchants"},{"description":"Look up saved accounts and categories from the connected ledger, without\nrefreshing it. Ledger category IDs differ from FacturAI category keys.\nRequires `references:read`.\n","name":"ledger-connections","x-displayName":"Ledger reference data"},{"description":"Read the Household's currencies and exchange-rate information.\nRequires `references:read`; settings cannot be changed through this endpoint.\n","name":"household","x-displayName":"Household \u0026 currencies"},{"description":"Export purchase history as JSON, CSV or XLSX. Start an export, wait for\nsuccess and get a temporary download link. Starting requires `exports:write`;\nreading progress and downloading require `exports:read`.\n","name":"exports","x-displayName":"Exports"},{"description":"Check that the API is running and can reach its database.\nNo API key is required; these checks do not cover connected services.\n","name":"probes","x-displayName":"Service health"}],"x-tagGroups":[{"name":"Core API","tags":["receipts"]},{"name":"Reference data","tags":["taxonomy","merchants","ledger-connections","household"]},{"name":"Utilities","tags":["exports","probes"]}]}