{ "openapi": "3.0.0", "info": { "title": "AppStoreCat API", "description": "Open source app intelligence toolkit API. Provides endpoints for app registration, DNA building, store listing tracking, and analytics.", "version": "1.0.0" }, "servers": [ { "url": "http://localhost:7460/api/v1", "description": "API Server" } ], "paths": { "/account/api-tokens": { "get": { "tags": [ "Account" ], "summary": "List all API tokens", "operationId": "listApiTokens", "responses": { "200": { "description": "Token list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiTokenResource" } } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Account" ], "summary": "Create a new API token", "operationId": "createApiToken", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreApiTokenRequest" } } } }, "responses": { "201": { "description": "Token created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTokenCreatedResource" } } } }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/account/api-tokens/{tokenId}": { "delete": { "tags": [ "Account" ], "summary": "Revoke an API token", "operationId": "revokeApiToken", "parameters": [ { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Token revoked" }, "404": { "description": "Token not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/register": { "post": { "tags": [ "Auth" ], "summary": "Register a new user", "operationId": "register", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } } } }, "responses": { "201": { "description": "Registration successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResource" } } } }, "422": { "description": "Validation error" } } } }, "/auth/login": { "post": { "tags": [ "Auth" ], "summary": "Login a user", "operationId": "login", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResource" } } } }, "401": { "description": "Invalid credentials" } } } }, "/auth/logout": { "post": { "tags": [ "Auth" ], "summary": "Logout the authenticated user", "operationId": "logout", "responses": { "204": { "description": "Logged out successfully" } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/me": { "get": { "tags": [ "Auth" ], "summary": "Get authenticated user info", "operationId": "me", "responses": { "200": { "description": "User info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResource" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/account/profile": { "get": { "tags": [ "Account" ], "summary": "Get authenticated user profile", "operationId": "showProfile", "responses": { "200": { "description": "User profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResource" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Account" ], "summary": "Delete user account", "operationId": "deleteProfile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileDeleteRequest" } } } }, "responses": { "204": { "description": "Account deleted" } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Account" ], "summary": "Update user profile", "operationId": "updateProfile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileUpdateRequest" } } } }, "responses": { "200": { "description": "Profile updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResource" } } } }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/account/password": { "put": { "tags": [ "Account" ], "summary": "Update user password", "operationId": "updatePassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordUpdateRequest" } } } }, "responses": { "200": { "description": "Password updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResource" } } } }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/apps": { "get": { "tags": [ "Apps" ], "summary": "List tracked apps", "operationId": "listApps", "parameters": [ { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "List of tracked apps", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AppResource" } } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Apps" ], "summary": "Register and track an app", "operationId": "storeApp", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreAppRequest" } } } }, "responses": { "201": { "description": "App registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppDetailResource" } } } }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/apps/{platform}/{externalId}": { "get": { "tags": [ "Apps" ], "summary": "Get app details", "operationId": "showApp", "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "App details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppDetailResource" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/apps/{platform}/{externalId}/listing": { "get": { "tags": [ "Apps" ], "summary": "Get store listing for a specific country", "operationId": "appListing", "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "country_code", "in": "query", "required": true, "schema": { "type": "string", "example": "tr" } }, { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "example": "tr" } } ], "responses": { "200": { "description": "Store listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingResource" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/apps/{platform}/{externalId}/sync": { "post": { "tags": [ "Apps" ], "summary": "Trigger a sync job for this app", "operationId": "syncApp", "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sync queued or already in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncStatusResource" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/apps/{platform}/{externalId}/sync-status": { "get": { "tags": [ "Apps" ], "summary": "Get current sync status for this app", "operationId": "appSyncStatus", "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sync status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncStatusResource" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/apps/{platform}/{externalId}/track": { "post": { "tags": [ "Apps" ], "summary": "Track an app", "operationId": "trackApp", "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "App tracked" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Apps" ], "summary": "Untrack an app", "operationId": "untrackApp", "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "App untracked" } }, "security": [ { "bearerAuth": [] } ] } }, "/apps/{platform}/{externalId}/rankings": { "get": { "tags": [ "Apps" ], "summary": "List chart rankings for an app on a given date", "operationId": "listAppRankings", "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "collection", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "top_free", "top_paid", "top_grossing", "all" ] } } ], "responses": { "200": { "description": "Rankings on the selected date", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AppRankingResource" } } } } }, "404": { "description": "App not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/apps/search": { "get": { "tags": [ "Apps" ], "summary": "Search apps in stores", "operationId": "searchApps", "parameters": [ { "name": "term", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 100, "minLength": 2 } }, { "name": "platform", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "country_code", "in": "query", "required": false, "schema": { "type": "string", "default": "us", "maxLength": 2, "minLength": 2 } }, { "name": "exclude_external_ids[]", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "maxLength": 255 } } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AppSearchResultResource" } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/apps/{platform}/{externalId}/competitors": { "get": { "tags": [ "Apps" ], "summary": "List competitors for an app", "operationId": "listCompetitors", "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of competitors", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitorResource" } } } } }, "404": { "description": "App not found" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Apps" ], "summary": "Add a competitor to an app", "operationId": "storeCompetitor", "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCompetitorRequest" } } } }, "responses": { "201": { "description": "Competitor added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitorResource" } } } }, "404": { "description": "App not found" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/competitors": { "get": { "tags": [ "Apps" ], "summary": "List competitors grouped by parent app across all user apps", "operationId": "listAllCompetitors", "parameters": [ { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "Competitors grouped by parent app", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitorGroupResource" } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/apps/{platform}/{externalId}/competitors/{competitor}": { "delete": { "tags": [ "Apps" ], "summary": "Remove a competitor from an app", "operationId": "deleteCompetitor", "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "competitor", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Competitor removed" }, "404": { "description": "Not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/apps/{platform}/{externalId}/keywords": { "get": { "tags": [ "Apps" ], "summary": "Get keyword density for an app", "operationId": "appKeywords", "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "example": "en-US" } }, { "name": "ngram", "in": "query", "required": false, "schema": { "type": "integer", "example": 1, "enum": [ 1, 2, 3 ] } }, { "name": "version_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "default": "density", "enum": [ "keyword", "count", "density" ] } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 500, "minimum": 1 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated keyword density list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KeywordDensityResource" } }, "links": { "type": "object" }, "meta": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "App not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/apps/{platform}/{externalId}/keywords/compare": { "get": { "tags": [ "Apps" ], "summary": "Compare keyword density with other apps", "operationId": "compareKeywords", "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app_ids", "in": "query", "description": "App IDs to compare (max 5)", "required": true, "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "version_ids", "in": "query", "description": "Version ID per app (keyed by app ID)", "required": false, "schema": { "type": "object", "additionalProperties": { "type": "integer" } } }, { "name": "locale", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "ngram", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3 ] } } ], "responses": { "200": { "description": "Keyword comparison data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordCompareResource" } } } }, "404": { "description": "App not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/apps/{platform}/{externalId}/ratings/summary": { "get": { "tags": [ "Apps" ], "summary": "Get the rating summary (current rating + 30-day trend)", "operationId": "getRatingSummary", "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rating summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RatingSummaryResource" } } } }, "404": { "description": "App not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/apps/{platform}/{externalId}/ratings/history": { "get": { "tags": [ "Apps" ], "summary": "Get daily rating history (last N days)", "operationId": "getRatingHistory", "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "maximum": 90, "minimum": 1 } } ], "responses": { "200": { "description": "Daily history points", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RatingHistoryPointResource" } } } } }, "404": { "description": "App not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/apps/{platform}/{externalId}/ratings/country-breakdown": { "get": { "tags": [ "Apps" ], "summary": "Get the latest rating snapshot per country (iOS only)", "operationId": "getRatingCountryBreakdown", "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Per-country rating snapshots", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RatingByCountryResource" } } } } }, "404": { "description": "App not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/changes/apps": { "get": { "tags": [ "Change Monitor" ], "summary": "List store listing changes for all tracked apps", "operationId": "appChanges", "parameters": [ { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "field", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "title", "subtitle", "description", "whats_new", "screenshots", "locale_added", "locale_removed" ] } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "app_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Paginated app changes list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedChangeResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/changes/competitors": { "get": { "tags": [ "Change Monitor" ], "summary": "List store listing changes for all competitor apps", "operationId": "competitorChanges", "parameters": [ { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "field", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "title", "subtitle", "description", "whats_new", "screenshots", "locale_added", "locale_removed" ] } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "app_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Paginated competitor changes list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedChangeResponse" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/charts": { "get": { "tags": [ "Charts" ], "summary": "Get chart rankings", "operationId": "getCharts", "parameters": [ { "name": "platform", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "collection", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "top_free", "top_paid", "top_grossing" ] } }, { "name": "country_code", "in": "query", "required": false, "schema": { "type": "string", "default": "us" } }, { "name": "category_id", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Chart data", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChartEntryResource" } }, "meta": { "properties": { "snapshot_date": { "type": "string", "format": "date", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "platform": { "type": "string", "enum": [ "ios", "android" ] }, "collection": { "type": "string" }, "country_code": { "type": "string" }, "message": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/countries": { "get": { "tags": [ "Countries" ], "summary": "List active countries", "operationId": "listCountries", "responses": { "200": { "description": "List of active countries", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CountryResource" } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/dashboard": { "get": { "tags": [ "Dashboard" ], "summary": "Get dashboard summary for current user", "operationId": "dashboard", "responses": { "200": { "description": "Dashboard summary", "content": { "application/json": { "schema": { "properties": { "total_apps": { "type": "integer", "example": 5 }, "total_versions": { "type": "integer", "example": 12 }, "total_changes": { "type": "integer", "example": 8 }, "recent_changes": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "app_name": { "type": "string" }, "field_changed": { "type": "string" }, "locale": { "type": "string" }, "detected_at": { "type": "string", "format": "date-time" } }, "type": "object" } } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/explorer/screenshots": { "get": { "tags": [ "Explorer" ], "summary": "Browse screenshots across all apps", "operationId": "exploreScreenshots", "parameters": [ { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "category_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 12 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Paginated app screenshot listings", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExplorerScreenshotResource" } }, "links": { "type": "object" }, "meta": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/explorer/icons": { "get": { "tags": [ "Explorer" ], "summary": "Browse app icons across all apps", "operationId": "exploreIcons", "parameters": [ { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "category_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 48 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Paginated app icons", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExplorerIconResource" } }, "links": { "type": "object" }, "meta": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/publishers/search": { "get": { "tags": [ "Publishers" ], "summary": "Search publishers across stores", "operationId": "searchPublishers", "parameters": [ { "name": "term", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 } }, { "name": "platform", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "country_code", "in": "query", "required": false, "schema": { "type": "string", "default": "us", "maxLength": 2, "minLength": 2 } } ], "responses": { "200": { "description": "Publisher search results", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublisherSearchResultResource" } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/publishers": { "get": { "tags": [ "Publishers" ], "summary": "List publishers from user apps", "operationId": "listPublishers", "responses": { "200": { "description": "Publisher list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublisherResource" } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/publishers/{platform}/{externalId}": { "get": { "tags": [ "Publishers" ], "summary": "Get publisher details with tracked apps", "operationId": "showPublisher", "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Publisher details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublisherDetailResource" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/publishers/{platform}/{externalId}/store-apps": { "get": { "tags": [ "Publishers" ], "summary": "Fetch all apps by publisher from store", "operationId": "publisherStoreApps", "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Apps from store", "content": { "application/json": { "schema": { "properties": { "apps": { "type": "array", "items": { "$ref": "#/components/schemas/StoreAppResource" } } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/publishers/{platform}/{externalId}/import": { "post": { "tags": [ "Publishers" ], "summary": "Import and track apps from publisher", "operationId": "importPublisherApps", "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "external_ids" ], "properties": { "external_ids": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "204": { "description": "Apps imported" } }, "security": [ { "bearerAuth": [] } ] } }, "/store-categories": { "get": { "tags": [ "Store Categories" ], "summary": "List store categories", "operationId": "listStoreCategories", "parameters": [ { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ios", "android" ] } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "app", "game", "magazine" ] } } ], "responses": { "200": { "description": "List of categories", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreCategoryResource" } } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "CompetitorRelationship": { "type": "string", "example": "direct", "enum": [ "direct", "indirect", "aspiration" ] }, "LoginRequest": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "password": { "type": "string", "format": "password", "example": "password" } }, "type": "object" }, "PasswordUpdateRequest": { "required": [ "current_password", "password", "password_confirmation" ], "properties": { "current_password": { "type": "string", "format": "password" }, "password": { "type": "string", "format": "password" }, "password_confirmation": { "type": "string", "format": "password" } }, "type": "object" }, "ProfileDeleteRequest": { "required": [ "password" ], "properties": { "password": { "type": "string", "format": "password" } }, "type": "object" }, "ProfileUpdateRequest": { "properties": { "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "user@example.com" } }, "type": "object" }, "RegisterRequest": { "required": [ "name", "email", "password", "password_confirmation" ], "properties": { "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "user@example.com" }, "password": { "type": "string", "format": "password", "example": "password" }, "password_confirmation": { "type": "string", "format": "password", "example": "password" } }, "type": "object" }, "StoreApiTokenRequest": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "My MCP Token", "maxLength": 255 } }, "type": "object" }, "AppIndexRequest": { "properties": { "platform": { "type": "string", "nullable": true, "enum": [ "ios", "android" ] }, "search": { "type": "string", "nullable": true, "maxLength": 100 } }, "type": "object" }, "AppRankingIndexRequest": { "properties": { "date": { "type": "string", "format": "date", "example": "2026-04-17" }, "collection": { "type": "string", "nullable": true, "enum": [ "top_free", "top_paid", "top_grossing", "all" ] } }, "type": "object" }, "AppSearchRequest": { "required": [ "term", "platform" ], "properties": { "term": { "type": "string", "example": "instagram", "maxLength": 100, "minLength": 2 }, "platform": { "type": "string", "example": "ios", "enum": [ "ios", "android" ] }, "country_code": { "type": "string", "example": "us", "maxLength": 2, "minLength": 2 }, "exclude_external_ids": { "type": "array", "items": { "type": "string", "maxLength": 255 }, "nullable": true } }, "type": "object" }, "CompetitorAllRequest": { "properties": { "platform": { "type": "string", "nullable": true, "enum": [ "ios", "android" ] }, "search": { "type": "string", "nullable": true, "maxLength": 100 } }, "type": "object" }, "KeywordCompareRequest": { "required": [ "app_ids" ], "properties": { "app_ids": { "type": "array", "items": { "type": "integer" }, "example": [ 2, 3 ] }, "version_ids": { "type": "object", "example": { "2": 5, "3": 8 }, "additionalProperties": { "type": "integer" } }, "locale": { "type": "string", "example": "en-US" }, "ngram": { "type": "integer", "example": 1, "enum": [ 1, 2, 3, 4 ] } }, "type": "object" }, "KeywordIndexRequest": { "properties": { "locale": { "type": "string", "example": "en-US" }, "ngram": { "type": "integer", "example": 1, "enum": [ 1, 2, 3, 4 ] }, "version_id": { "type": "integer", "example": 1 }, "search": { "type": "string", "nullable": true, "maxLength": 100 }, "sort": { "type": "string", "nullable": true, "enum": [ "keyword", "count", "density" ] }, "order": { "type": "string", "nullable": true, "enum": [ "asc", "desc" ] }, "per_page": { "type": "integer", "nullable": true, "maximum": 500, "minimum": 1 }, "page": { "type": "integer", "nullable": true, "minimum": 1 } }, "type": "object" }, "ListingRequest": { "required": [ "country_code", "locale" ], "properties": { "country_code": { "type": "string", "example": "tr", "maxLength": 2, "minLength": 2 }, "locale": { "type": "string", "example": "tr", "maxLength": 10 } }, "type": "object" }, "RatingCountryBreakdownRequest": { "properties": {} }, "RatingHistoryRequest": { "properties": { "days": { "type": "integer", "example": 30, "maximum": 90, "minimum": 1 } }, "type": "object" }, "RatingSummaryRequest": { "properties": {} }, "StoreAppRequest": { "required": [ "external_id", "platform" ], "properties": { "external_id": { "type": "string", "example": "389801252" }, "platform": { "type": "string", "example": "ios", "enum": [ "ios", "android" ] } }, "type": "object" }, "StoreCompetitorRequest": { "required": [ "competitor_app_id" ], "properties": { "competitor_app_id": { "type": "integer", "example": 2 }, "relationship": { "type": "string", "example": "direct", "enum": [ "direct", "indirect", "aspiration" ] } }, "type": "object" }, "ChangeAppsRequest": { "properties": { "per_page": { "type": "integer", "nullable": true, "maximum": 100, "minimum": 1 }, "field": { "type": "string", "nullable": true, "enum": [ "title", "subtitle", "description", "whats_new", "screenshots", "locale_added", "locale_removed" ] }, "platform": { "type": "string", "nullable": true, "enum": [ "ios", "android" ] }, "search": { "type": "string", "nullable": true, "maxLength": 100 }, "app_id": { "type": "integer", "nullable": true, "minimum": 1 }, "page": { "type": "integer", "nullable": true, "minimum": 1 } }, "type": "object" }, "ChangeCompetitorsRequest": { "properties": { "per_page": { "type": "integer", "nullable": true, "maximum": 100, "minimum": 1 }, "field": { "type": "string", "nullable": true, "enum": [ "title", "subtitle", "description", "whats_new", "screenshots", "locale_added", "locale_removed" ] }, "platform": { "type": "string", "nullable": true, "enum": [ "ios", "android" ] }, "search": { "type": "string", "nullable": true, "maxLength": 100 }, "app_id": { "type": "integer", "nullable": true, "minimum": 1 }, "page": { "type": "integer", "nullable": true, "minimum": 1 } }, "type": "object" }, "ChartIndexRequest": { "required": [ "platform", "collection" ], "properties": { "platform": { "type": "string", "enum": [ "ios", "android" ] }, "collection": { "type": "string", "enum": [ "top_free", "top_paid", "top_grossing" ] }, "country_code": { "type": "string", "nullable": true, "maxLength": 2, "minLength": 2 }, "category_id": { "type": "integer", "nullable": true } }, "type": "object" }, "ExplorerIconsRequest": { "properties": { "platform": { "type": "string", "nullable": true, "enum": [ "ios", "android" ] }, "category_id": { "type": "integer", "nullable": true }, "search": { "type": "string", "nullable": true, "maxLength": 100 }, "per_page": { "type": "integer", "nullable": true, "maximum": 200, "minimum": 1 } }, "type": "object" }, "ExplorerScreenshotsRequest": { "properties": { "platform": { "type": "string", "nullable": true, "enum": [ "ios", "android" ] }, "category_id": { "type": "integer", "nullable": true }, "search": { "type": "string", "nullable": true, "maxLength": 100 }, "per_page": { "type": "integer", "nullable": true, "maximum": 50, "minimum": 1 } }, "type": "object" }, "PublisherImportRequest": { "required": [ "external_ids" ], "properties": { "external_ids": { "type": "array", "items": { "type": "string" } } }, "type": "object" }, "PublisherSearchRequest": { "required": [ "term", "platform" ], "properties": { "term": { "type": "string", "example": "Instagram", "maxLength": 100, "minLength": 2 }, "platform": { "type": "string", "example": "ios", "enum": [ "ios", "android" ] }, "country_code": { "type": "string", "example": "us", "maxLength": 2, "minLength": 2 } }, "type": "object" }, "StoreCategoryIndexRequest": { "properties": { "platform": { "type": "string", "nullable": true, "enum": [ "ios", "android" ] }, "type": { "type": "string", "nullable": true, "enum": [ "app", "game", "magazine" ] } }, "type": "object" }, "ApiTokenCreatedResource": { "required": [ "token", "plain_text_token" ], "properties": { "token": { "$ref": "#/components/schemas/ApiTokenResource" }, "plain_text_token": { "type": "string", "example": "1|abc123..." } }, "type": "object" }, "ApiTokenResource": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "My MCP Token" }, "abilities": { "type": "array", "items": { "type": "string" }, "example": "[\"mcp\"]" }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "LoginResource": { "properties": { "user": { "$ref": "#/components/schemas/UserResource" }, "token": { "type": "string", "example": "1|abc123..." } }, "type": "object" }, "UserResource": { "allOf": [ { "$ref": "#/components/schemas/User" } ] }, "AppDetailResource": { "required": [ "name" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/App" }, { "properties": { "name": { "type": "string", "example": "Instagram" }, "rating": { "type": "number", "format": "float", "example": 4.68, "nullable": true }, "rating_count": { "type": "integer", "example": 31, "nullable": true }, "version": { "type": "string", "example": "1.2.4", "nullable": true }, "file_size_bytes": { "type": "integer", "example": 73822208, "nullable": true }, "is_tracked": { "type": "boolean", "example": false }, "unavailable_countries": { "description": "Country codes where this app is not listed on the store.", "type": "array", "items": { "type": "string", "example": "ru" } }, "listings": { "type": "array", "items": { "$ref": "#/components/schemas/ListingResource" } }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/VersionResource" } }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/StoreListingChange" } }, "competitors": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitorResource" } } }, "type": "object" } ] }, "AppRankingResource": { "properties": { "country_code": { "description": "Expects a ChartEntry with an eager-loaded `snapshot.category` relation and\na `previous_rank` dynamic property attached by the controller (nullable β€”\nnull when the app did not appear in the previous snapshot).", "type": "string" }, "collection": { "type": "string" }, "category": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "rank": { "type": "integer" }, "previous_rank": { "type": "integer", "nullable": true }, "rank_change": { "type": "integer", "nullable": true }, "status": { "type": "string", "enum": [ "new", "up", "down", "same" ] }, "snapshot_date": { "type": "string", "format": "date" } }, "type": "object" }, "AppResource": { "required": [ "name" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/App" }, { "properties": { "name": { "type": "string", "example": "Instagram" }, "rating": { "type": "number", "format": "float", "example": 4.68, "nullable": true }, "rating_count": { "type": "integer", "example": 31, "nullable": true }, "version": { "type": "string", "example": "1.2.4", "nullable": true }, "is_tracked": { "type": "boolean", "example": false } }, "type": "object" } ] }, "AppSearchResultResource": { "required": [ "id", "platform", "external_id", "name" ], "properties": { "id": { "type": "integer", "example": 1 }, "platform": { "type": "string", "enum": [ "ios", "android" ] }, "external_id": { "type": "string", "example": "389801252" }, "name": { "type": "string", "example": "Instagram" }, "icon_url": { "type": "string", "nullable": true }, "publisher_name": { "type": "string", "example": "Instagram, Inc.", "nullable": true }, "rating": { "type": "number", "format": "float", "example": 4.68, "nullable": true }, "rating_count": { "type": "integer", "example": 31, "nullable": true }, "version": { "type": "string", "example": "1.2.4", "nullable": true }, "is_available": { "type": "boolean", "example": true, "nullable": true }, "is_tracked": { "type": "boolean", "example": false, "nullable": true }, "publisher": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "external_id": { "type": "string", "nullable": true }, "platform": { "type": "string", "enum": [ "ios", "android" ] } }, "type": "object", "nullable": true }, "category": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "type": "object", "nullable": true } }, "type": "object" }, "CompetitorGroupResource": { "required": [ "parent", "competitors" ], "properties": { "parent": { "$ref": "#/components/schemas/AppResource" }, "competitors": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitorResource" } } }, "type": "object" }, "CompetitorResource": { "required": [ "app" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/AppCompetitor" }, { "properties": { "app": { "$ref": "#/components/schemas/AppResource" } }, "type": "object" } ] }, "KeywordCompareResource": { "required": [ "apps", "keywords" ], "properties": { "apps": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "icon_url": { "type": "string", "nullable": true }, "versions": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "version": { "type": "string" } }, "type": "object" } } }, "type": "object" } }, "keywords": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "properties": { "count": { "type": "integer" }, "density": { "type": "number", "format": "float" } }, "type": "object" } } } }, "type": "object" }, "KeywordDensityResource": { "required": [ "keyword", "count", "density" ], "properties": { "locale": { "type": "string", "example": "en-US" }, "ngram_size": { "type": "integer", "example": 2 }, "keyword": { "type": "string", "example": "photo editor" }, "count": { "type": "integer", "example": 5 }, "density": { "type": "number", "format": "float", "example": 2.35 } }, "type": "object" }, "ListingResource": { "allOf": [ { "$ref": "#/components/schemas/StoreListing" } ] }, "RatingByCountryResource": { "required": [ "country_code", "rating", "rating_count" ], "properties": { "country_code": { "type": "string", "example": "us" }, "rating": { "type": "number", "format": "float", "example": 4.2 }, "rating_count": { "type": "integer", "example": 36 } }, "type": "object" }, "RatingHistoryPointResource": { "required": [ "date", "rating", "rating_count", "breakdown" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-03-15" }, "rating": { "type": "number", "format": "float", "example": 4.08, "nullable": true }, "rating_count": { "type": "integer", "example": 1250, "nullable": true }, "breakdown": { "properties": { "1": { "type": "integer", "example": 12 }, "2": { "type": "integer", "example": 8 }, "3": { "type": "integer", "example": 42 }, "4": { "type": "integer", "example": 120 }, "5": { "type": "integer", "example": 1068 } }, "type": "object" }, "delta_breakdown": { "properties": { "1": { "type": "integer", "example": 0 }, "2": { "type": "integer", "example": 1 }, "3": { "type": "integer", "example": 4 }, "4": { "type": "integer", "example": 12 }, "5": { "type": "integer", "example": 138 } }, "type": "object", "nullable": true }, "delta_total": { "type": "integer", "example": 155, "nullable": true } }, "type": "object" }, "RatingSummaryResource": { "required": [ "rating", "rating_count", "breakdown", "trend" ], "properties": { "rating": { "description": "Expects the underlying resource to be an associative array of the form:\n ['latest' => ?AppMetric, 'baseline' => ?AppMetric]\n\n`latest` is the most recent metric row for the relevant country.\n`baseline` is the metric row used as the 30-day comparison anchor (or null\nwhen no such row exists).", "type": "number", "format": "float", "example": 4.12 }, "rating_count": { "type": "integer", "example": 139 }, "breakdown": { "properties": { "1": { "type": "integer" }, "2": { "type": "integer" }, "3": { "type": "integer" }, "4": { "type": "integer" }, "5": { "type": "integer" } }, "type": "object", "nullable": true }, "trend": { "required": [ "rating_delta_30d", "rating_count_delta_30d" ], "properties": { "rating_delta_30d": { "type": "number", "format": "float", "nullable": true }, "rating_count_delta_30d": { "type": "integer", "nullable": true } }, "type": "object" } }, "type": "object" }, "SyncStatusResource": { "properties": { "app_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed" ] }, "current_step": { "type": "string", "nullable": true, "enum": [ "identity", "listings", "metrics", "finalize", "reconciling" ] }, "progress": { "properties": { "done": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" }, "failed_items": { "type": "array", "items": { "properties": { "type": { "type": "string", "enum": [ "listing", "metric" ] }, "locale": { "type": "string", "nullable": true }, "country_code": { "type": "string", "nullable": true }, "reason": { "type": "string", "nullable": true }, "retry_count": { "type": "integer" }, "last_attempted_at": { "type": "string", "format": "date-time", "nullable": true }, "next_retry_at": { "type": "string", "format": "date-time", "nullable": true }, "permanent_failure": { "type": "boolean" }, "last_error": { "type": "string", "nullable": true } }, "type": "object" } }, "failed_items_count": { "type": "integer" }, "error_message": { "type": "string", "nullable": true }, "job_id": { "type": "string", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "next_retry_at": { "type": "string", "format": "date-time", "nullable": true }, "elapsed_ms": { "type": "integer", "nullable": true } }, "type": "object" }, "VersionResource": { "allOf": [ { "$ref": "#/components/schemas/AppVersion" } ] }, "ChangeResource": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/StoreListingChange" }, { "properties": { "app": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "platform": { "type": "string", "enum": [ "ios", "android" ] }, "external_id": { "type": "string" }, "icon_url": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "version": { "type": "string", "nullable": true }, "previous_version": { "type": "string", "nullable": true } }, "type": "object" } ] }, "ChartEntryResource": { "properties": { "rank": { "type": "integer" }, "rank_change": { "type": "integer", "nullable": true }, "app_id": { "type": "integer" }, "app_external_id": { "type": "string" }, "app_name": { "type": "string" }, "icon_url": { "type": "string", "nullable": true }, "platform": { "type": "string", "enum": [ "ios", "android" ] }, "publisher": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "category_name": { "type": "string", "nullable": true }, "price": { "type": "number", "format": "float" }, "currency": { "type": "string", "nullable": true }, "is_free": { "type": "boolean" } }, "type": "object" }, "CountryResource": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/Country" }, { "properties": { "ios_languages": { "type": "array", "items": { "type": "string" }, "nullable": true }, "android_languages": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "type": "object" } ] }, "DashboardResource": { "properties": { "total_apps": { "type": "integer", "example": 5 }, "total_versions": { "type": "integer", "example": 12 }, "total_changes": { "type": "integer", "example": 8 }, "recent_changes": { "type": "array", "items": { "type": "object" } } }, "type": "object" }, "ExplorerIconResource": { "properties": { "app_id": { "type": "integer" }, "external_id": { "type": "string" }, "platform": { "type": "string", "enum": [ "ios", "android" ] }, "name": { "type": "string" }, "icon_url": { "type": "string", "nullable": true }, "publisher_name": { "type": "string", "nullable": true }, "category_name": { "type": "string", "nullable": true } }, "type": "object" }, "ExplorerScreenshotResource": { "properties": { "app_id": { "type": "integer" }, "external_id": { "type": "string" }, "platform": { "type": "string", "enum": [ "ios", "android" ] }, "name": { "type": "string" }, "icon_url": { "type": "string", "nullable": true }, "publisher_name": { "type": "string", "nullable": true }, "category_name": { "type": "string", "nullable": true }, "screenshots": { "type": "array", "items": { "required": [ "url", "device_type", "order" ], "properties": { "url": { "type": "string" }, "device_type": { "type": "string", "example": "iphone" }, "order": { "type": "integer" } }, "type": "object" } } }, "type": "object" }, "MessageResource": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Operation completed successfully" } }, "type": "object" }, "PaginatedChangeResponse": { "required": [ "data", "meta" ], "properties": { "data": { "description": "Schema-only class documenting the paginator envelope that wraps\n`ChangeResource::collection($paginator)`. Swagger refs this shape so Orval\ngenerates the correct paginated response type for both change-monitor\nendpoints.\n\nThis file holds no runtime behaviour β€” `ChangeResource` itself performs\nthe per-row transformation; the controller adds `meta_ext` via\n`additional(...)`.", "type": "array", "items": { "$ref": "#/components/schemas/ChangeResource" } }, "links": { "properties": { "first": { "type": "string", "nullable": true }, "last": { "type": "string", "nullable": true }, "prev": { "type": "string", "nullable": true }, "next": { "type": "string", "nullable": true } }, "type": "object" }, "meta": { "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" }, "meta_ext": { "properties": { "has_scope_apps": { "type": "boolean" } }, "type": "object" } }, "type": "object" }, "PublisherDetailResource": { "properties": { "publisher": { "$ref": "#/components/schemas/PublisherResource" }, "apps": { "type": "array", "items": { "$ref": "#/components/schemas/AppResource" } } }, "type": "object" }, "PublisherResource": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/Publisher" }, { "properties": { "apps_count": { "type": "integer", "example": 5, "nullable": true } }, "type": "object" } ] }, "PublisherSearchResultResource": { "required": [ "external_id", "name", "platform" ], "properties": { "external_id": { "type": "string", "example": "389801255" }, "name": { "type": "string", "example": "Meta Platforms, Inc." }, "url": { "type": "string", "nullable": true }, "platform": { "type": "string", "example": "ios", "enum": [ "ios", "android" ] }, "app_count": { "type": "integer", "example": 5 }, "sample_apps": { "type": "array", "items": { "properties": { "name": { "type": "string" }, "icon_url": { "type": "string", "nullable": true } }, "type": "object" } } }, "type": "object" }, "StoreAppResource": { "required": [ "external_id", "name" ], "properties": { "external_id": { "type": "string", "example": "389801252" }, "name": { "type": "string", "example": "Instagram" }, "icon_url": { "type": "string", "nullable": true }, "rating": { "type": "number", "format": "float", "nullable": true }, "rating_count": { "type": "integer", "nullable": true }, "is_free": { "type": "boolean" }, "category": { "type": "string", "nullable": true }, "is_tracked": { "type": "boolean" } }, "type": "object" }, "StoreCategoryResource": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/StoreCategory" }, { "properties": { "parent_id": { "type": "integer", "nullable": true }, "type": { "type": "string", "nullable": true, "enum": [ "app", "game", "magazine" ] }, "external_id": { "type": "string", "nullable": true } }, "type": "object" } ] }, "App": { "required": [ "id", "platform", "external_id" ], "properties": { "id": { "type": "integer", "example": 1 }, "platform": { "type": "string", "enum": [ "ios", "android" ] }, "external_id": { "type": "string", "example": "389801252" }, "display_name": { "type": "string", "example": "Instagram", "nullable": true }, "icon_url": { "type": "string", "nullable": true }, "origin_country_code": { "type": "string", "example": "us" }, "supported_locales": { "type": "array", "items": { "type": "string" }, "nullable": true }, "original_release_date": { "type": "string", "format": "date", "nullable": true }, "is_free": { "type": "boolean", "example": true }, "is_available": { "type": "boolean", "example": true }, "publisher": { "oneOf": [ { "$ref": "#/components/schemas/Publisher" } ], "nullable": true }, "category": { "oneOf": [ { "$ref": "#/components/schemas/StoreCategory" } ], "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "AppCompetitor": { "required": [ "id", "app_id", "competitor_app_id", "relationship" ], "properties": { "id": { "type": "integer", "example": 1 }, "app_id": { "type": "integer" }, "competitor_app_id": { "type": "integer" }, "relationship": { "$ref": "#/components/schemas/CompetitorRelationship" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "AppMetric": { "properties": { "id": { "type": "integer", "example": 1 }, "country_code": { "type": "string", "example": "us" }, "date": { "type": "string", "format": "date", "example": "2026-04-07" }, "rating": { "type": "number", "format": "float", "example": 4.68 }, "rating_count": { "type": "integer", "example": 31 }, "rating_breakdown": { "type": "object", "nullable": true }, "rating_delta": { "type": "integer", "nullable": true }, "price": { "type": "number", "format": "float", "example": 0, "nullable": true }, "currency": { "type": "string", "example": "USD", "nullable": true }, "installs_range": { "type": "string", "example": "1,000,000+", "nullable": true }, "file_size_bytes": { "type": "integer", "example": 73822208, "nullable": true }, "is_available": { "type": "boolean", "example": true } }, "type": "object" }, "AppVersion": { "required": [ "id", "version" ], "properties": { "id": { "type": "integer", "example": 1 }, "version": { "type": "string", "example": "1.2.4" }, "release_date": { "type": "string", "format": "date", "example": "2026-01-15", "nullable": true }, "whats_new": { "type": "string", "nullable": true }, "file_size_bytes": { "type": "integer", "example": 73822208, "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Country": { "required": [ "code", "name", "emoji" ], "properties": { "code": { "type": "string", "example": "us" }, "name": { "type": "string", "example": "United States" }, "emoji": { "type": "string", "example": "πŸ‡ΊπŸ‡Έ" } }, "type": "object" }, "Publisher": { "required": [ "id", "name", "platform" ], "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Instagram, Inc." }, "external_id": { "type": "string", "example": "389801255", "nullable": true }, "platform": { "type": "string", "enum": [ "ios", "android" ] }, "url": { "type": "string", "example": "https://apps.apple.com/us/developer/instagram-inc/id389801255", "nullable": true } }, "type": "object" }, "StoreCategory": { "required": [ "id", "name", "slug", "platform" ], "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Photo & Video" }, "slug": { "type": "string", "example": "photo-video" }, "platform": { "type": "string", "enum": [ "ios", "android" ] } }, "type": "object" }, "StoreListing": { "required": [ "id", "locale" ], "properties": { "id": { "type": "integer", "example": 1 }, "version_id": { "type": "integer", "nullable": true }, "locale": { "type": "string", "example": "tr" }, "title": { "type": "string", "example": "Instagram" }, "subtitle": { "type": "string", "example": "Photos & Videos", "nullable": true }, "description": { "type": "string" }, "promotional_text": { "type": "string", "nullable": true }, "whats_new": { "type": "string", "nullable": true }, "icon_url": { "type": "string", "nullable": true }, "screenshots": { "type": "array", "items": { "properties": { "url": { "type": "string" }, "device_type": { "type": "string", "example": "iphone" }, "order": { "type": "integer" } }, "type": "object" }, "nullable": true }, "price": { "type": "number", "format": "float", "example": 6.99 }, "currency": { "type": "string", "example": "USD", "nullable": true }, "video_url": { "type": "string", "nullable": true }, "fetched_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "StoreListingChange": { "properties": { "id": { "type": "integer", "example": 1 }, "version_id": { "type": "integer", "nullable": true }, "locale": { "type": "string", "example": "en-US" }, "field_changed": { "type": "string", "example": "description" }, "old_value": { "type": "string", "nullable": true }, "new_value": { "type": "string", "nullable": true }, "detected_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "SyncStatus": { "required": [ "id", "app_id", "status" ], "properties": { "id": { "type": "integer", "example": 1 }, "app_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed" ] }, "current_step": { "type": "string", "nullable": true, "enum": [ "identity", "listings", "metrics", "finalize", "reconciling" ] }, "progress_done": { "type": "integer", "example": 0 }, "progress_total": { "type": "integer", "example": 0 }, "failed_items": { "type": "array", "items": { "type": "object" }, "nullable": true }, "error_message": { "type": "string", "nullable": true }, "job_id": { "type": "string", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "next_retry_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "User": { "required": [ "id", "name", "email" ], "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "user@example.com" }, "email_verified_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "securitySchemes": { "bearerAuth": { "type": "http", "description": "Authentication using Bearer token. Example: Bearer {your-token}", "bearerFormat": "Sanctum", "scheme": "bearer" } } }, "tags": [ { "name": "Auth", "description": "Authentication endpoints" }, { "name": "Account", "description": "Account and profile management" }, { "name": "Apps", "description": "App registration and management" }, { "name": "Change Monitor", "description": "Change Monitor" }, { "name": "Charts", "description": "Charts" }, { "name": "Countries", "description": "Countries" }, { "name": "Dashboard", "description": "Dashboard" }, { "name": "Explorer", "description": "Explorer" }, { "name": "Publishers", "description": "Publishers" }, { "name": "Store Categories", "description": "Store Categories" } ] }