api.socialfetch.dev

{
  "description": "Standard success response envelope.",
  "properties": {
    "data": {
      "description": "Endpoint-specific response payload.",
      "properties": {
        "album": {
          "description": "Album details when available.",
          "nullable": true,
          "properties": {
            "albumId": {
              "description": "Stable Spotify album identifier.",
              "minLength": 1,
              "type": "string"
            },
            "albumType": {
              "description": "Release type (album, single, compilation, etc.).",
              "enum": [
                "album",
                "single",
                "compilation",
                "ep",
                "unknown"
              ],
              "type": "string"
            },
            "albumUrl": {
              "description": "Canonical public Spotify album URL.",
              "minLength": 1,
              "type": "string"
            },
            "artists": {
              "description": "Album artists when available.",
              "items": {
                "description": "Artist credited on a Spotify album.",
                "properties": {
                  "artistId": {
                    "description": "Spotify artist id.",
                    "minLength": 1,
                    "type": "string"
                  },
                  "avatarUrl": {
                    "description": "Best available square avatar image URL when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "displayName": {
                    "description": "Artist display name on this album.",
                    "minLength": 1,
                    "type": "string"
                  },
                  "profileUrl": {
                    "description": "Canonical public Spotify artist profile URL.",
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "artistId",
                  "displayName",
                  "profileUrl"
                ],
                "type": "object"
              },
              "minItems": 1,
              "type": "array"
            },
            "copyright": {
              "description": "Copyright lines when available.",
              "items": {
                "description": "Copyright line on a Spotify album.",
                "properties": {
                  "text": {
                    "description": "Copyright notice text.",
                    "minLength": 1,
                    "type": "string"
                  },
                  "type": {
                    "description": "Copyright type code.",
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "coverArtUrl": {
              "description": "Best available square cover image URL when available.",
              "nullable": true,
              "type": "string"
            },
            "isPreRelease": {
              "description": "Whether the album is marked as a pre-release.",
              "type": "boolean"
            },
            "label": {
              "description": "Record label when available.",
              "nullable": true,
              "type": "string"
            },
            "platform": {
              "description": "Platform for this album.",
              "enum": [
                "spotify"
              ],
              "type": "string"
            },
            "playable": {
              "description": "Whether the album is playable on Spotify.",
              "type": "boolean"
            },
            "releaseDate": {
              "description": "Release date as an ISO 8601 string when available.",
              "minLength": 1,
              "type": "string"
            },
            "releaseDatePrecision": {
              "description": "Precision of the release date when available.",
              "enum": [
                "day",
                "month",
                "year"
              ],
              "type": "string"
            },
            "title": {
              "description": "Album title.",
              "minLength": 1,
              "type": "string"
            },
            "trackCount": {
              "description": "Number of tracks on the album.",
              "minimum": 0,
              "type": "integer"
            },
            "tracks": {
              "description": "Album tracks in track order.",
              "items": {
                "description": "Track on a Spotify album.",
                "properties": {
                  "artists": {
                    "description": "Artists credited on this track.",
                    "items": {
                      "description": "Artist credited on a Spotify album track.",
                      "properties": {
                        "artistId": {
                          "description": "Spotify artist id for this track.",
                          "minLength": 1,
                          "type": "string"
                        },
                        "displayName": {
                          "description": "Artist display name on this track.",
                          "minLength": 1,
                          "type": "string"
                        }
                      },
                      "required": [
                        "artistId",
                        "displayName"
                      ],
                      "type": "object"
                    },
                    "minItems": 1,
                    "type": "array"
                  },
                  "discNumber": {
                    "description": "Disc number for this track.",
                    "exclusiveMinimum": true,
                    "minimum": 0,
                    "type": "integer"
                  },
                  "durationMs": {
                    "description": "Track duration in milliseconds.",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "explicit": {
                    "description": "Whether the track is marked explicit.",
                    "type": "boolean"
                  },
                  "playCount": {
                    "description": "Reported play count when available.",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "title": {
                    "description": "Track title.",
                    "minLength": 1,
                    "type": "string"
                  },
                  "trackId": {
                    "description": "Stable Spotify track identifier.",
                    "minLength": 1,
                    "type": "string"
                  },
                  "trackNumber": {
                    "description": "Track number on the disc.",
                    "exclusiveMinimum": true,
                    "minimum": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "trackId",
                  "title",
                  "trackNumber",
                  "discNumber",
                  "durationMs",
                  "explicit",
                  "artists"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "platform",
            "albumId",
            "title",
            "albumType",
            "label",
            "releaseDate",
            "coverArtUrl",
            "albumUrl",
            "playable",
            "copyright",
            "artists",
            "trackCount",
            "tracks"
          ],
          "type": "object"
        },
        "lookupStatus": {
          "description": "Whether the album was found.",
          "enum": [
            "found",
            "not_found"
          ],
          "type": "string"
        }
      },
      "required": [
        "lookupStatus",
        "album"
      ],
      "type": "object"
    },
    "meta": {
      "description": "Metadata describing the request and billing outcome.",
      "properties": {
        "cached": {
          "description": "True when served from shared response cache. Credits still apply (full endpoint price); Age header may be present.",
          "type": "boolean"
        },
        "creditsCharged": {
          "description": "Credits charged for this request.",
          "minimum": 0,
          "type": "integer"
        },
        "requestId": {
          "description": "Unique request identifier for tracing this API call.",
          "minLength": 1,
          "type": "string"
        },
        "version": {
          "description": "Public API version that served the response.",
          "enum": [
            "v1"
          ],
          "type": "string"
        }
      },
      "required": [
        "requestId",
        "creditsCharged",
        "version"
      ],
      "type": "object"
    }
  },
  "required": [
    "data",
    "meta"
  ],
  "type": "object"
}