{
  "openapi": "3.1.0",
  "info": {
    "title": "pickthepitch API",
    "version": "1.0.0",
    "description": "B2B requests and pitches on the intents.md protocol. Free, no account. Writes are confirmed by the human's own email link before anything is published or delivered.",
    "contact": {
      "email": "contact@goldcote.com"
    }
  },
  "servers": [
    {
      "url": "https://pickthepitch.com"
    }
  ],
  "paths": {
    "/api/requests": {
      "get": {
        "operationId": "listRequests",
        "summary": "Open requests (public fields)",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "requests"
          }
        }
      },
      "post": {
        "operationId": "postRequest",
        "summary": "Post a buyer request (goes live after the buyer clicks the emailed link)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Request"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "saved, pending confirmation"
          },
          "400": {
            "description": "invalid"
          },
          "429": {
            "description": "too many"
          }
        }
      }
    },
    "/api/requests/{id}": {
      "get": {
        "operationId": "getRequest",
        "summary": "One request",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "request"
          },
          "404": {
            "description": "not found"
          }
        }
      }
    },
    "/api/requests/{id}/pitches": {
      "post": {
        "operationId": "pitchRequest",
        "summary": "Pitch for a request (supplier)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Pitch"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "saved or delivered"
          }
        }
      }
    },
    "/api/watch": {
      "post": {
        "operationId": "watchRequests",
        "summary": "Supplier alerts",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Watch"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "saved, pending confirmation"
          }
        }
      }
    },
    "/api/catalog": {
      "get": {
        "operationId": "getTemplate",
        "summary": "The brief template",
        "responses": {
          "200": {
            "description": "template"
          }
        }
      }
    },
    "/api/brief": {
      "post": {
        "operationId": "previewBrief",
        "summary": "Parse one sentence into a brief (rules, nothing saved)",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "lang": {
                    "type": "string",
                    "enum": [
                      "en",
                      "de",
                      "fr",
                      "it"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "brief"
          }
        }
      }
    },
    "/api/verify": {
      "post": {
        "operationId": "verifyIntent",
        "summary": "Check an intents.md signature",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string"
                  },
                  "text": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "verification state"
          }
        }
      }
    },
    "/api/stats": {
      "get": {
        "operationId": "boardStats",
        "summary": "Real board counts",
        "responses": {
          "200": {
            "description": "counts"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Request": {
        "type": "object",
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string"
          },
          "brief": {
            "type": "string"
          },
          "lang": {
            "type": "string",
            "enum": [
              "en",
              "de",
              "fr",
              "it"
            ]
          },
          "product": {
            "type": "string"
          },
          "productKey": {
            "type": "string",
            "enum": [
              "sencha",
              "matcha",
              "darjeeling",
              "assam",
              "earl-grey",
              "oolong",
              "white-tea",
              "rooibos",
              "chamomile",
              "peppermint",
              "green-coffee",
              "espresso-beans",
              "cocoa-powder",
              "cocoa-beans",
              "turmeric",
              "ceylon-cinnamon",
              "raw-honey",
              "almonds",
              "cashews",
              "rolled-oats",
              "quinoa",
              "olive-oil",
              "chia-seeds",
              "dates"
            ]
          },
          "category": {
            "type": "string",
            "enum": [
              "tea",
              "coffee",
              "cocoa",
              "spices",
              "sweet",
              "nuts",
              "grains",
              "oils",
              "superfoods",
              "drinks",
              "other"
            ]
          },
          "quantity": {
            "type": "number"
          },
          "unit": {
            "type": "string",
            "enum": [
              "kg",
              "t",
              "g",
              "l",
              "units",
              "cases",
              "pallets"
            ]
          },
          "frequency": {
            "type": "string",
            "enum": [
              "once",
              "weekly",
              "monthly",
              "quarterly",
              "yearly"
            ]
          },
          "must": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "organic",
                "bio-suisse",
                "demeter",
                "lab-tested",
                "no-additives",
                "fairtrade",
                "rainforest",
                "single-origin",
                "food-safety",
                "vegan",
                "gluten-free",
                "kosher",
                "halal",
                "private-label",
                "plastic-free",
                "stock-ch",
                "stock-eu"
              ]
            }
          },
          "nice": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "organic",
                "bio-suisse",
                "demeter",
                "lab-tested",
                "no-additives",
                "fairtrade",
                "rainforest",
                "single-origin",
                "food-safety",
                "vegan",
                "gluten-free",
                "kosher",
                "halal",
                "private-label",
                "plastic-free",
                "stock-ch",
                "stock-eu"
              ]
            }
          },
          "origin": {
            "type": "string"
          },
          "specs": {
            "type": "string"
          },
          "packaging": {
            "type": "string",
            "enum": [
              "bulk",
              "foodservice",
              "retail",
              "private-label"
            ]
          },
          "deliverCountry": {
            "type": "string"
          },
          "deliverPlace": {
            "type": "string"
          },
          "incoterm": {
            "type": "string",
            "enum": [
              "DAP",
              "DDP",
              "EXW",
              "FOB",
              "any"
            ]
          },
          "neededBy": {
            "type": "string",
            "format": "date"
          },
          "budget": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "number"
              },
              "currency": {
                "type": "string",
                "enum": [
                  "CHF",
                  "EUR",
                  "USD",
                  "GBP"
                ]
              },
              "per": {
                "type": "string"
              }
            }
          },
          "samples": {
            "type": "boolean"
          },
          "buyerKind": {
            "type": "string",
            "enum": [
              "cafe",
              "shop",
              "maker",
              "distributor",
              "office",
              "private"
            ]
          },
          "company": {
            "type": "string"
          },
          "showCompany": {
            "type": "boolean"
          },
          "notes": {
            "type": "string"
          },
          "expiresDays": {
            "type": "integer",
            "minimum": 7,
            "maximum": 90
          },
          "agent": {
            "type": "string"
          }
        }
      },
      "Pitch": {
        "type": "object",
        "required": [
          "company",
          "email",
          "message"
        ],
        "properties": {
          "company": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "answers": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "answer": {
                  "type": "string",
                  "enum": [
                    "yes",
                    "no",
                    "partly"
                  ]
                },
                "evidence": {
                  "type": "string"
                }
              }
            }
          },
          "price": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "number"
              },
              "currency": {
                "type": "string",
                "enum": [
                  "CHF",
                  "EUR",
                  "USD",
                  "GBP"
                ]
              },
              "per": {
                "type": "string"
              }
            }
          },
          "moq": {
            "type": "string"
          },
          "leadTime": {
            "type": "string"
          },
          "incoterm": {
            "type": "string"
          },
          "samples": {
            "type": "string",
            "enum": [
              "free",
              "paid",
              "no"
            ]
          },
          "siteUrl": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "intentsUrl": {
            "type": "string"
          },
          "lang": {
            "type": "string",
            "enum": [
              "en",
              "de",
              "fr",
              "it"
            ]
          },
          "agent": {
            "type": "string"
          }
        }
      },
      "Watch": {
        "type": "object",
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "tea",
                "coffee",
                "cocoa",
                "spices",
                "sweet",
                "nuts",
                "grains",
                "oils",
                "superfoods",
                "drinks",
                "other"
              ]
            }
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "countries": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "company": {
            "type": "string"
          },
          "lang": {
            "type": "string",
            "enum": [
              "en",
              "de",
              "fr",
              "it"
            ]
          }
        }
      }
    }
  }
}