{
  "openapi": "3.1.0",
  "info": {
    "title": "App Store API — Search",
    "version": "1.0.0",
    "description": "Search the App Store for apps by name or keyword."
  },
  "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": "array",
                            "items": {
                              "type": "string"
                            },
                            "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": [
                        {
                          "appId": "1232780281",
                          "name": "Notion: Notes, Tasks, AI",
                          "subtitle": "Plan, organize, track projects",
                          "rating": null,
                          "ratingCount": null,
                          "screenshots": [
                            "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/94/dd/d8/…/1284x2778bb.jpg"
                          ],
                          "editorsChoice": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  }
}