{
  "openapi": "3.1.0",
  "info": {
    "title": "PalletMath agent API",
    "version": "1.0.0",
    "description": "Read-only. What liquidation resellers have live on eBay, Mercari, Poshmark and Facebook, with provenance. Every item links out to the marketplace listing where it is sold; nothing is sold here."
  },
  "servers": [
    {
      "url": "https://palletmath.com"
    }
  ],
  "paths": {
    "/api/agent/search": {
      "get": {
        "operationId": "searchListings",
        "summary": "Search every live, linked item across all resellers",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Words to match against title, description and category (up to 80 characters)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "on",
            "in": "query",
            "description": "Keep to one marketplace",
            "schema": {
              "type": "string",
              "enum": [
                "ebay",
                "mercari",
                "poshmark",
                "facebook"
              ]
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "deal = biggest discount off retail first (default), new = newest, price = lowest price",
            "schema": {
              "type": "string",
              "enum": [
                "deal",
                "new",
                "price"
              ]
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "1-based, 60 items a page",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResult"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/items/{id}": {
      "get": {
        "operationId": "getListing",
        "summary": "One live item",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The item",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Item"
                }
              }
            }
          },
          "404": {
            "description": "Not live, or no such item"
          }
        }
      }
    },
    "/api/agent/sellers": {
      "get": {
        "operationId": "listSellers",
        "summary": "Every reseller with something live",
        "responses": {
          "200": {
            "description": "Sellers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SellerList"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/sellers/{handle}": {
      "get": {
        "operationId": "getSeller",
        "summary": "One reseller and everything they have live",
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The seller",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Seller"
                }
              }
            }
          },
          "404": {
            "description": "No such seller"
          }
        }
      }
    },
    "/api/agent/feed": {
      "get": {
        "operationId": "productFeed",
        "summary": "Every live, linked item as a flat product feed, paginated",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "1-based, 200 items a page",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Feed page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Feed"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Item": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The PalletMath item page — cite this"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "condition": {
            "type": [
              "string",
              "null"
            ]
          },
          "quantityAvailable": {
            "type": "integer"
          },
          "price": {
            "type": [
              "number",
              "null"
            ],
            "description": "Seller asking price, USD. null = make an offer"
          },
          "priceCurrency": {
            "type": "string",
            "const": "USD"
          },
          "priceNote": {
            "type": [
              "string",
              "null"
            ]
          },
          "retailPrice": {
            "type": [
              "number",
              "null"
            ]
          },
          "percentOffRetail": {
            "type": [
              "integer",
              "null"
            ]
          },
          "buyUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "The marketplace listing — send the buyer here"
          },
          "marketplace": {
            "type": [
              "string",
              "null"
            ]
          },
          "marketplaceKey": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "ebay",
              "mercari",
              "poshmark",
              "facebook",
              "other",
              null
            ]
          },
          "imageUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "provenance": {
            "type": "object",
            "properties": {
              "source": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The pallet it came off, e.g. \"B-Stock · Costco\""
              },
              "checkedInAt": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "code": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "checkUrl": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uri"
              }
            }
          },
          "seller": {
            "type": "object",
            "properties": {
              "handle": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "verified": {
                "type": [
                  "boolean",
                  "null"
                ]
              }
            }
          },
          "listedAt": {
            "type": "string"
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "properties": {
          "q": {
            "type": "string"
          },
          "sort": {
            "type": "string"
          },
          "on": {
            "type": [
              "string",
              "null"
            ]
          },
          "page": {
            "type": "integer"
          },
          "pages": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "sellers": {
            "type": "integer"
          },
          "marketplaces": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "count": {
                  "type": "integer"
                }
              }
            }
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Item"
            }
          }
        }
      },
      "Seller": {
        "type": "object",
        "properties": {
          "handle": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "profileUrl": {
            "type": "string",
            "format": "uri"
          },
          "llmsTxtUrl": {
            "type": "string",
            "format": "uri"
          },
          "verified": {
            "type": "boolean"
          },
          "rank": {
            "type": "string"
          },
          "record": {
            "type": "object",
            "properties": {
              "verifiedSales": {
                "type": "integer"
              },
              "byEbay": {
                "type": "integer"
              },
              "liveOn": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "storefronts": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "format": "uri"
            }
          },
          "liveItems": {
            "type": "integer"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Item"
            }
          }
        }
      },
      "SellerList": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer"
          },
          "sellers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "handle": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "apiUrl": {
                  "type": "string",
                  "format": "uri"
                },
                "verified": {
                  "type": "boolean"
                },
                "liveItems": {
                  "type": "integer"
                }
              }
            }
          }
        }
      },
      "Feed": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer"
          },
          "pages": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "generatedAt": {
            "type": "string"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FeedItem"
            }
          }
        }
      },
      "FeedItem": {
        "type": "object",
        "description": "A flat product-feed row (the shape ACP/Merchant-style feeds expect)",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "link": {
            "type": "string",
            "format": "uri"
          },
          "mobile_link": {
            "type": "string",
            "format": "uri"
          },
          "image_link": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "price": {
            "type": [
              "string",
              "null"
            ],
            "description": "\"25.00 USD\""
          },
          "availability": {
            "type": "string",
            "enum": [
              "in_stock",
              "out_of_stock"
            ]
          },
          "condition": {
            "type": "string",
            "enum": [
              "new",
              "used",
              "refurbished"
            ]
          },
          "quantity": {
            "type": "integer"
          },
          "product_category": {
            "type": [
              "string",
              "null"
            ]
          },
          "seller_name": {
            "type": "string"
          },
          "seller_url": {
            "type": "string",
            "format": "uri"
          },
          "marketplace": {
            "type": [
              "string",
              "null"
            ]
          },
          "marketplace_link": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          }
        }
      }
    }
  }
}