{
  "openapi": "3.1.0",
  "info": {
    "title": "Pietra Sourcing Assistant API",
    "version": "1.0.0",
    "description": "Read-only access to the Pietra Sourcing Marketplace: suppliers, products, sample prices, MOQs and reviews. Public data, no API key. Ordering samples, requesting quotes and messaging suppliers happen on pietrastudio.com via the returned url."
  },
  "servers": [
    {
      "url": "https://pietra-sourcing.pages.dev"
    }
  ],
  "paths": {
    "/api/suppliers": {
      "get": {
        "operationId": "searchSuppliers",
        "summary": "Search suppliers/factories",
        "description": "Find suppliers on the Pietra Sourcing Marketplace by product or capability keyword plus optional filters. Start every sourcing request here. Use limit = suppliers the customer wants (max 20). minRating and maxProductionDays filter the returned page only, so a page can hold fewer rows than limit; then read the next page (at most 3 pages per request). Never list a supplier that is not in the response.",
        "parameters": [
          {
            "name": "keyword",
            "in": "query",
            "required": false,
            "description": "Product, material or capability, e.g. candle, cut and sew hoodies, private label skincare.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "countryCode",
            "in": "query",
            "required": false,
            "description": "2-letter country code, e.g. US, CN, IT, PT, IN.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "region",
            "in": "query",
            "required": false,
            "description": "NA North America, SA Latin America, EU Europe, AS Asia, AF Africa, OA Oceania.",
            "schema": {
              "type": "string",
              "enum": [
                "NA",
                "SA",
                "EU",
                "AS",
                "AF",
                "OA"
              ]
            }
          },
          {
            "name": "attributes",
            "in": "query",
            "required": false,
            "description": "Comma-separated marketplace tags (supplier has at least one): Low MOQs, Female Owned, BIPOC Owned, Private Label Products, Contract Manufacturer, Certified Organic, Sustainable Materials, 10+ Years in Business, FDA Approved, Capacity for 25k+ Units, Packaging Options Available, Vegan.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "minMOQ",
            "in": "query",
            "required": false,
            "description": "Supplier minimum order quantity at least this.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "maxMOQ",
            "in": "query",
            "required": false,
            "description": "Supplier minimum order quantity at most this.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "maxSampleCost",
            "in": "query",
            "required": false,
            "description": "Lowest sample cost at or below this (USD).",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "minRating",
            "in": "query",
            "required": false,
            "description": "Minimum average rating out of 5 (suppliers without reviews are dropped).",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 5
            }
          },
          {
            "name": "maxProductionDays",
            "in": "query",
            "required": false,
            "description": "Maximum production lead time in days.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-based page. Ask for the next page only while hasMore is true.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Results per page (1-20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "page": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "totalMatches": {
                      "type": "integer"
                    },
                    "returned": {
                      "type": "integer"
                    },
                    "hasMore": {
                      "type": "boolean"
                    },
                    "note": {
                      "type": "string"
                    },
                    "suppliers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SupplierBrief"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Marketplace temporarily unavailable; wait and retry once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/suppliers/{supplier}": {
      "get": {
        "operationId": "getSupplier",
        "summary": "Supplier profile with products and review summary",
        "description": "Full profile of one supplier by supplierId or handle from searchSuppliers: categories, portfolio images, review summary, up to 3 recent reviews, total product count and its first products (productsLimit, default 5, max 10) with sample price and bulk pricing tiers. Call it for each supplier you present in detail (at most 5 per request).",
        "parameters": [
          {
            "name": "supplier",
            "in": "path",
            "required": true,
            "description": "supplierId or handle, e.g. laguna-candles.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "productsLimit",
            "in": "query",
            "required": false,
            "description": "How many of the supplier's products to include.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 10,
              "default": 5
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SupplierBrief"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "categories": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "portfolioImages": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "reviewSummary": {
                          "$ref": "#/components/schemas/ReviewSummary"
                        },
                        "recentReviews": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Review"
                          }
                        },
                        "productCount": {
                          "type": "integer",
                          "nullable": true
                        },
                        "products": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ProductBrief"
                          }
                        },
                        "note": {
                          "type": "string"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Marketplace temporarily unavailable; wait and retry once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/suppliers/{supplierId}/reviews": {
      "get": {
        "operationId": "getSupplierReviews",
        "summary": "Supplier reviews",
        "description": "Review summary (count and average out of 5) and individual reviews (rating, text, date, productId) for one supplier. Reviewer identity is never returned. Use when the customer asks about quality, reliability or past buyers' experience.",
        "parameters": [
          {
            "name": "supplierId",
            "in": "path",
            "required": true,
            "description": "supplierId from searchSuppliers or getSupplier.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-based page. Ask for the next page only while hasMore is true.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Results per page (1-10).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "default": 5
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "supplierId": {
                      "type": "integer"
                    },
                    "summary": {
                      "$ref": "#/components/schemas/ReviewSummary"
                    },
                    "page": {
                      "type": "integer"
                    },
                    "returned": {
                      "type": "integer"
                    },
                    "hasMore": {
                      "type": "boolean"
                    },
                    "reviews": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Review"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Marketplace temporarily unavailable; wait and retry once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/products": {
      "get": {
        "operationId": "searchProducts",
        "summary": "Search products",
        "description": "Search marketplace products by keyword, or list one supplier's products with supplierId (more than getSupplier shows). maxSamplePrice is checked against the shown sample price incl. Pietra's service fee; dropped rows are explained in note. minMOQ/maxMOQ use the first bulk tier quantity.",
        "parameters": [
          {
            "name": "keyword",
            "in": "query",
            "required": false,
            "description": "Product keyword.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "supplierId",
            "in": "query",
            "required": false,
            "description": "Only this supplier's products.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "countryCode",
            "in": "query",
            "required": false,
            "description": "Supplier country, 2-letter code.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "region",
            "in": "query",
            "required": false,
            "description": "Supplier region.",
            "schema": {
              "type": "string",
              "enum": [
                "NA",
                "SA",
                "EU",
                "AS",
                "AF",
                "OA"
              ]
            }
          },
          {
            "name": "minMOQ",
            "in": "query",
            "required": false,
            "description": "First bulk tier quantity at least this.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "maxMOQ",
            "in": "query",
            "required": false,
            "description": "First bulk tier quantity at most this.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "maxSamplePrice",
            "in": "query",
            "required": false,
            "description": "USD.",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-based page. Ask for the next page only while hasMore is true.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Results per page (1-20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "page": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "totalMatches": {
                      "type": "integer"
                    },
                    "returned": {
                      "type": "integer"
                    },
                    "hasMore": {
                      "type": "boolean"
                    },
                    "note": {
                      "type": "string"
                    },
                    "products": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ProductBrief"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Marketplace temporarily unavailable; wait and retry once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/products/{product}": {
      "get": {
        "operationId": "getProduct",
        "summary": "Product details",
        "description": "One product by productId or handle: full description, up to 6 images, sample price and what the sample includes, sample MOQ, bulk pricing tiers [{minQty, unitPrice}], customizations, supplier and url.",
        "parameters": [
          {
            "name": "product",
            "in": "path",
            "required": true,
            "description": "productId or handle.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ProductBrief"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "images": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "sampleIncludes": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Marketplace temporarily unavailable; wait and retry once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SupplierBrief": {
        "type": "object",
        "properties": {
          "supplierId": {
            "type": "integer"
          },
          "handle": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "countryCode": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "bio": {
            "type": "string",
            "nullable": true
          },
          "attributes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "customizations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "notableClients": {
            "type": "string",
            "nullable": true
          },
          "yearlySales": {
            "type": "string",
            "nullable": true
          },
          "sampleCostRange": {
            "type": "object",
            "nullable": true,
            "properties": {
              "min": {
                "type": "number",
                "nullable": true
              },
              "max": {
                "type": "number",
                "nullable": true
              }
            }
          },
          "minMOQ": {
            "type": "integer",
            "nullable": true
          },
          "lowestMoqOffer": {
            "type": "object",
            "nullable": true,
            "properties": {
              "productId": {
                "type": "integer"
              },
              "qty": {
                "type": "integer"
              },
              "unitPrice": {
                "type": "number",
                "nullable": true
              }
            }
          },
          "samplesEtaDays": {
            "type": "integer",
            "nullable": true
          },
          "productionEtaDays": {
            "type": "integer",
            "nullable": true
          },
          "shippingDays": {
            "type": "integer",
            "nullable": true
          },
          "rating": {
            "type": "number",
            "nullable": true,
            "description": "Average out of 5."
          },
          "reviewCount": {
            "type": "integer"
          },
          "url": {
            "type": "string",
            "description": "Supplier page on pietrastudio.com (order samples / request quotes there)."
          }
        }
      },
      "ProductBrief": {
        "type": "object",
        "properties": {
          "productId": {
            "type": "integer"
          },
          "handle": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "supplier": {
            "type": "object",
            "properties": {
              "supplierId": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "handle": {
                "type": "string"
              },
              "rating": {
                "type": "number",
                "nullable": true
              },
              "url": {
                "type": "string"
              }
            }
          },
          "category": {
            "type": "string",
            "nullable": true
          },
          "samplePrice": {
            "type": "number",
            "nullable": true,
            "description": "USD sample price shown on Pietra, service fee included. null = quote on request."
          },
          "sampleMOQ": {
            "type": "integer",
            "nullable": true
          },
          "bulkPricing": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "minQty": {
                  "type": "integer"
                },
                "unitPrice": {
                  "type": "number"
                }
              }
            }
          },
          "customizations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "image": {
            "type": "string",
            "nullable": true
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "url": {
            "type": "string"
          }
        }
      },
      "Review": {
        "type": "object",
        "properties": {
          "rating": {
            "type": "number",
            "nullable": true
          },
          "text": {
            "type": "string",
            "nullable": true
          },
          "date": {
            "type": "string"
          },
          "productId": {
            "type": "integer",
            "nullable": true
          }
        }
      },
      "ReviewSummary": {
        "type": "object",
        "nullable": true,
        "properties": {
          "count": {
            "type": "integer"
          },
          "rating": {
            "type": "number",
            "nullable": true
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
