{
  "components": {
    "schemas": {
      "EnrichRequest": {
        "properties": {
          "amount": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Amount"
          },
          "country": {
            "anyOf": [
              {
                "maxLength": 2,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Country"
          },
          "currency": {
            "anyOf": [
              {
                "maxLength": 3,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Currency"
          },
          "date": {
            "anyOf": [
              {
                "maxLength": 10,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Date"
          },
          "mcc": {
            "anyOf": [
              {
                "maxLength": 4,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Mcc"
          },
          "merchant_name": {
            "anyOf": [
              {
                "maxLength": 128,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Merchant Name"
          },
          "raw_description": {
            "maxLength": 512,
            "minLength": 1,
            "title": "Raw Description",
            "type": "string"
          }
        },
        "required": [
          "raw_description"
        ],
        "title": "EnrichRequest",
        "type": "object"
      },
      "EnrichResponse": {
        "properties": {
          "category": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Category"
          },
          "confidence": {
            "maximum": 1,
            "minimum": 0,
            "title": "Confidence",
            "type": "number"
          },
          "display_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Display Name"
          },
          "location_hint": {
            "anyOf": [
              {
                "additionalProperties": {
                  "type": "string"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Location Hint"
          },
          "logos": {
            "$ref": "#/components/schemas/LogoSetResponse"
          },
          "normalized_merchant": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Normalized Merchant"
          },
          "processor_hint": {
            "title": "Processor Hint",
            "type": "string"
          },
          "recurring_hint": {
            "title": "Recurring Hint",
            "type": "boolean"
          },
          "signals": {
            "items": {
              "type": "string"
            },
            "title": "Signals",
            "type": "array"
          },
          "subcategory": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Subcategory"
          },
          "warnings": {
            "items": {
              "type": "string"
            },
            "title": "Warnings",
            "type": "array"
          },
          "website": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Website"
          }
        },
        "required": [
          "normalized_merchant",
          "display_name",
          "category",
          "subcategory",
          "website",
          "logos",
          "confidence",
          "recurring_hint",
          "processor_hint",
          "location_hint",
          "signals",
          "warnings"
        ],
        "title": "Enrichment result",
        "type": "object"
      },
      "ErrorDetail": {
        "properties": {
          "code": {
            "title": "Code",
            "type": "string"
          },
          "message": {
            "title": "Message",
            "type": "string"
          },
          "reason": {
            "title": "Reason",
            "type": "string"
          }
        },
        "required": [
          "code",
          "reason",
          "message"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorResponse": {
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorDetail"
          }
        },
        "required": [
          "error"
        ],
        "title": "ErrorResponse",
        "type": "object"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "title": "HTTPValidationError",
        "type": "object"
      },
      "LogoSetResponse": {
        "properties": {
          "preferred": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/LogoVariantResponse"
              },
              {
                "type": "null"
              }
            ]
          },
          "variants": {
            "items": {
              "$ref": "#/components/schemas/LogoVariantResponse"
            },
            "title": "Variants",
            "type": "array"
          },
          "warnings": {
            "items": {
              "type": "string"
            },
            "title": "Warnings",
            "type": "array"
          }
        },
        "required": [
          "preferred",
          "variants",
          "warnings"
        ],
        "title": "LogoSetResponse",
        "type": "object"
      },
      "LogoVariantResponse": {
        "properties": {
          "background": {
            "title": "Background",
            "type": "string"
          },
          "confidence": {
            "maximum": 1,
            "minimum": 0,
            "title": "Confidence",
            "type": "number"
          },
          "format": {
            "enum": [
              "png",
              "svg",
              "webp",
              "ico"
            ],
            "title": "Format",
            "type": "string"
          },
          "height": {
            "title": "Height",
            "type": "integer"
          },
          "purpose": {
            "title": "Purpose",
            "type": "string"
          },
          "shape": {
            "title": "Shape",
            "type": "string"
          },
          "source": {
            "title": "Source",
            "type": "string"
          },
          "theme": {
            "title": "Theme",
            "type": "string"
          },
          "url": {
            "title": "Url",
            "type": "string"
          },
          "width": {
            "title": "Width",
            "type": "integer"
          }
        },
        "required": [
          "url",
          "format",
          "width",
          "height",
          "background",
          "theme",
          "shape",
          "purpose",
          "source",
          "confidence"
        ],
        "title": "LogoVariantResponse",
        "type": "object"
      },
      "ValidationError": {
        "properties": {
          "ctx": {
            "title": "Context",
            "type": "object"
          },
          "input": {
            "title": "Input"
          },
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "title": "Location",
            "type": "array"
          },
          "msg": {
            "title": "Message",
            "type": "string"
          },
          "type": {
            "title": "Error Type",
            "type": "string"
          }
        },
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError",
        "type": "object"
      }
    }
  },
  "info": {
    "description": "Deterministic-first merchant and transaction enrichment for messy transaction feeds.",
    "title": "TxnKit Transaction Enrichment API",
    "version": "0.2.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/healthz": {
      "get": {
        "operationId": "healthz_healthz_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "title": "Response Healthz Healthz Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Healthz"
      }
    },
    "/v1/enrich": {
      "post": {
        "description": "Deterministic, privacy-bounded enrichment for one safe transaction descriptor. Do not send card numbers, account numbers, full statements, bank credentials, customer PII, or contact details.",
        "operationId": "enrichTransaction",
        "requestBody": {
          "content": {
            "application/json": {
              "examples": {
                "known_subscription": {
                  "description": "Reviewed seed-data match with high confidence and approved logo variants when present.",
                  "summary": "Known merchant hit",
                  "value": {
                    "amount": 12.99,
                    "country": "US",
                    "currency": "USD",
                    "date": "2026-05-22",
                    "raw_description": "PAYPAL *SPOTIFY"
                  }
                },
                "privacy_rejection": {
                  "description": "Example that demonstrates bounded rejection without echoing sensitive input.",
                  "summary": "Privacy rejection",
                  "value": {
                    "raw_description": "Payment from jane@example.com"
                  }
                },
                "square_local": {
                  "description": "Safe low-confidence local merchant example with processor and city hints.",
                  "summary": "Square local merchant fallback",
                  "value": {
                    "amount": 6.75,
                    "country": "CA",
                    "currency": "CAD",
                    "date": "2026-05-22",
                    "mcc": "5814",
                    "raw_description": "SQ *JOES COFFEE 0421 TORONTO"
                  }
                }
              },
              "schema": {
                "$ref": "#/components/schemas/EnrichRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnrichResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Request rejected because input is sensitive, statement-like, or invalid"
          }
        },
        "summary": "Enrich one transaction descriptor",
        "x-openai-isConsequential": false
      }
    }
  }
}