openapi: 3.1.0
info:
  title: RecallMatch Catalog Monitoring API
  version: 1.0.0
  description: Tenant-isolated catalog persistence and actionable official recall monitoring.
security: [{bearerAuth: []}]
paths:
  /v1/catalogs:
    post:
      operationId: createCatalog
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CreateCatalog'}}}}
      responses:
        '201': {description: Catalog created, content: {application/json: {schema: {$ref: '#/components/schemas/Catalog'}}}}
        '400': {$ref: '#/components/responses/Error'}
        '401': {$ref: '#/components/responses/Error'}
        '429': {$ref: '#/components/responses/Error'}
    get:
      operationId: listCatalogs
      responses: {'200': {description: Tenant catalogs}}
  /v1/catalogs/{catalog_id}:
    parameters: [{name: catalog_id, in: path, required: true, schema: {type: string, format: uuid}}]
    get: {operationId: getCatalog, responses: {'200': {description: Catalog}, '404': {$ref: '#/components/responses/Error'}}}
    delete: {operationId: deleteCatalog, responses: {'204': {description: Deleted}, '404': {$ref: '#/components/responses/Error'}}}
  /v1/catalogs/{catalog_id}/products:
    post:
      operationId: uploadCatalogProducts
      parameters: [{name: catalog_id, in: path, required: true, schema: {type: string, format: uuid}}]
      requestBody:
        required: true
        content: {application/json: {schema: {type: object, required: [products], properties: {products: {type: array, minItems: 1, maxItems: 1000, items: {$ref: '#/components/schemas/Product'}}}}}}
      responses: {'200': {description: Ordered products}, '422': {$ref: '#/components/responses/Error'}}
  /v1/catalogs/{catalog_id}/matches:
    get:
      operationId: listCatalogMatches
      parameters: [{name: catalog_id, in: path, required: true, schema: {type: string, format: uuid}}]
      responses: {'200': {description: Actionable matches}, '404': {$ref: '#/components/responses/Error'}}
components:
  securitySchemes: {bearerAuth: {type: http, scheme: bearer, bearerFormat: API key}}
  schemas:
    CreateCatalog: {type: object, required: [name], additionalProperties: false, properties: {name: {type: string, minLength: 1, maxLength: 200}}}
    Product:
      type: object
      required: [title]
      additionalProperties: false
      properties: {title: {type: string}, brand: {type: string}, model: {type: string}, gtin: {type: string}, mpn: {type: string}, category: {type: string}, sku: {type: string}, manufacturer: {type: string}, description: {type: string}, country: {type: string}}
    Catalog: {type: object, required: [id, name, product_count, created_at, updated_at], properties: {id: {type: string, format: uuid}, name: {type: string}, product_count: {type: integer}, created_at: {type: string, format: date-time}, updated_at: {type: string, format: date-time}}}
  responses: {Error: {description: Structured catalog error, content: {application/json: {schema: {type: object, required: [error], properties: {error: {type: object}}}}}}}