{
  "openapi": "3.1.0",
  "info": {
    "title": "App Store API",
    "version": "1.0.0",
    "description": "App Store search and reviews endpoints exposed through FetchLayer."
  },
  "servers": [
    {
      "url": "https://api.fetchlayer.dev/appstore"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key."
      }
    }
  },
  "paths": {
    "/search": {
      "post": {
        "operationId": "search",
        "tags": [
          "Search"
        ],
        "summary": "Search the App Store",
        "description": "Search by app name or keyword. Returns matching apps with ratings, developer, subtitle, category, and screenshots. Filter by platform (iPhone, iPad, Mac, Apple TV, Apple Watch, Apple Vision Pro) and country.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "App name or keyword to search."
                  },
                  "country": {
                    "type": "string",
                    "description": "Two-letter country code (e.g. us, gb, jp).",
                    "example": "us"
                  },
                  "platform": {
                    "type": "string",
                    "description": "Filter by platform: iphone, ipad, mac, appletv, watch, realityDevice."
                  },
                  "geo": {
                    "type": "string",
                    "description": "Two-letter geo code for regional results."
                  }
                },
                "additionalProperties": false,
                "required": [
                  "query"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "query": "notion",
                    "country": "us"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "App Store app ID."
                          },
                          "name": {
                            "type": "string",
                            "description": "App name."
                          },
                          "developer": {
                            "type": "string",
                            "description": "Developer name."
                          },
                          "subtitle": {
                            "type": "string",
                            "description": "Short app description/tagline."
                          },
                          "rating": {
                            "type": "number",
                            "description": "Average star rating."
                          },
                          "ratingCount": {
                            "type": "number",
                            "description": "Total number of ratings."
                          },
                          "category": {
                            "type": "string",
                            "description": "Primary App Store category."
                          },
                          "price": {
                            "type": "number",
                            "description": "Price in local currency (0 = free)."
                          },
                          "screenshots": {
                            "type": "object",
                            "additionalProperties": true,
                            "description": "Screenshot URLs."
                          },
                          "editorsChoice": {
                            "type": "boolean",
                            "description": "Whether the app has been selected as an Editor's Choice."
                          },
                          "url": {
                            "type": "string",
                            "description": "App Store listing URL."
                          }
                        },
                        "additionalProperties": false
                      }
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "results": [
                        {
                          "id": "1234567890",
                          "name": "Notion",
                          "developer": "Notion Labs",
                          "rating": 4.8,
                          "ratingCount": 45000,
                          "category": "Productivity",
                          "price": 0,
                          "url": "https://apps.apple.com/us/app/notion/id1234567890"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/reviews": {
      "post": {
        "operationId": "reviews",
        "tags": [
          "Reviews"
        ],
        "summary": "Fetch app reviews",
        "description": "Returns customer reviews for the specified App Store app. Supports filtering by platform, country, language, and pagination. Each review includes rating, title, body text, version, and date. Billing is per page actually fetched — the response includes a `pagesFetched` field and you are charged 1 credit per page retrieved (not per page requested).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "appId": {
                    "type": "string",
                    "description": "App Store app ID (numeric)."
                  },
                  "country": {
                    "type": "string",
                    "description": "Two-letter country code.",
                    "example": "us"
                  },
                  "platforms": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Filter by one or more platforms: iphone, ipad, mac, appletv, watch, realityDevice."
                  },
                  "lang": {
                    "type": "string",
                    "description": "Language code (e.g. en, ja)."
                  },
                  "geo": {
                    "type": "string",
                    "description": "Two-letter geo code for regional results."
                  },
                  "pages": {
                    "type": "number",
                    "description": "Number of pages to fetch. Billed per page actually retrieved (see `pagesFetched` in the response).",
                    "example": "1"
                  },
                  "reviewsPerPage": {
                    "type": "number",
                    "description": "Reviews per page (max 20).",
                    "example": "20"
                  },
                  "sort": {
                    "type": "string",
                    "description": "Sort order: recent (default) or helpful.",
                    "example": "recent"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "appId"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "appId": "1234567890",
                    "country": "us",
                    "pages": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Unique review identifier."
                    },
                    "rating": {
                      "type": "number",
                      "description": "Star rating (1-5)."
                    },
                    "title": {
                      "type": "string",
                      "description": "Review title."
                    },
                    "body": {
                      "type": "string",
                      "description": "Full review text."
                    },
                    "author": {
                      "type": "string",
                      "description": "Reviewer display name."
                    },
                    "version": {
                      "type": "string",
                      "description": "App version reviewed."
                    },
                    "date": {
                      "type": "string",
                      "description": "ISO 8601 review date."
                    },
                    "helpfulCount": {
                      "type": "number",
                      "description": "Number of users who found this helpful."
                    },
                    "pagesFetched": {
                      "type": "number",
                      "description": "Number of pages actually fetched. Billing is multiplied by this value (1 page = 1 credit). You are only charged for pages that were actually retrieved, not the number requested."
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "reviews": [
                        {
                          "id": "r123",
                          "rating": 5,
                          "title": "Great app",
                          "body": "Love using this every day!",
                          "author": "User123",
                          "version": "10.1.0",
                          "date": "2026-07-28T12:00:00Z",
                          "helpfulCount": 12
                        }
                      ],
                      "pagesFetched": 1
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  }
}