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": "Spotify album identifier.",
              "minLength": 1,
              "type": "string"
            },
            "albumType": {
              "description": "Album type when available.",
              "minLength": 1,
              "type": "string"
            },
            "albumUrl": {
              "description": "Canonical public Spotify album URL when available.",
              "minLength": 1,
              "type": "string"
            },
            "coverArtUrl": {
              "description": "Best available album cover image URL when available.",
              "nullable": true,
              "type": "string"
            },
            "releaseDateIso": {
              "description": "Release date ISO string when available.",
              "minLength": 1,
              "type": "string"
            },
            "releaseYear": {
              "description": "Release year when available.",
              "type": "integer"
            },
            "title": {
              "description": "Album title.",
              "minLength": 1,
              "type": "string"
            },
            "trackCount": {
              "description": "Number of tracks on the album when available.",
              "minimum": 0,
              "type": "integer"
            }
          },
          "required": [
            "albumId",
            "title"
          ],
          "type": "object"
        },
        "artists": {
          "description": "Artists credited on the track (may be empty).",
          "items": {
            "description": "Artist credited on a Spotify track.",
            "properties": {
              "artistId": {
                "description": "Spotify artist identifier.",
                "minLength": 1,
                "type": "string"
              },
              "avatarUrl": {
                "description": "Best available artist avatar URL when available.",
                "nullable": true,
                "type": "string"
              },
              "displayName": {
                "description": "Artist display name.",
                "minLength": 1,
                "type": "string"
              },
              "profileUrl": {
                "description": "Canonical public Spotify artist profile URL when available.",
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "artistId",
              "displayName"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "lookupStatus": {
          "description": "Whether the track was found.",
          "enum": [
            "found",
            "not_found"
          ],
          "type": "string"
        },
        "track": {
          "description": "Track details when available.",
          "nullable": true,
          "properties": {
            "durationMs": {
              "description": "Track duration in milliseconds.",
              "minimum": 0,
              "type": "integer"
            },
            "explicit": {
              "description": "Whether the track is marked explicit when available.",
              "type": "boolean"
            },
            "mediaType": {
              "description": "Media type when available.",
              "minLength": 1,
              "type": "string"
            },
            "platform": {
              "description": "Platform for this track.",
              "enum": [
                "spotify"
              ],
              "type": "string"
            },
            "playCount": {
              "description": "Play count when available.",
              "minimum": 0,
              "type": "integer"
            },
            "playable": {
              "description": "Whether the track is playable in the current context.",
              "type": "boolean"
            },
            "previewUrl": {
              "description": "Short audio preview URL when available.",
              "minLength": 1,
              "type": "string"
            },
            "title": {
              "description": "Track title.",
              "minLength": 1,
              "type": "string"
            },
            "trackId": {
              "description": "Stable Spotify track identifier.",
              "minLength": 1,
              "type": "string"
            },
            "trackNumber": {
              "description": "Track number on the album when available.",
              "exclusiveMinimum": true,
              "minimum": 0,
              "type": "integer"
            },
            "trackUrl": {
              "description": "Canonical public Spotify track URL.",
              "minLength": 1,
              "type": "string"
            }
          },
          "required": [
            "platform",
            "trackId",
            "title",
            "durationMs",
            "playable",
            "trackUrl"
          ],
          "type": "object"
        }
      },
      "required": [
        "lookupStatus",
        "track",
        "album",
        "artists"
      ],
      "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"
}