{
  "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": {
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Every error, on every route. Branch on code and retryable rather than on the text; on a 5xx the text is generic. MCP tool errors carry the same fields in structuredContent, and as a JSON text block.",
        "properties": {
          "error": {
            "type": "string",
            "description": "What went wrong, in words. For a 400, what to change."
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status, repeated in the body."
          },
          "code": {
            "type": "string",
            "description": "The kind of error, stable: invalid_input, unauthorized, insufficient_credits, forbidden, not_found, expired, quota_exceeded, cancelled, time_limit, temporarily_unavailable, posts_unavailable, store_unreachable, upstream_error, internal_error, tool_error. A platform may add its own; more may be added. Treat a code you do not recognise by its retryable flag."
          },
          "retryable": {
            "type": "boolean",
            "description": "Whether asking again can succeed."
          },
          "requestId": {
            "type": "string",
            "description": "This request’s id, also sent as the X-Request-Id header. Quote it when reporting a problem."
          },
          "missing": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "With invalid_input when the request's parameters are refused before the request runs: the parameters that were missing. Always present on those errors, empty when nothing was missing."
          }
        },
        "required": [
          "error",
          "code",
          "retryable",
          "requestId"
        ]
      }
    },
    "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": true
                      }
                    }
                  },
                  "additionalProperties": true
                },
                "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
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_input: the request needs fixing; error names the field.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "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, date, and pagination. Each review includes rating, title, review text, reviewer name, date and whether it was edited. 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). With the default `sort=recent`, reviews are newest-first across every page and platform, so `reviews[0]` is the newest review; passing `since` also stops pagination early once results fall before the cutoff, so a narrow date window can cost far fewer credits than `pages` alone would suggest. With `sort=helpful`, Apple's own ordering is preserved and `since` filters without stopping early, so it still fetches every requested page. 2026-11-06: any other refusal from the App Store is a retryable 503 with a Retry-After header (it used to be a 500).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "appId": {
                    "type": [
                      "string",
                      "integer"
                    ],
                    "description": "Numeric App Store app id, e.g. 375380948. Also accepts the id1234 form or an apps.apple.com link. An appId with no numeric id is a 400 naming the value (2026-11-06; Apple's parameter errors used to answer 500)."
                  },
                  "country": {
                    "type": "string",
                    "description": "Two-letter App Store country code, case-insensitive; uk is read as gb. An unknown country is a 400 naming the value (2026-11-06; it used to answer 500).",
                    "example": "us"
                  },
                  "platforms": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Filter by one or more platforms: iphone, ipad, mac, appletv, watch, realityDevice."
                  },
                  "lang": {
                    "type": "string",
                    "description": "Language code (e.g. en, ja). An unsupported language is a 400 naming the value (2026-11-06)."
                  },
                  "geo": {
                    "type": "string",
                    "description": "Two-letter geo code for regional results."
                  },
                  "pages": {
                    "type": "integer",
                    "description": "Number of pages to fetch per platform: with several `platforms`, each one is paged separately, so 2 platforms at 1 page is 2 pages. Billed per page actually retrieved (see `pagesFetched` in the response).",
                    "example": "1"
                  },
                  "reviewsPerPage": {
                    "type": "integer",
                    "description": "Reviews per page (max 20).",
                    "example": "20"
                  },
                  "sort": {
                    "type": "string",
                    "description": "Sort order: recent (default) or helpful.",
                    "example": "recent"
                  },
                  "since": {
                    "type": "string",
                    "description": "Only return reviews dated on or after this ISO 8601 date (inclusive: date >= since). Accepts a bare date like 2026-01-31 or a full timestamp like 2026-01-31T00:00:00Z; an unparseable value returns HTTP 400 and costs nothing. With sort=recent the request also stops paging once it passes the cutoff, so a narrow window can finish in far fewer than `pages` requests. With sort=helpful, Apple's feed is not date-ordered, so `since` still filters but every requested page is fetched."
                  }
                },
                "additionalProperties": false,
                "required": [
                  "appId"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "appId": "1232780281",
                    "country": "us",
                    "pages": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "appId": {
                      "type": "string",
                      "description": "App Store app ID that was requested."
                    },
                    "country": {
                      "type": "string",
                      "description": "The country storefront the reviews come from."
                    },
                    "reviews": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Unique review identifier."
                          },
                          "rating": {
                            "type": "number",
                            "description": "Star rating (1-5)."
                          },
                          "title": {
                            "type": "string",
                            "description": "Review title."
                          },
                          "review": {
                            "type": "string",
                            "description": "Full review text."
                          },
                          "userName": {
                            "type": "string",
                            "description": "Reviewer display name."
                          },
                          "date": {
                            "type": "string",
                            "description": "ISO 8601 review date."
                          },
                          "isEdited": {
                            "type": "boolean",
                            "description": "Whether the reviewer edited the review after posting it."
                          }
                        }
                      },
                      "description": "Matching review records."
                    },
                    "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 — unchanged by `since`, though with sort=recent a narrow `since` window typically makes this number much smaller."
                    },
                    "totalTimeSec": {
                      "type": "string",
                      "description": "Total time taken to fetch the requested pages, in seconds."
                    },
                    "notes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Caveats about this result. When the first page has no reviews the response is still a 200 and notes says \"No reviews were found for this app id. Check that it's the numeric id from the App Store link.\" (an unknown id looks like an app without reviews)."
                    },
                    "platforms": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "properties": {
                          "platform": {
                            "type": "string",
                            "description": "Platform name for this breakdown entry."
                          },
                          "reviews": {
                            "type": "number",
                            "description": "Number of reviews returned for this platform."
                          },
                          "pages": {
                            "type": "number",
                            "description": "Number of pages fetched for this platform."
                          },
                          "complete": {
                            "type": "boolean",
                            "description": "Whether every requested page was read for this platform."
                          }
                        }
                      },
                      "description": "Per-platform breakdown of reviews and pages fetched, one entry for each platform read."
                    },
                    "complete": {
                      "type": "boolean",
                      "description": "Whether every requested page was read on every platform."
                    },
                    "transport": {
                      "type": "string",
                      "description": "The data source: always the platform id, \"appstore\"."
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "appId": "1232780281",
                      "country": "us",
                      "reviews": [
                        {
                          "id": "14558727941",
                          "rating": 5,
                          "title": "so so perfect",
                          "review": "I rarely give apps a 5 star review … I use it for everything, I appreciate it being free to use the most and open to anyone. 10/10",
                          "userName": "lily wockens",
                          "date": "2026-09-17T02:00:56Z",
                          "isEdited": false
                        }
                      ],
                      "pagesFetched": 1,
                      "platforms": [
                        {
                          "platform": "iphone",
                          "reviews": 20,
                          "pages": 1,
                          "complete": true
                        }
                      ],
                      "totalTimeSec": "1.8",
                      "complete": true,
                      "notes": [],
                      "transport": "appstore"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_input: the request needs fixing; error names the field.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  }
}