openapi: 3.2.0 info: title: Monocrawl Spotify API version: 0.1.0 description: One key, one envelope, one credit meter across social, search, commerce and web data. contact: name: Monocrawl support url: https://www.monocrawl.com/contact termsOfService: https://www.monocrawl.com/legal/terms-and-conditions servers: - url: https://www.monocrawl.com security: - ApiKeyHeader: [] tags: - name: Spotify paths: /v1/spotify/album: get: operationId: spotify_album tags: - Spotify summary: Get a Spotify album description: Look up one Spotify album by id or open.spotify.com URL, including label, copyrights, UPC, and the first page of its track listing. Costs 1 credit per successful live response. parameters: - name: id in: query required: false schema: type: string example: 4aawyAB9vmqN3uQ7FjRGTy description: Spotify album id (this or url) - name: url in: query required: false schema: type: string example: https://open.spotify.com/album/4aawyAB9vmqN3uQ7FjRGTy description: 'open.spotify.com album URL or spotify:album: URI (this or id)' - name: market in: query required: false schema: type: string example: US description: ISO 3166-1 alpha-2 country to scope availability (optional) - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/spotify/album.json title: spotify/album data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: album_type: description: Optional album type supplied by this operation. Null means unknown. type: - string - 'null' artists: description: Optional artists supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' uri: description: Optional uri supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true copyrights: description: Optional copyrights supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: text: description: Source text when supplied. type: - string - 'null' type: description: Optional type supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true genres: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' image_url: description: Optional image url supplied by this operation. Null means unknown. type: - string - 'null' images: description: Optional images supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true kind: description: Optional kind supplied by this operation. Null means unknown. type: - string - 'null' label: description: Optional label supplied by this operation. Null means unknown. type: - string - 'null' popularity: description: Optional popularity supplied by this operation. Null means unknown. type: - number - 'null' release_date: description: Optional release date supplied by this operation. Null means unknown. type: - string - 'null' release_date_precision: description: Optional release date precision supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' total_tracks: description: Optional total tracks supplied by this operation. Null means unknown. type: - number - 'null' uri: description: Optional uri supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - album_type properties: album_type: description: Optional album type supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - artists properties: artists: description: Optional artists supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' uri: description: Optional uri supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true - required: - copyrights properties: copyrights: description: Optional copyrights supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: text: description: Source text when supplied. type: - string - 'null' type: description: Optional type supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - genres properties: genres: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - image_url properties: image_url: description: Optional image url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - images properties: images: description: Optional images supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: height: description: Optional height supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' width: description: Optional width supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - label properties: label: description: Optional label supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - popularity properties: popularity: description: Optional popularity supplied by this operation. Null means unknown. type: - number - required: - release_date properties: release_date: description: Optional release date supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - release_date_precision properties: release_date_precision: description: Optional release date precision supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - total_tracks properties: total_tracks: description: Optional total tracks supplied by this operation. Null means unknown. type: - number - required: - uri properties: uri: description: Optional uri supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - album_type: example artists: - id: example name: example uri: example url: https://example.com/example copyrights: - text: example type: example genres: [] id: example image_url: https://example.com/example images: - height: 0 url: https://example.com/example width: 0 kind: example label: example popularity: 0 release_date: '2026-09-01T12:00:00Z' release_date_precision: '2026-09-01T12:00:00Z' title: example total_tracks: 0 uri: example url: https://example.com/example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/spotify/artist: get: operationId: spotify_artist tags: - Spotify summary: Artist details description: 'One Spotify artist: followers, monthly listeners, world rank, top cities, biography and top tracks with play counts. Costs 2 credits per successful live response.' parameters: - name: id in: query required: true schema: type: string example: 0cGUm45nv7Z6M6qdXYQGTX description: Spotify artist id, from spotify/search. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/spotify/artist.json title: spotify/artist data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: biography: description: Optional biography supplied by this operation. Null means unknown. type: - string - 'null' followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' monthly_listeners: description: Optional monthly listeners supplied by this operation. Null means unknown. type: - number - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' popularity: description: Optional popularity supplied by this operation. Null means unknown. type: - number - 'null' top_cities: description: Optional top cities supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: city: description: Optional city supplied by this operation. Null means unknown. type: - string - 'null' country: description: Optional country supplied by this operation. Null means unknown. type: - string - 'null' listeners: description: Optional listeners supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true top_tracks: description: Optional top tracks supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' playcount: description: Optional playcount supplied by this operation. Null means unknown. type: - number - 'null' popularity: description: Optional popularity supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true url: description: Original source URL when supplied. type: - string - 'null' verified: description: Optional verified supplied by this operation. Null means unknown. type: - boolean - 'null' world_rank: description: Optional world rank supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true allOf: - anyOf: - required: - biography properties: biography: description: Optional biography supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - followers properties: followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - monthly_listeners properties: monthly_listeners: description: Optional monthly listeners supplied by this operation. Null means unknown. type: - number - required: - name properties: name: description: Optional name supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - popularity properties: popularity: description: Optional popularity supplied by this operation. Null means unknown. type: - number - required: - top_cities properties: top_cities: description: Optional top cities supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: city: description: Optional city supplied by this operation. Null means unknown. type: - string - 'null' country: description: Optional country supplied by this operation. Null means unknown. type: - string - 'null' listeners: description: Optional listeners supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - top_tracks properties: top_tracks: description: Optional top tracks supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' playcount: description: Optional playcount supplied by this operation. Null means unknown. type: - number - 'null' popularity: description: Optional popularity supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - verified properties: verified: description: Optional verified supplied by this operation. Null means unknown. type: - boolean - required: - world_rank properties: world_rank: description: Optional world rank supplied by this operation. Null means unknown. type: - number x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - biography: example followers: 0 id: example monthly_listeners: 0 name: example platform: example popularity: 0 top_cities: - city: example country: example listeners: 0 top_tracks: - id: example name: example playcount: 0 popularity: 0 url: https://example.com/example url: https://example.com/example verified: false world_rank: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 2 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/spotify/playlist: get: operationId: spotify_playlist tags: - Spotify summary: Spotify playlist description: A public playlist with its owner, follower count and a page of tracks with play counts. Costs 4 credits per successful live response. parameters: - name: id in: query required: true schema: type: string example: 37i9dQZF1DXcBWIGoYBM5M description: Playlist id (or pass url) - name: url in: query required: false schema: type: string example: https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M description: Playlist URL, instead of id - name: cursor in: query required: false schema: type: string example: '' description: Opaque cursor from the previous page of tracks - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/spotify/playlist.json title: spotify/playlist data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' description: description: Source description; null or absent means not supplied. type: - string - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' image_url: description: Optional image url supplied by this operation. Null means unknown. type: - string - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: album: description: Optional album supplied by this operation. Null means unknown. type: - string - 'null' artists: description: Optional artists supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true duration_ms: description: Optional duration ms supplied by this operation. Null means unknown. type: - number - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' play_count: description: Optional play count supplied by this operation. Null means unknown. type: - number - 'null' title: description: Source title when supplied. type: - string - 'null' uri: description: Optional uri supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - album properties: album: description: Optional album supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - artists properties: artists: description: Optional artists supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true - required: - duration_ms properties: duration_ms: description: Optional duration ms supplied by this operation. Null means unknown. type: - number - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - play_count properties: play_count: description: Optional play count supplied by this operation. Null means unknown. type: - number - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - uri properties: uri: description: Optional uri supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 kind: description: Optional kind supplied by this operation. Null means unknown. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' owner: description: Optional owner supplied by this operation. Null means unknown. type: - object - 'null' properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true total_tracks: description: Optional total tracks supplied by this operation. Null means unknown. type: - number - 'null' uri: description: Optional uri supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - count: 0 description: example dropped: 0 followers: 0 id: example image_url: https://example.com/example items: - album: example artists: - {} duration_ms: 0 id: example play_count: 0 title: example uri: example url: https://example.com/example kind: example name: example owner: id: example name: example url: https://example.com/example total_tracks: 0 uri: example url: https://example.com/example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 4 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/spotify/podcast: get: operationId: spotify_podcast tags: - Spotify summary: Get a Spotify podcast description: 'Look up one Spotify podcast (show) by id or open.spotify.com URL: publisher, description, languages, and total episode count. Costs 1 credit per successful live response.' parameters: - name: id in: query required: false schema: type: string example: 38bS44xjbVVZ3No3ByF1dJ description: Spotify show id (this or url) - name: url in: query required: false schema: type: string example: https://open.spotify.com/show/38bS44xjbVVZ3No3ByF1dJ description: 'open.spotify.com show URL or spotify:show: URI (this or id)' - name: market in: query required: false schema: type: string example: US description: ISO 3166-1 alpha-2 country; show availability is market-scoped (default US) - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/spotify/podcast.json title: spotify/podcast data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: id: type: - string - 'null' description: Exact source identifier; preserve it as a string. name: type: - string - 'null' description: name url: type: - string - 'null' description: url uri: type: - string - 'null' description: uri kind: type: - string - 'null' description: kind description: type: - string - 'null' description: description publisher: type: - string - 'null' description: publisher image_url: type: - string - 'null' description: image url rating: type: - number - 'null' description: rating; null is unknown. ratings_count: type: - number - 'null' description: ratings count; null is unknown. total_episodes: type: - number - 'null' description: total episodes; null is unknown. languages: type: array items: type: - string - 'null' description: Source text. topics: type: array items: type: - object - 'null' properties: title: type: - string - 'null' description: title uri: type: - string - 'null' description: uri additionalProperties: true explicit: type: - boolean - 'null' description: Explicit-content label. additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Exact source identifier; preserve it as a string. minLength: 1 - required: - name properties: name: type: - string description: name minLength: 1 - required: - url properties: url: type: - string description: url minLength: 1 - required: - uri properties: uri: type: - string description: uri minLength: 1 - required: - description properties: description: type: - string description: description minLength: 1 - required: - publisher properties: publisher: type: - string description: publisher minLength: 1 - required: - image_url properties: image_url: type: - string description: image url minLength: 1 - required: - rating properties: rating: type: - number description: rating; null is unknown. - required: - ratings_count properties: ratings_count: type: - number description: ratings count; null is unknown. - required: - total_episodes properties: total_episodes: type: - number description: total episodes; null is unknown. - required: - languages properties: languages: type: array items: type: - string - 'null' description: Source text. - required: - topics properties: topics: type: array items: type: - object - 'null' properties: title: type: - string - 'null' description: title uri: type: - string - 'null' description: uri additionalProperties: true - required: - explicit properties: explicit: type: - boolean description: Explicit-content label. x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - id: example name: Example podcast kind: show default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/spotify/podcast/episodes: get: operationId: spotify_podcast_episodes tags: - Spotify summary: List a Spotify podcast's episodes description: 'List a Spotify podcast''s episodes newest-first, paginated: title, description, duration, release date, and audio preview. Costs 1 credit per successful live response.' parameters: - name: id in: query required: false schema: type: string example: 38bS44xjbVVZ3No3ByF1dJ description: Spotify show id (this or url) - name: url in: query required: false schema: type: string example: https://open.spotify.com/show/38bS44xjbVVZ3No3ByF1dJ description: 'open.spotify.com show URL or spotify:show: URI (this or id)' - name: cursor in: query required: false schema: type: string example: '25' description: Offset for the next page (opaque, from a prior response) - name: limit in: query required: false schema: type: string example: '25' description: Episodes per page, 1-50 (default 25) - name: market in: query required: false schema: type: string example: US description: ISO 3166-1 alpha-2 country; episode availability is market-scoped (default US) - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/spotify/podcast/episodes.json title: spotify/podcast/episodes data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _meta: description: Optional meta supplied by this operation. Null means unknown. type: - object - 'null' properties: billing: description: Optional billing supplied by this operation. Null means unknown. type: - object - 'null' properties: charged: description: Optional charged supplied by this operation. Null means unknown. type: - number - 'null' list_price: description: Optional list price supplied by this operation. Null means unknown. type: - number - 'null' reason: description: Optional reason supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true additionalProperties: true dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' items: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - _meta: billing: charged: 0 list_price: 0 reason: example dropped: 0 items: [] default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/spotify/search: get: operationId: spotify_search tags: - Spotify summary: Catalog search description: 'Search the Spotify catalog: matching artists, tracks, albums and playlists with ids and links. Costs 2 credits per successful live response.' parameters: - name: query in: query required: true schema: type: string example: daft punk description: Artist, track, album or playlist name. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/spotify/search.json title: spotify/search data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: albums: description: Optional albums supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: artist: description: Optional artist supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' type: description: Optional type supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' year: description: Optional year supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true artists: description: Optional artists supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' verified: description: Optional verified supplied by this operation. Null means unknown. type: - boolean - 'null' additionalProperties: true playlists: description: Optional playlists supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: description: description: Source description; null or absent means not supplied. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true tracks: description: Optional tracks supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: album: description: Optional album supplied by this operation. Null means unknown. type: - string - 'null' artist: description: Optional artist supplied by this operation. Null means unknown. type: - string - 'null' duration_ms: description: Optional duration ms supplied by this operation. Null means unknown. type: - number - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - albums properties: albums: description: Optional albums supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: artist: description: Optional artist supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' type: description: Optional type supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' year: description: Optional year supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - artists properties: artists: description: Optional artists supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' verified: description: Optional verified supplied by this operation. Null means unknown. type: - boolean - 'null' additionalProperties: true - required: - playlists properties: playlists: description: Optional playlists supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: description: description: Source description; null or absent means not supplied. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true - required: - tracks properties: tracks: description: Optional tracks supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: album: description: Optional album supplied by this operation. Null means unknown. type: - string - 'null' artist: description: Optional artist supplied by this operation. Null means unknown. type: - string - 'null' duration_ms: description: Optional duration ms supplied by this operation. Null means unknown. type: - number - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - albums: - artist: example id: example name: example type: example url: https://example.com/example year: 0 artists: - id: example name: example url: https://example.com/example verified: false playlists: - description: example id: example name: example url: https://example.com/example tracks: - album: example artist: example duration_ms: 0 id: example name: example url: https://example.com/example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 2 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/spotify/track: get: operationId: spotify_track tags: - Spotify summary: Get a Spotify track description: Look up one Spotify track by id or open.spotify.com URL, with ISRC, duration, artists, and album context. Costs 1 credit per successful live response. parameters: - name: id in: query required: false schema: type: string example: 11dFghVXANMlKmJXsNCbNl description: Spotify track id (this or url) - name: url in: query required: false schema: type: string example: https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl description: 'open.spotify.com track URL or spotify:track: URI (this or id)' - name: market in: query required: false schema: type: string example: US description: ISO 3166-1 alpha-2 country to scope availability (optional) - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/spotify/track.json title: spotify/track data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: album: description: Optional album supplied by this operation. Null means unknown. type: - object - 'null' properties: album_type: description: Optional album type supplied by this operation. Null means unknown. type: - string - 'null' artists: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' image_url: description: Optional image url supplied by this operation. Null means unknown. type: - string - 'null' release_date: description: Optional release date supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' total_tracks: description: Optional total tracks supplied by this operation. Null means unknown. type: - number - 'null' uri: description: Optional uri supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true artists: description: Optional artists supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' uri: description: Optional uri supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true duration_ms: description: Optional duration ms supplied by this operation. Null means unknown. type: - number - 'null' explicit: description: Optional explicit supplied by this operation. Null means unknown. type: - boolean - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' kind: description: Optional kind supplied by this operation. Null means unknown. type: - string - 'null' play_count: description: Optional play count supplied by this operation. Null means unknown. type: - number - 'null' popularity: description: Optional popularity supplied by this operation. Null means unknown. type: - number - 'null' title: description: Source title when supplied. type: - string - 'null' track_number: description: Optional track number supplied by this operation. Null means unknown. type: - number - 'null' uri: description: Optional uri supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - album properties: album: description: Optional album supplied by this operation. Null means unknown. type: - object properties: album_type: description: Optional album type supplied by this operation. Null means unknown. type: - string - 'null' artists: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' image_url: description: Optional image url supplied by this operation. Null means unknown. type: - string - 'null' release_date: description: Optional release date supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' total_tracks: description: Optional total tracks supplied by this operation. Null means unknown. type: - number - 'null' uri: description: Optional uri supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true - required: - artists properties: artists: description: Optional artists supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' uri: description: Optional uri supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true - required: - duration_ms properties: duration_ms: description: Optional duration ms supplied by this operation. Null means unknown. type: - number - required: - explicit properties: explicit: description: Optional explicit supplied by this operation. Null means unknown. type: - boolean - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - play_count properties: play_count: description: Optional play count supplied by this operation. Null means unknown. type: - number - required: - popularity properties: popularity: description: Optional popularity supplied by this operation. Null means unknown. type: - number - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - track_number properties: track_number: description: Optional track number supplied by this operation. Null means unknown. type: - number - required: - uri properties: uri: description: Optional uri supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - album: album_type: example artists: [] id: example image_url: https://example.com/example release_date: '2026-09-01T12:00:00Z' title: example total_tracks: 0 uri: example url: https://example.com/example artists: - id: example name: example uri: example url: https://example.com/example duration_ms: 0 explicit: false id: example kind: example play_count: 0 popularity: 0 title: example track_number: 0 uri: example url: https://example.com/example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true components: schemas: Error: type: object required: - success - error - credits_used - request_id properties: success: const: false error: type: object required: - type - message - status properties: type: type: string enum: - UNAUTHORIZED - KEY_REVOKED - KEY_LIMIT_EXCEEDED - RATE_LIMITED - INSUFFICIENT_CREDITS - RESOURCE_NOT_FOUND - INVALID_PARAMETERS - TARGET_ACCESS_DENIED - UPSTREAM_ERROR - UPSTREAM_TIMEOUT - FREE_CAPACITY_UNAVAILABLE - CAPACITY_UNAVAILABLE - ENDPOINT_NOT_FOUND - ENDPOINT_NOT_AVAILABLE - FAIR_USE_EXCEEDED - INTERNAL_ERROR message: type: string status: type: integer doc_url: type: string description: Deep link to the exact section of the errors guide for this type. details: type: object credits_used: type: - integer - 'null' description: Confirmed net charge; null when billing is pending reconciliation. Inspect error.details.billing_status and retain request_id. credits_remaining: type: integer request_id: type: string Success: type: object required: - success - platform - endpoint - data - credits_used - credits_remaining - request_id properties: _completeness: type: object description: Reported response completeness, not a guarantee of complete platform history. Missing source assertions remain unknown. properties: state: type: string enum: - complete - partial - unknown scope: type: string inspection_limited: type: boolean success: const: true platform: type: string endpoint: type: string description: The resolved path, e.g. `/v1/github/profile`. data: description: Amazon responses include marketplace.country and marketplace.domain (resolved request marketplace, UK by default). X profiles preserve location, bio_link and cover_url when supplied. TikTok profiles preserve commerce_user, seller, region, location and business_category when supplied; region identifies the account region rather than personal residence. TikTok comments use platform_default selection, which can change between fetches; keep the same video and options when following cursors. Amazon review variant is readable text. Facebook profiles preserve cover_url, following and created_at when supplied; likes_count and followers are distinct and follower totals may be rounded. Endpoint-specific normalized payload, not one universal post/profile schema. Many lists use items/count/cursor; a null cursor means no usable next cursor was supplied, not proof that all history was retrieved. Check has_more and warnings where present. Social full-profile bundles use posts_cursor and posts_pagination.next_params; retain all returned next parameters. YouTube channel bundles instead use recent_videos, cursor and recent_videos_pagination. Inspect complete/partial/legs where supplied for bounded or failed components. Optional model-derived fields are labelled, not source facts. credits_used: type: integer credits_remaining: type: integer request_id: type: string cached: type: boolean stale: type: boolean description: True only for an explicitly labelled, zero-credit reference snapshot served after a temporary upstream failure. age_seconds: type: integer minimum: 0 description: Age of a stale snapshot since its original retrieval; not reset by outage recovery. fetched_at: type: string format: date-time description: Original retrieval time of a stale snapshot, in UTC. synthetic: type: boolean description: Present and true only on the explicitly requested /sandbox surface. Synthetic responses are representative and charged 0 credits; production /v1 never returns them. degraded: type: boolean description: Reserved for sandbox compatibility. Production /v1 reports upstream failure as an error and never serves a representative fallback. securitySchemes: ApiKeyHeader: type: apiKey in: header name: x-api-key description: Your API key (`mn_…`), from the console. The recommended style. BearerKey: type: http scheme: bearer description: The same key as a Bearer token, for clients that only expose an Authorization field. Keys are never accepted in the query string — URLs leak into logs and referrers. x-provenance: method: harvested publisher: Monocrawl source: https://www.monocrawl.com/openapi.json note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json); stamped by stamp-openapi-provenance.py (roadmap#793)