AppTierList

Every ranked category (product type): slug, title, section, parent, how many apps are tiered, its #1 app, ranking_status (ranked; under_review: fewer than 6 apps checked against it yet; too_few: fewer than 6 apps in it at all; either way no ranking and no #1) and under_review_count (apps listed but not checked yet). Use the slug with get_category. verbose=true adds each definition, excludes, counts and URLs (about 10x larger). Default: active only; status=all includes drafts (unpublished, being built) and archived (kept, no longer recommended).

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "active",
        "draft",
        "archived",
        "all"
      ],
      "default": "active"
    },
    "verbose": {
      "type": "boolean",
      "description": "include definitions, excludes, counts and URLs"
    }
  }
}

The tier list for one category: members in order with tier, score, the score components, per-store search ranks, membership status (active), confidence (normal|provisional), maker verification, freshness. Each ranked member carries a compact app (name, one-liner, price, rating, links); unranked and under_review entries carry a smaller one (name, rating, links). Full details of any app are at its api_url, or get_app. Positions are only meaningful within this category. under_review lists the apps not yet checked against this category's definition (review_status: "under_review"): they have no tier and no position, come after every ranked app, and should not be presented as ranked. ranking_status "under_review" means fewer than 6 apps are checked and "too_few" fewer than 6 apps in all, so the category has no ranking yet. An app whose missing_since is set is no longer on the App Store: do not recommend it or send anyone to its store_url. A merged category's slug answers with the category it was merged into, with merged_from.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "category slug from list_categories"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "max members to return (default 20; 40 is the whole tiered set)"
    }
  },
  "required": [
    "slug"
  ]
}

One app by slug or App Store id: App Store facts, generated summary, every category membership with tier/score/status/confidence and review_status (checked, or under_review: not checked against that category yet, so tier and position are null) and list_ranking_status (the category's own ranking_status: tier and position are null unless it is ranked), main_list (the list slug of the app's main job: the first category the placer marked primary on the current App Store listing; null when no read of the current listing marks one (never guessed). An app's alternatives belong to this job), maker claim status, recent history. An app whose missing_since is set is no longer on the App Store: do not recommend it or send anyone to its store_url.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "app slug or numeric app_store_id"
    }
  },
  "required": [
    "key"
  ]
}

Find categories by name or definition and apps by name, word by word: 'best free ai companion', 'apps like calm' (the categories Calm is ranked in), 'chat gpt'. Filler words (best, free, app, like) are ignored. Returns summaries with compact apps; follow up with get_category or get_app. When nothing matches every word, the categories matching some of them come back with a hint.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "free text, e.g. 'ai girlfriend', 'period tracker', 'apps like calm'"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "max results per kind (default 20)"
    },
    "made_for_iphone_duo": {
      "type": "boolean",
      "description": "true: only apps with Apple's Made for iPhone Duo badge (iPhone Duo screenshots on the listing), best tier first, then most rated; query may be empty to list them all, and no categories come back"
    }
  },
  "required": [
    "query"
  ]
}

Why an app sits where it does: score components per category, per-store search ranks, every judge verdict (with reason, whether it is current for the app's present listing and the category's present definition), and the app's change history. An app whose missing_since is set is no longer on the App Store: do not recommend it or send anyone to its store_url.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "app slug or numeric app_store_id"
    },
    "list": {
      "type": "string",
      "description": "optional category slug to restrict to"
    }
  },
  "required": [
    "key"
  ]
}

Apps that do the same job as the given app, in three groups: most_similar (S to C tier; apps that also sit in more of this app's other categories first, then the same App Store genre, then tier), top_rated (the category's own order) and best_free (free to download, in-app purchases allowed); each app in one group at most, every one with why it is there (shared_lists, same_genre, free). all lists every alternative. They all come from the app's main-job category, so none does a different job. An app whose missing_since is set is no longer on the App Store: its alternatives matter most then.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "app slug or numeric app_store_id"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 60,
      "description": "max apps in all (default 20)"
    }
  },
  "required": [
    "key"
  ]
}

Side-by-side tier, position, score and components for two or more apps in one category (or in every category they share when list is omitted). An app with review_status under_review is not checked against that category yet: no tier, no position. Never compares positions across different categories.

{
  "type": "object",
  "properties": {
    "keys": {
      "type": "array",
      "minItems": 2,
      "maxItems": 10,
      "items": {
        "type": "string",
        "description": "app slug or app_store_id"
      }
    },
    "list": {
      "type": "string",
      "description": "category slug; omitted = every category all the apps share"
    }
  },
  "required": [
    "keys"
  ]
}

Append-only history: memberships added/removed, tier changes, categories created/activated/archived, apps discovered/missing. Newest first (by time, then id); page with cursor. To poll for new events use after_id instead: events whose seq is greater than after_id, oldest first by seq, each with its seq, and next_after_id (the last seq) to send next time (start at 0); seq is the order events became public, so it never misses an event written late or shown after review, which since can (not with since, cursor or summary). since is exact for events: only changes after that instant. summary=true answers 'what moved this week' in one call instead: per category, apps added/removed/contested, each app's net tier move (up, down, entered or left the top 40) with the S/A moves and membership changes as highlights (each with its reason: why it moved, e.g. under review or checked), plus catalog events; window from since rounded down to its UTC day (default 7 days back, at most the last 31 days), counted over every event in it. By default the 15 busiest categories (lists_total says how many changed); pass list for one.

{
  "type": "object",
  "properties": {
    "since": {
      "type": "string",
      "description": "ISO-8601 timestamp. Events: only changes after this exact instant. summary: rounded down to its UTC day, within the last 31 days",
      "format": "date-time"
    },
    "list": {
      "type": "string",
      "description": "category slug",
      "pattern": "^[a-z0-9][a-z0-9-]{0,199}$"
    },
    "kind": {
      "type": "string",
      "description": "one change kind (not with summary)",
      "enum": [
        "membership_added",
        "membership_removed",
        "membership_contested",
        "tier_changed",
        "list_created",
        "list_activated",
        "list_archived",
        "list_definition_changed",
        "app_added",
        "app_missing",
        "app_returned",
        "app_described",
        "claim_dropped"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "description": "default 100 (not with summary)"
    },
    "cursor": {
      "type": "integer",
      "minimum": 1,
      "maximum": 2147483647,
      "description": "next_cursor from the previous page (not with summary)"
    },
    "after_id": {
      "type": "integer",
      "minimum": 0,
      "maximum": 2147483647,
      "description": "polling: events whose seq is greater than this, oldest first by seq; send next_after_id from the previous answer, 0 to start (not with since, cursor or summary)"
    },
    "summary": {
      "type": "boolean",
      "description": "true: a per-category digest of the window instead of raw events"
    }
  }
}

Is the data being maintained: per-job last success and next due time, provider cool-downs, invariant check status, counts of pending judgments, stale apps, and public_unchecked (memberships shown as under review, expected to fall to 0).

{
  "type": "object",
  "properties": {}
}

Search categories and apps; returns results with an id to pass to fetch (list:<slug> for a category's ranking, app:<slug> for an app), a title and a URL. Same matching as search_apps; when no category matched every word, a hint says the categories match only some of them.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "free text, e.g. 'best vpn' or 'apps like calm'"
    }
  },
  "required": [
    "query"
  ]
}

One document by the id search returned: list:<slug> is the category's ranking (compact members), app:<slug> the app's full record. text holds the record as JSON.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "list:<slug> or app:<slug>, from search"
    }
  },
  "required": [
    "id"
  ]
}