{
  "openapi": "3.1.0",
  "info": {
    "title": "RARA Rare Collection API",
    "version": "1.3.0",
    "description": "Public discovery only. Prices are estimates, stock is unverified. No checkout or seller partnership implied."
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "paths": {
    "/api/catalog": {
      "get": {
        "operationId": "searchDiscoveries",
        "summary": "Find discoveries and source links",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$",
              "description": "Country of origin code, e.g. JP. Only explicit origin evidence matches; unknown origins are excluded."
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 240
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "food",
                "textile",
                "object",
                "experience"
              ]
            }
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Exact source hostname, e.g. maiwa.com"
            }
          },
          {
            "name": "tags",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Comma-separated exact tags; all must match"
            }
          },
          {
            "name": "availability",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "minPrice",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "maxPrice",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "rarity",
                "name",
                "priceAsc",
                "priceDesc"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 28
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "fields",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Comma-separated projection: id,name,origin,tagline,kind,category,tags,price,availability,url,sourceUrl,where,provenance,img,sourceCheckedAt"
            }
          },
          {
            "name": "revision",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Pin pagination to a revision; 409 means restart"
            }
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "description": "ETag from the same URL; lists and weak validators supported."
          }
        ],
        "responses": {
          "200": {
            "description": "Catalog results or individual item, with revision and explicit unknowns",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogPage"
                }
              }
            },
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Representation-specific validator"
              }
            }
          },
          "304": {
            "description": "Unchanged representation; ETag match"
          },
          "400": {
            "description": "Invalid query; response includes error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Catalog revision changed; restart pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "head": {
        "operationId": "searchDiscoveriesHeaders",
        "summary": "GET headers without a response body",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$",
              "description": "Country of origin code, e.g. JP. Only explicit origin evidence matches; unknown origins are excluded."
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 240
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "food",
                "textile",
                "object",
                "experience"
              ]
            }
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Exact source hostname, e.g. maiwa.com"
            }
          },
          {
            "name": "tags",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Comma-separated exact tags; all must match"
            }
          },
          {
            "name": "availability",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "minPrice",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "maxPrice",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "rarity",
                "name",
                "priceAsc",
                "priceDesc"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 28
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "fields",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Comma-separated projection: id,name,origin,tagline,kind,category,tags,price,availability,url,sourceUrl,where,provenance,img,sourceCheckedAt"
            }
          },
          {
            "name": "revision",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Pin pagination to a revision; 409 means restart"
            }
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "description": "ETag from the same URL; lists and weak validators supported."
          }
        ],
        "responses": {
          "200": {
            "description": "Catalog results or individual item, with revision and explicit unknowns"
          },
          "304": {
            "description": "Unchanged representation; ETag match"
          },
          "400": {
            "description": "Invalid query; response includes error"
          },
          "404": {
            "description": "Item not found"
          },
          "405": {
            "description": "Method not allowed"
          },
          "409": {
            "description": "Catalog revision changed; restart pagination"
          }
        }
      }
    },
    "/api/catalog/{id}": {
      "get": {
        "operationId": "getDiscovery",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "description": "ETag from the same URL; lists and weak validators supported."
          }
        ],
        "responses": {
          "200": {
            "description": "Catalog results or individual item, with revision and explicit unknowns",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "revision",
                    "item"
                  ],
                  "properties": {
                    "revision": {
                      "type": "string"
                    },
                    "item": {
                      "$ref": "#/components/schemas/Discovery"
                    }
                  }
                }
              }
            },
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Representation-specific validator"
              }
            }
          },
          "304": {
            "description": "Unchanged representation; ETag match"
          },
          "400": {
            "description": "Invalid query; response includes error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Item not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Catalog revision changed; restart pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "head": {
        "operationId": "getDiscoveryHeaders",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "description": "ETag from the same URL; lists and weak validators supported."
          }
        ],
        "responses": {
          "200": {
            "description": "Catalog results or individual item, with revision and explicit unknowns"
          },
          "304": {
            "description": "Unchanged representation; ETag match"
          },
          "400": {
            "description": "Invalid query; response includes error"
          },
          "404": {
            "description": "Item not found"
          },
          "405": {
            "description": "Method not allowed"
          },
          "409": {
            "description": "Catalog revision changed; restart pagination"
          }
        },
        "summary": "GET headers without a response body"
      }
    },
    "/api/edits": {
      "get": {
        "operationId": "listCuratedEdits",
        "summary": "Authored intent shortlists and comparisons; accepts no parameters",
        "responses": {
          "200": {
            "description": "Read-only discovery context",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "edits",
                    "comparisons"
                  ],
                  "properties": {
                    "edits": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CuratedEdit"
                      }
                    },
                    "comparisons": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EditorialComparison"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid or duplicate parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown item",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Use GET or HEAD",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "head": {
        "operationId": "listCuratedEditsHeaders",
        "summary": "Authored intent shortlists and comparisons; accepts no parameters",
        "responses": {
          "200": {
            "description": "Read-only discovery context"
          },
          "400": {
            "description": "Invalid or duplicate parameters"
          },
          "404": {
            "description": "Unknown item"
          },
          "405": {
            "description": "Use GET or HEAD"
          }
        }
      }
    },
    "/api/compare": {
      "get": {
        "operationId": "compareDiscoveries",
        "summary": "Compare 2–4 catalog IDs using source facts, with explicit unknowns",
        "parameters": [
          {
            "name": "ids",
            "in": "query",
            "required": true,
            "description": "Comma-separated distinct IDs. Duplicate or extra parameters are rejected.",
            "schema": {
              "type": "string"
            },
            "example": "jasmine-silver-tip,aroma-stone"
          }
        ],
        "responses": {
          "200": {
            "description": "Read-only discovery context",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "revision",
                    "items",
                    "comparisonBasis",
                    "nextStep"
                  ],
                  "properties": {
                    "revision": {
                      "type": "string"
                    },
                    "comparisonBasis": {
                      "type": "string"
                    },
                    "items": {
                      "type": "array",
                      "minItems": 2,
                      "maxItems": 4,
                      "items": {
                        "$ref": "#/components/schemas/ComparisonItem"
                      }
                    },
                    "nextStep": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid or duplicate parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown item",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Use GET or HEAD",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "head": {
        "operationId": "compareDiscoveriesHeaders",
        "summary": "Compare 2–4 catalog IDs using source facts, with explicit unknowns",
        "parameters": [
          {
            "name": "ids",
            "in": "query",
            "required": true,
            "description": "Comma-separated distinct IDs. Duplicate or extra parameters are rejected.",
            "schema": {
              "type": "string"
            },
            "example": "jasmine-silver-tip,aroma-stone"
          }
        ],
        "responses": {
          "200": {
            "description": "Read-only discovery context"
          },
          "400": {
            "description": "Invalid or duplicate parameters"
          },
          "404": {
            "description": "Unknown item"
          },
          "405": {
            "description": "Use GET or HEAD"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Discovery": {
        "type": "object",
        "required": [
          "id",
          "name",
          "url",
          "category",
          "kind",
          "price",
          "availability",
          "tags"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-z0-9-]+$"
          },
          "name": {
            "type": "string",
            "minLength": 1
          },
          "url": {
            "type": "string"
          },
          "category": {
            "enum": [
              "food",
              "textile",
              "object",
              "experience"
            ]
          },
          "kind": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "availability": {
            "type": "string",
            "description": "Recorded status, not live stock. Consult response facets for accepted values."
          },
          "price": {
            "type": "object",
            "required": [
              "amount",
              "currency",
              "unit",
              "verified"
            ],
            "properties": {
              "amount": {
                "type": [
                  "number",
                  "null"
                ],
                "minimum": 0
              },
              "currency": {
                "type": "string",
                "pattern": "^[A-Z]{3}$"
              },
              "unit": {
                "type": "string"
              },
              "verified": {
                "type": "boolean"
              }
            }
          },
          "sourceUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Original source. Follow it to verify stock, delivery and current price."
          },
          "sourceCheckedAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "Recorded research date, not a live inventory check."
          },
          "tagline": {
            "type": "string"
          },
          "where": {
            "type": "string"
          },
          "img": {
            "type": "string"
          },
          "provenance": {
            "type": [
              "object",
              "null"
            ],
            "description": "Publisher and recorded retrieval evidence; not independent verification."
          },
          "origin": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "code",
              "name",
              "flag",
              "basis",
              "evidence",
              "sourceUrl"
            ],
            "properties": {
              "code": {
                "type": "string",
                "pattern": "^[A-Z]{2}$"
              },
              "name": {
                "type": "string"
              },
              "flag": {
                "type": "string"
              },
              "basis": {
                "type": "string"
              },
              "evidence": {
                "type": "string"
              },
              "sourceUrl": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "code",
          "documentation"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "documentation": {
            "type": "string"
          }
        }
      },
      "CatalogPage": {
        "type": "object",
        "required": [
          "revision",
          "total",
          "items",
          "links"
        ],
        "properties": {
          "revision": {
            "type": "string"
          },
          "total": {
            "type": "integer"
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "links": {
            "type": "object",
            "properties": {
              "self": {
                "type": "string"
              },
              "next": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "previous": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "schema": {
                "type": "string",
                "description": "Search response schema in OpenAPI"
              },
              "snapshotSchema": {
                "type": "string",
                "description": "Separate downloadable catalog snapshot schema"
              }
            }
          },
          "version": {
            "type": "string"
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "nextOffset": {
            "type": [
              "integer",
              "null"
            ]
          },
          "filters": {
            "type": "object"
          },
          "currency": {
            "type": "string"
          },
          "pricePolicy": {
            "type": "string"
          },
          "facets": {
            "type": "object"
          },
          "matchedFacets": {
            "type": "object"
          },
          "queryContext": {
            "type": "object",
            "description": "Interpreted product terms, explicit requirements still needing seller confirmation, applied exclusions and budget, and separately labeled recovery links. Candidate results do not certify delivery, allergens, weight or custom fit.",
            "properties": {
              "tokens": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "sourceRequired": {
                "type": "boolean"
              },
              "maxPrice": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "requirements": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "exclusions": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "resultMode": {
                "enum": [
                  "candidates_need_confirmation",
                  "discovery_candidates"
                ]
              },
              "summary": {
                "type": "string"
              },
              "recovery": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              }
            }
          }
        }
      },
      "CuratedEdit": {
        "type": "object",
        "required": [
          "slug",
          "title",
          "question",
          "intro",
          "ids",
          "reasons",
          "guide",
          "check",
          "query",
          "image",
          "url"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "question": {
            "type": "string"
          },
          "intro": {
            "type": "string"
          },
          "ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "guide": {
            "type": "string",
            "description": "Field-note slug under /journal/"
          },
          "check": {
            "type": "string"
          },
          "query": {
            "type": "string",
            "description": "Query string for collection browsing"
          },
          "image": {
            "type": "string",
            "description": "Catalog ID of the lead image"
          },
          "maxPrice": {
            "type": "number"
          },
          "url": {
            "type": "string"
          }
        }
      },
      "EditorialComparison": {
        "type": "object",
        "required": [
          "slug",
          "title",
          "ids",
          "intro",
          "questions",
          "decision",
          "url"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "intro": {
            "type": "string"
          },
          "questions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "decision": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        }
      },
      "ComparisonItem": {
        "type": "object",
        "required": [
          "id",
          "name",
          "kind",
          "price",
          "availability",
          "url",
          "sourceUrl",
          "sourceCheckedAt",
          "caveat",
          "evidenceStatus",
          "unknowns"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "price": {
            "type": "object",
            "required": [
              "amount",
              "currency",
              "unit",
              "verified"
            ],
            "properties": {
              "amount": {
                "type": [
                  "number",
                  "null"
                ],
                "minimum": 0
              },
              "currency": {
                "type": "string",
                "pattern": "^[A-Z]{3}$"
              },
              "unit": {
                "type": "string"
              },
              "verified": {
                "type": "boolean"
              }
            }
          },
          "availability": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "sourceUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "sourceCheckedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "caveat": {
            "type": [
              "string",
              "null"
            ]
          },
          "evidenceStatus": {
            "type": [
              "string",
              "null"
            ]
          },
          "unknowns": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}