{
  "openapi": "3.1.0",
  "info": {
    "title": "ArzAPI",
    "version": "1.0.0",
    "description": "Gold, currency and crypto prices for the Iranian market.\n\nResponses are cached for 60 seconds at the edge. Authenticate with an API key created in the admin panel (`/admin/`).\n\n`period=oneDay` is synthesised from the 24 intraday points returned by `/v1/items`, because the upstream currently rejects it.",
    "contact": {
      "name": "API operator"
    }
  },
  "servers": [
    {
      "url": "/",
      "description": "This deployment"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Prices",
      "description": "Item catalog and historical prices (API key required)"
    },
    {
      "name": "Public",
      "description": "Key-less endpoints used by the landing page"
    }
  ],
  "paths": {
    "/v1/plans": {
      "get": {
        "tags": ["Public"],
        "summary": "Plans available for purchase",
        "description": "Active plans with a price above zero. Used by the pricing page.",
        "operationId": "listPublicPlans",
        "security": [],
        "responses": {
          "200": {
            "description": "Sellable plans",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "plans": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/PublicPlan" }
                    }
                  }
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/highlights": {
      "get": {
        "tags": ["Public"],
        "summary": "Curated market snapshot (no API key)",
        "description": "Returns 3 currencies, 3 crypto assets and 3 gold items with the latest price and 24-hour change. Used by the landing page and cached for 60 seconds.",
        "operationId": "getHighlights",
        "security": [],
        "responses": {
          "200": {
            "description": "Grouped market snapshot",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HighlightsResponse" }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "502": { "$ref": "#/components/responses/UpstreamError" }
        }
      }
    },
    "/v1/items": {
      "get": {
        "tags": ["Prices"],
        "summary": "All items with the latest ~24 hours of prices",
        "description": "Returns every tracked item with its most recent intraday samples, newest first.",
        "operationId": "listItems",
        "responses": {
          "200": {
            "description": "One entry per item",
            "headers": {
              "X-Cache": {
                "description": "Whether the edge cache served this response",
                "schema": {
                  "type": "string",
                  "enum": ["HIT", "MISS", "BYPASS"]
                }
              },
              "X-RateLimit-Limit": {
                "description": "Requests allowed per minute for this key's plan",
                "schema": { "type": "integer" }
              },
              "X-Quota-Remaining": {
                "description": "Requests left in today's quota (omitted when unlimited)",
                "schema": { "type": "integer" }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/PriceItem" }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "502": { "$ref": "#/components/responses/UpstreamError" }
        }
      }
    },
    "/v1/history": {
      "get": {
        "tags": ["Prices"],
        "summary": "Price history for one item",
        "description": "Returns one item with a downsampled series for the requested period.",
        "operationId": "getHistory",
        "parameters": [
          {
            "name": "item",
            "in": "query",
            "required": true,
            "description": "Item abbreviation from `/v1/items`",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9]{1,16}$"
            },
            "example": "usd"
          },
          {
            "name": "period",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "oneDay",
                "oneWeek",
                "oneMonth",
                "oneYear",
                "threeYears",
                "fiveYears",
                "all"
              ],
              "default": "all"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Item with price history",
            "headers": {
              "X-Cache": {
                "description": "Whether the edge cache served this response",
                "schema": {
                  "type": "string",
                  "enum": ["HIT", "MISS", "BYPASS"]
                }
              },
              "X-OneDay-Source": {
                "description": "Present for period=oneDay; indicates the series was built from intraday data",
                "schema": { "type": "string" }
              },
              "X-RateLimit-Limit": {
                "schema": { "type": "integer" }
              },
              "X-Quota-Remaining": {
                "schema": { "type": "integer" }
              }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PriceItem" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "502": { "$ref": "#/components/responses/UpstreamError" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Key created in `/admin/`. `Authorization: Bearer <key>` is also accepted."
      }
    },
    "schemas": {
      "PublicPlan": {
        "type": "object",
        "required": ["id", "name", "rpm", "daily_quota", "price_toman", "duration_days"],
        "properties": {
          "id": { "type": "string", "example": "pro" },
          "name": { "type": "string", "example": "Pro" },
          "rpm": { "type": "integer", "example": 600 },
          "daily_quota": { "type": "integer", "example": 50000 },
          "price_toman": { "type": "integer", "example": 50000 },
          "duration_days": { "type": "integer", "example": 30 }
        }
      },
      "HighlightItem": {
        "type": "object",
        "required": ["ab", "fa", "en", "ty", "av", "sp", "ts", "change_pct", "spark"],
        "properties": {
          "ab": { "type": "string", "example": "usd" },
          "fa": { "type": "string", "example": "دلار آمریکا" },
          "en": { "type": "string", "example": "US Dollar" },
          "av": { "type": "string", "example": "🇺🇸" },
          "ty": { "type": "string", "enum": ["cu", "co", "go", "cc", "rm", "oz"] },
          "sp": {
            "description": "Latest sale price",
            "oneOf": [{ "type": "number" }, { "type": "string" }]
          },
          "bp": {
            "description": "Latest buy price",
            "oneOf": [{ "type": "number" }, { "type": "string" }, { "type": "null" }]
          },
          "ts": { "type": "string", "format": "date-time" },
          "change_pct": {
            "type": "number",
            "description": "Percent change over the available 24h window",
            "example": 0.31
          },
          "spark": {
            "type": "array",
            "description": "Chronological (oldest to newest) sale prices, up to 24 points, for charting",
            "items": { "type": "number" },
            "example": [266900, 267100, 267500]
          }
        }
      },
      "HighlightGroup": {
        "type": "object",
        "required": ["key", "label", "items"],
        "properties": {
          "key": { "type": "string", "example": "currency" },
          "label": { "type": "string", "example": "Currencies" },
          "items": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/HighlightItem" }
          }
        }
      },
      "HighlightsResponse": {
        "type": "object",
        "required": ["updated", "groups"],
        "properties": {
          "updated": { "type": "string", "format": "date-time" },
          "source": { "type": "string", "example": "public" },
          "groups": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/HighlightGroup" }
          }
        }
      },
      "PricePoint": {
        "type": "object",
        "required": ["ts", "sp"],
        "properties": {
          "ts": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 UTC timestamp",
            "example": "2026-11-06T11:06:56Z"
          },
          "sp": {
            "description": "Sale (ask) price. May be a JSON number or a numeric string.",
            "oneOf": [{ "type": "number" }, { "type": "string" }]
          },
          "bp": {
            "description": "Buy (bid) price. Optional; missing values are treated as 0.",
            "oneOf": [
              { "type": "number" },
              { "type": "string" },
              { "type": "null" }
            ]
          }
        }
      },
      "PriceItem": {
        "type": "object",
        "required": ["ab", "fa", "en", "ty", "av", "ps"],
        "properties": {
          "ab": {
            "type": "string",
            "description": "Abbreviation / API id",
            "example": "usd"
          },
          "fa": {
            "type": "string",
            "description": "Persian display name",
            "example": "دلار آمریکا"
          },
          "en": {
            "type": "string",
            "description": "English display name",
            "example": "US Dollar"
          },
          "ty": {
            "type": "string",
            "description": "Item type code",
            "enum": ["cu", "co", "go", "cc", "rm", "oz"]
          },
          "av": {
            "type": "string",
            "description": "Avatar shown in the app; live data uses emoji flags",
            "example": "🇺🇸"
          },
          "ps": {
            "type": "array",
            "description": "Price points, newest first",
            "items": { "$ref": "#/components/schemas/PricePoint" }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "string",
                "example": "invalid_period"
              },
              "message": {
                "type": "string",
                "example": "`period` must be one of: oneDay, oneWeek, ..."
              }
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid item or period",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing, unknown or revoked API key",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "NotFound": {
        "description": "Unknown item",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "RateLimited": {
        "description": "Per-minute rate limit or daily quota exceeded",
        "headers": {
          "Retry-After": {
            "description": "Seconds until the client may retry",
            "schema": { "type": "integer" }
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "UpstreamError": {
        "description": "The upstream price service failed or rate limited the request",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    }
  }
}