{
  "openapi": "3.1.0",
  "info": {
    "title": "Citeda API",
    "version": "2026-10-16",
    "description": "Read-only K-beauty gap data from Seoul, plus an inquiry endpoint. Citeda connects buyers to brands; it does not sell, ship or take payment. Every order-related request is reviewed by a human (Sean Lim) and routed to the brand or its US distributor.",
    "contact": {
      "name": "Sean Lim",
      "email": "sean@go.citeda.com"
    },
    "license": {
      "name": "Free to read, attribute and link"
    }
  },
  "servers": [
    {
      "url": "https://citeda.com"
    }
  ],
  "paths": {
    "/data/products.json": {
      "get": {
        "operationId": "listProducts",
        "summary": "Products with US Amazon gap status and check dates",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductList"
                }
              }
            }
          }
        }
      }
    },
    "/data/brands.json": {
      "get": {
        "operationId": "listBrands",
        "summary": "Brands referenced in issues",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/data/offers.json": {
      "get": {
        "operationId": "listOffers",
        "summary": "Wholesale offers published by brands (empty until brands onboard)",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/data/issue-01.json": {
      "get": {
        "operationId": "getIssue01",
        "summary": "Issue 01 with export trends",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/inquiries": {
      "post": {
        "operationId": "createInquiry",
        "summary": "Ask to buy or stock products. A human reviews it and replies to the buyer's email within 2 business days.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InquiryRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Received",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InquiryReceipt"
                }
              }
            }
          },
          "400": {
            "description": "Validation error"
          },
          "429": {
            "description": "Too many requests"
          },
          "503": {
            "description": "Inbox not configured"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ProductList": {
        "type": "object",
        "properties": {
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Product"
            }
          }
        }
      },
      "Product": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "prd_46cm-deodorant-body-wash",
              "prd_healing-bird-revive-no-wash-treatment",
              "prd_tamburins",
              "prd_borntostandout",
              "prd_collagen-gel-masks",
              "prd_boj-stay-fresh-tone-up-spf50"
            ]
          },
          "name": {
            "type": "string"
          },
          "brand_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "category": {
            "type": "string"
          },
          "signal": {
            "type": "string"
          },
          "tier": {
            "enum": [
              "feature",
              "watch"
            ]
          },
          "amazon_us": {
            "type": "object",
            "properties": {
              "listings": {
                "type": "integer"
              },
              "status": {
                "type": "string"
              },
              "checked": {
                "type": "string"
              }
            }
          }
        }
      },
      "InquiryRequest": {
        "type": "object",
        "required": [
          "buyer",
          "items"
        ],
        "properties": {
          "agent": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "operator": {
                "type": "string"
              }
            }
          },
          "buyer": {
            "type": "object",
            "required": [
              "business_name",
              "country",
              "contact_email"
            ],
            "properties": {
              "business_name": {
                "type": "string",
                "maxLength": 200
              },
              "country": {
                "type": "string",
                "minLength": 2,
                "maxLength": 2
              },
              "region": {
                "type": "string"
              },
              "website": {
                "type": "string",
                "format": "uri"
              },
              "contact_email": {
                "type": "string",
                "format": "email"
              },
              "reseller_license": {
                "type": "string",
                "description": "Resale or tax ID if the buyer wants wholesale pricing"
              }
            }
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "type": "object",
              "required": [
                "product_id",
                "quantity"
              ],
              "properties": {
                "product_id": {
                  "type": "string",
                  "enum": [
                    "prd_46cm-deodorant-body-wash",
                    "prd_healing-bird-revive-no-wash-treatment",
                    "prd_tamburins",
                    "prd_borntostandout",
                    "prd_collagen-gel-masks",
                    "prd_boj-stay-fresh-tone-up-spf50"
                  ]
                },
                "quantity": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 1000000
                },
                "target_price_usd": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              }
            }
          },
          "message": {
            "type": "string",
            "maxLength": 2000
          }
        }
      },
      "InquiryReceipt": {
        "type": "object",
        "properties": {
          "inquiry_id": {
            "type": "string"
          },
          "status": {
            "const": "received"
          },
          "next": {
            "type": "string"
          },
          "referral_token": {
            "type": "string",
            "description": "Quote this when the brand or distributor replies."
          }
        }
      }
    }
  }
}