{
  "openapi": "3.1.0",
  "info": {
    "title": "PrivGift public catalogue API",
    "version": "1.0.0",
    "summary": "Read-only catalogue of gift cards purchasable with cryptocurrency.",
    "description": "Open, keyless, rate-limited at 120 requests per minute per IP. Returns the same data the website renders: brands, markets, accepted crypto assets and every purchasable gift card with its denominations and prices. No authentication, CORS open to all origins.",
    "contact": {
      "email": "support@privgift.com",
      "url": "https://privgift.com"
    },
    "license": {
      "name": "Data provided for reference; attribution appreciated."
    }
  },
  "servers": [
    {
      "url": "https://privgift.com/api/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "catalogue",
      "description": "Products, brands and markets"
    },
    {
      "name": "payments",
      "description": "Accepted cryptocurrencies"
    }
  ],
  "paths": {
    "/products": {
      "get": {
        "tags": [
          "catalogue"
        ],
        "summary": "List gift cards",
        "description": "Every purchasable gift card. Combine filters freely; unknown parameters are ignored.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Free-text search across brand, country and category."
          },
          {
            "name": "brand",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Brand slug, e.g. `amazon`."
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO 3166-1 alpha-2 code or `GLOBAL`."
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "One of shopping, gaming, entertainment, food-delivery, travel, prepaid-cards, mobile-topup, software."
          },
          {
            "name": "crypto",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Asset symbol, e.g. `XMR`. Returns cards payable with it."
          },
          {
            "name": "minPrice",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Minimum price in the card's own currency."
          },
          {
            "name": "maxPrice",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Maximum price in the card's own currency."
          },
          {
            "name": "inStockOnly",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "`true` to hide out-of-stock cards."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "popular (default), price-asc, price-desc, name-asc or discount."
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "1-based page number."
          },
          {
            "name": "perPage",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Page size, capped at 96."
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of products.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductList"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/products/{slug}": {
      "get": {
        "tags": [
          "catalogue"
        ],
        "summary": "Get one gift card",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Product slug, e.g. `amazon-gift-card-us`."
          }
        ],
        "responses": {
          "200": {
            "description": "The product.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductItem"
                }
              }
            }
          },
          "404": {
            "description": "Unknown slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/brands": {
      "get": {
        "tags": [
          "catalogue"
        ],
        "summary": "List brands",
        "responses": {
          "200": {
            "description": "Every brand in the catalogue.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/countries": {
      "get": {
        "tags": [
          "catalogue"
        ],
        "summary": "List markets",
        "description": "Markets cards are issued for, with their currency and product count.",
        "responses": {
          "200": {
            "description": "Every market.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/cryptos": {
      "get": {
        "tags": [
          "payments"
        ],
        "summary": "List cryptocurrencies",
        "description": "Accepted assets with network, typical confirmation time and whether they are currently enabled. Disabled assets are included with `enabled: false`.",
        "responses": {
          "200": {
            "description": "Every asset.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "required": [
          "id",
          "slug",
          "name",
          "brand",
          "countryCode",
          "currency",
          "denominations"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "slug": {
            "type": "string",
            "examples": [
              "amazon-gift-card-us"
            ]
          },
          "name": {
            "type": "string"
          },
          "brand": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "countryCode": {
            "type": "string",
            "examples": [
              "US",
              "GLOBAL"
            ]
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "currency": {
            "type": "string",
            "description": "ISO-4217.",
            "examples": [
              "USD"
            ]
          },
          "denominations": {
            "type": "array",
            "description": "Fixed face values, with per-value stock.",
            "items": {
              "type": "object",
              "properties": {
                "sku": {
                  "type": "string"
                },
                "value": {
                  "type": "number"
                },
                "inStock": {
                  "type": "boolean"
                }
              }
            }
          },
          "customAmount": {
            "type": [
              "object",
              "null"
            ],
            "description": "Free-amount window, when the product supports one.",
            "properties": {
              "min": {
                "type": "number"
              },
              "max": {
                "type": "number"
              },
              "step": {
                "type": "number"
              }
            }
          },
          "discountPercent": {
            "type": "number",
            "description": "Positive means the buyer pays less than face value."
          },
          "feePercent": {
            "type": "number",
            "description": "Service fee, included in the price shown."
          },
          "inStock": {
            "type": "boolean"
          },
          "delivery": {
            "type": "string",
            "enum": [
              "instant",
              "under-15-min",
              "under-1-hour"
            ]
          },
          "cryptos": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "rating": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "value": {
                "type": "number"
              },
              "count": {
                "type": "integer"
              }
            }
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ProductList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Product"
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "page": {
                "type": "integer"
              },
              "perPage": {
                "type": "integer"
              },
              "totalPages": {
                "type": "integer"
              },
              "version": {
                "type": "string"
              }
            }
          }
        }
      },
      "ProductItem": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Product"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}