api.socialfetch.dev

{
  "description": "Standard success response envelope.",
  "properties": {
    "data": {
      "description": "Endpoint-specific response payload.",
      "properties": {
        "channel": {
          "description": "Channel details when available.",
          "nullable": true,
          "properties": {
            "avatarUrl": {
              "description": "Best available square avatar image URL.",
              "nullable": true,
              "type": "string"
            },
            "bannerUrl": {
              "description": "Channel banner image URL when available.",
              "nullable": true,
              "type": "string"
            },
            "bio": {
              "description": "Channel description text when available.",
              "nullable": true,
              "type": "string"
            },
            "country": {
              "description": "Country label when available.",
              "nullable": true,
              "type": "string"
            },
            "displayName": {
              "description": "Public display name for the YouTube channel.",
              "nullable": true,
              "type": "string"
            },
            "externalLinks": {
              "description": "Deduplicated outbound links associated with the channel when available.",
              "items": {
                "minLength": 1,
                "type": "string"
              },
              "type": "array"
            },
            "handle": {
              "description": "YouTube channel handle without the leading @.",
              "type": "string"
            },
            "joinedDateText": {
              "description": "Human-readable join date text from YouTube when available (not guaranteed to parse to a calendar date).",
              "nullable": true,
              "type": "string"
            },
            "platform": {
              "description": "Social platform for this channel.",
              "enum": [
                "youtube"
              ],
              "type": "string"
            },
            "platformUserId": {
              "description": "YouTube channel id (stable identifier for the channel).",
              "type": "string"
            },
            "profileUrl": {
              "description": "Canonical public YouTube channel URL.",
              "minLength": 1,
              "type": "string"
            },
            "verified": {
              "description": "Whether the channel is marked as verified.",
              "type": "boolean"
            }
          },
          "required": [
            "platform",
            "handle",
            "displayName",
            "bio",
            "avatarUrl",
            "bannerUrl",
            "verified",
            "profileUrl"
          ],
          "type": "object"
        },
        "lookupStatus": {
          "description": "Whether the channel was found.",
          "enum": [
            "found",
            "not_found"
          ],
          "type": "string"
        },
        "metrics": {
          "description": "Channel metrics when available.",
          "nullable": true,
          "properties": {
            "subscribers": {
              "description": "Subscriber count for the channel when available.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            },
            "videos": {
              "description": "Public video count for the channel when available.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            },
            "views": {
              "description": "Total view count reported for the channel when available.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            }
          },
          "required": [
            "subscribers",
            "videos",
            "views"
          ],
          "type": "object"
        }
      },
      "required": [
        "lookupStatus",
        "channel",
        "metrics"
      ],
      "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"
}