Appstore Api

Read-only access to public App Store app data via track or bundle ID lookup, bounded search, and related app listings requiring Bearer workspace-key authenti...

App Store Public Reads (ReplyNodes)

Read-only App Store API for iOS app metadata and ASO research through ReplyNodes prepaid credits using one long-lived Bearer fetcher key.

This directory is the canonical appstore-api agent skill package for the ReplyNodes fetcher read domain, regenerated deterministically from services/social-data-skills/catalog/catalog_appstore.json. Every capability below maps onto an operation implemented and behavior-tested today in services/appstore-fetcher; nothing here is aspirational. Use https://api.replynodes.com as the ReplyNodes fetcher gateway base URL.

Setup

1. Create a free ReplyNodes account at https://app.replynodes.com/auth.
2. The Free plan includes 500 one-time credits and does not require payment setup.
3. Open https://app.replynodes.com/developers and create the single long-lived ReplyNodes fetcher API key.
4. Store the secret as REPLYNODES_API_KEY in the agent secret store. Never paste it into chat, commit it, or put it in a URL.
5. Send it on API calls as Authorization: Bearer YOUR_FETCHER_KEY.

Gateway: https://api.replynodes.com

Surface status

• All nine reviewed public read methods are exposed as stable capability identifiers in the manifest: app, list, search, developer, privacy, suggest, similar, reviews, and ratings.
• Each route uses the provider method name and exact option names; app-shaped results are normalized into the public App contract and raw provider records never cross the public gateway.
• No availability, uptime, latency, or success-rate figure is claimed; example payloads are illustrative fixtures.
• Package access uses prepaid credits only: one long-lived fetcher key is sent as Authorization: Bearer YOUR_FETCHER_KEY

Package contents

File	Purpose
SKILL.md	This handbook (package entrypoint).
INSTALL.md	Step-by-step installation for every supported agent family.
PUBLICATION.md	Publication status and evidence policy (currently NOT PUBLISHED anywhere).
manifest.json	Machine-readable inventory: per-file sizes and SHA-256 digests plus the exact capability-to-operation map and unsupported-capability matrix.
CHECKSUMS.txt	sha256sum-format checksums for every packaged handbook/reference file.
llms.txt	Single-file orientation for LLM agents (byte-copy of the canonical artifact).
references/appstore-public-v1.openapi.json	OpenAPI 3.1 spec of the supported read capabilities (byte-copy).
references/appstore-mcp.schema.json	Read-only MCP-style tool manifest (byte-copy).
references/endpoints.md	Worked HTTP examples and per-agent integration snippets (byte-copy).
evidence/publication-evidence.json	Machine-readable local verification facts and prohibited-claims policy.

Read-only guarantees

• Every cataloged operation is an HTTP GET capability over public application data only.
• No purchase, review-submission, account, login, or any other write or authenticated capability exists in this domain, now or later; it is excluded by policy rather than by configuration.
• Operations can only be disabled at runtime (APPSTORE_FETCHER_DISABLED_OPERATIONS kill switch), never enabled beyond this matrix.
• No request path carries or accepts credentials, keys, or login material of any kind; the read layer performs public reads server-side.
• Only public platform data is returned; counters, scores, and prices are null when the source omits them - zeros are never fabricated - and unknown upstream fields are dropped.

Credential safety

• Authenticate at the gateway with one long-lived fetcher key sent as Authorization: Bearer YOUR_FETCHER_KEY; key fingerprints are stored server-side only as SHA-256 hashes.
• Never embed the key in client-side code, repositories, logs, screenshots, or support tickets; send it per request in the Authorization header.
• Customer-managed platform credentials are not required, accepted, or stored: callers hold only their ReplyNodes API key while reads run server-side.
• The App Store read layer accepts no credential material on any path; requests carry position and selection data plus an opaque correlation id only.

Prepaid credits

• Payment mode: prepaid_credit only.
• Free: 500 one-time credits. Developer: 10,000 credits/month at $19/month.
• Pro: 100,000 credits/month at $99/month.
• Each App Store request costs 1 credit. Failed or provider-error requests cost zero; monthly credits do not roll over; paid overage requires an explicit cap.

First call

bash

curl -sS https://api.replynodes.com/v1/appstore/capabilities
curl -sS -H "Authorization: Bearer YOUR_FETCHER_KEY" \
  "https://api.replynodes.com/v1/appstore/apps/APP_ID"

Capabilities - exact mapping to implemented read operations

Capabilities cover single-app lookup (by numeric track id or bundle id), bounded term search, and related-app listings for public App Store data.

Capability	MCP tool	Route	Matrix operation	Implemented in
app	appstore_app	GET /v1/appstore/apps/{id}	app	services/appstore-fetcher/provider-runtime and services/replynodes-fetcher/internal/appstoreadapter
list	appstore_list	GET /v1/appstore/list	list	services/appstore-fetcher/provider-runtime and services/replynodes-fetcher/internal/appstoreadapter
search	appstore_search	GET /v1/appstore/search	search	services/appstore-fetcher/provider-runtime and services/replynodes-fetcher/internal/appstoreadapter
developer	appstore_developer	GET /v1/appstore/developer	developer	services/appstore-fetcher/provider-runtime and services/replynodes-fetcher/internal/appstoreadapter
privacy	appstore_privacy	GET /v1/appstore/privacy	privacy	services/appstore-fetcher/provider-runtime and services/replynodes-fetcher/internal/appstoreadapter
suggest	appstore_suggest	GET /v1/appstore/suggest	suggest	services/appstore-fetcher/provider-runtime and services/replynodes-fetcher/internal/appstoreadapter
similar	appstore_similar	GET /v1/appstore/apps/{id}/similar	similar	services/appstore-fetcher/provider-runtime and services/replynodes-fetcher/internal/appstoreadapter
reviews	appstore_reviews	GET /v1/appstore/reviews	reviews	services/appstore-fetcher/provider-runtime and services/replynodes-fetcher/internal/appstoreadapter
ratings	appstore_ratings	GET /v1/appstore/ratings	ratings	services/appstore-fetcher/provider-runtime and services/replynodes-fetcher/internal/appstoreadapter

Each row above is cross-checked against the implemented capability matrix in services/appstore-fetcher/internal/capabilities/capabilities.go by the repository checkers; a package whose manifest disagrees with the implemented operations fails validation.

Response envelope

Success: { "data": [ <app records> ], "meta": { "request_id": "req-...", "contract_version": "v1", "generated_at": "2026-08-23T00:00:00Z", "availability": "complete" } }. Single lookups carry exactly one element in data; searches and related listings carry zero or more; data is always present even when empty. Failure: { "error": { "code": "...", "message": "...", "request_id": "req-..." } }. meta.request_id echoes your opaque correlation id; always quote it in support requests. Normalized payloads follow contract v1: identifiers are platform-prefixed URNs (ios:app:<id>), timestamps are RFC3339 UTC, and counters, scores, and prices are explicit null when the public source omits them - zeros are never fabricated. Unknown upstream fields are dropped.

Page bounds

• Provider-specific limits are enforced by the pinned runtime; the gateway bounds request and response transport sizes without renaming options.

Normalized errors

Every non-2xx response uses the envelope above with one of: 400 invalid_request, 404 not_found, 429 rate_limited, 502 upstream_unavailable, 503 degraded. The full meaning table lives in references/endpoints.md; retry only idempotent reads on 502/503 with backoff, treat 400/404 as terminal for the attempt, and honor Retry-After on 429.

Unsupported capabilities

Capability	Reason	Notes
version_history	not supported by pinned provider	No version_history method exists in the pinned provider source.
writes_auth_private	read only policy	Writes and authenticated/private operations are excluded by the domain read-only policy.

Anything not listed under Capabilities is out of scope. Do not improvise around this matrix; requests for these capabilities are refused rather than approximated.

Install

Worked steps per agent family (OpenClaw, Hermes, ChatGPT, Claude, generic HTTP, MCP agents) are in INSTALL.md. Quick reference:

• OpenClaw: Install the skill files (SKILL.md plus llms.txt) into the agent's skill directory; tools resolve the workspace base URL and key from environment configuration.
• Hermes: Register each tool below as a function/tool definition; execute by issuing plain HTTPS GET requests with the Bearer key.
• ChatGPT: Import generated/appstore/openapi/appstore-public-v1.openapi.json as an action schema; configure bearer authentication with the workspace key.
• Claude: Declare the tools via the Model Context Protocol manifest or native tool-use JSON shown in the examples.
• generic HTTP: Any HTTP client works: GET the URL with Authorization: Bearer YOUR_FETCHER_KEY and parse the JSON response.
• MCP agents: Consume generated/appstore/mcp/appstore-mcp.schema.json: nine read-only tools with exact provider option names.

Honest scope

• Public reads only: no purchase, review submission, account, login, or any other write or authenticated capability exists in this domain, now or later.
• Capabilities beyond the supported matrix (rankings, developer catalogs, reviews, standalone ratings, suggestions) are explicitly unsupported - see the matrix in this handbook; do not improvise around it.
• This package has NOT been published to any registry or marketplace; its only distribution channel is this repository (see PUBLICATION.md).
• No live availability figures, uptime numbers, latency, or success-rate claims appear anywhere in this package; example payloads in the references are illustrative fixtures, not captured responses.
• No official platform partnership, endorsement, license grant, or data-sharing arrangement is claimed or implied.
• The base URL is a deployment-specific placeholder; no reachable host can be derived from this package.