api.socialfetch.dev

{
  "description": "Standard success response envelope.",
  "properties": {
    "data": {
      "description": "Endpoint-specific response payload.",
      "properties": {
        "captions": {
          "description": "Caption and subtitle tracks when available.",
          "items": {
            "description": "A caption or subtitle track available for the video.",
            "properties": {
              "isTranslatable": {
                "description": "Whether the track can be translated in the player.",
                "type": "boolean"
              },
              "kind": {
                "description": "Caption kind when available.",
                "nullable": true,
                "type": "string"
              },
              "label": {
                "description": "Caption track label.",
                "type": "string"
              },
              "languageCode": {
                "description": "BCP-47 style language code when available.",
                "type": "string"
              }
            },
            "required": [
              "label",
              "languageCode",
              "kind",
              "isTranslatable"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "channel": {
          "description": "Uploader channel when found.",
          "nullable": true,
          "properties": {
            "displayName": {
              "description": "Public display name for the YouTube channel.",
              "nullable": true,
              "type": "string"
            },
            "handle": {
              "description": "YouTube channel handle without a leading @.",
              "minLength": 1,
              "type": "string"
            },
            "platform": {
              "description": "Social platform for this channel.",
              "enum": [
                "youtube"
              ],
              "type": "string"
            },
            "platformUserId": {
              "description": "YouTube channel id when available.",
              "type": "string"
            },
            "profileUrl": {
              "description": "Canonical public YouTube channel URL.",
              "minLength": 1,
              "type": "string"
            }
          },
          "required": [
            "platform",
            "handle",
            "displayName",
            "profileUrl"
          ],
          "type": "object"
        },
        "chapters": {
          "description": "Chapter markers when available.",
          "items": {
            "description": "A chapter marker in the video timeline.",
            "properties": {
              "startTimeSeconds": {
                "description": "Chapter start offset in seconds.",
                "minimum": 0,
                "type": "number"
              },
              "startTimeText": {
                "description": "Human-readable chapter start time when available.",
                "nullable": true,
                "type": "string"
              },
              "title": {
                "description": "Chapter title.",
                "type": "string"
              }
            },
            "required": [
              "title",
              "startTimeText",
              "startTimeSeconds"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "lookupStatus": {
          "description": "Whether the video was resolved for this request.",
          "enum": [
            "found",
            "not_found"
          ],
          "type": "string"
        },
        "metrics": {
          "description": "Engagement metrics when found.",
          "nullable": true,
          "properties": {
            "comments": {
              "description": "Comment count when available.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            },
            "likes": {
              "description": "Like count when available.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            },
            "views": {
              "description": "View count when available.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            }
          },
          "required": [
            "views",
            "likes",
            "comments"
          ],
          "type": "object"
        },
        "relatedVideos": {
          "description": "Related videos suggested after playback when available.",
          "items": {
            "description": "A related or recommended video entry.",
            "properties": {
              "channel": {
                "description": "Uploader channel summary when available.",
                "nullable": true,
                "properties": {
                  "displayName": {
                    "description": "Related video channel title when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "handle": {
                    "description": "Related video channel handle when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "platformUserId": {
                    "description": "Related video channel id when available.",
                    "type": "string"
                  },
                  "profileUrl": {
                    "description": "Related video channel URL when available.",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "required": [
                  "displayName",
                  "handle",
                  "profileUrl"
                ],
                "type": "object"
              },
              "durationSeconds": {
                "description": "Duration in seconds when available.",
                "minimum": 0,
                "nullable": true,
                "type": "integer"
              },
              "durationText": {
                "description": "Human-readable duration label when available.",
                "nullable": true,
                "type": "string"
              },
              "id": {
                "description": "Related video id.",
                "minLength": 1,
                "type": "string"
              },
              "publishedAt": {
                "description": "Resolved publish timestamp when available.",
                "nullable": true,
                "type": "string"
              },
              "publishedTimeText": {
                "description": "Human-readable relative publish time when available.",
                "nullable": true,
                "type": "string"
              },
              "thumbnailUrl": {
                "description": "Thumbnail image URL when available.",
                "nullable": true,
                "type": "string"
              },
              "title": {
                "description": "Related video title.",
                "type": "string"
              },
              "url": {
                "description": "Canonical watch URL when available.",
                "nullable": true,
                "type": "string"
              },
              "viewCount": {
                "description": "View count when available.",
                "minimum": 0,
                "nullable": true,
                "type": "integer"
              },
              "viewCountText": {
                "description": "Human-readable view count when available.",
                "nullable": true,
                "type": "string"
              }
            },
            "required": [
              "id",
              "url",
              "title",
              "thumbnailUrl",
              "publishedAt",
              "publishedTimeText",
              "viewCount",
              "viewCountText",
              "durationSeconds",
              "durationText",
              "channel"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "video": {
          "description": "Video details when found.",
          "nullable": true,
          "properties": {
            "description": {
              "description": "Video description text when available.",
              "nullable": true,
              "type": "string"
            },
            "descriptionLinks": {
              "description": "URLs extracted from the description when available.",
              "items": {
                "minLength": 1,
                "type": "string"
              },
              "type": "array"
            },
            "durationFormatted": {
              "description": "Human-readable duration label when available.",
              "nullable": true,
              "type": "string"
            },
            "durationMs": {
              "description": "Video duration in milliseconds when available.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            },
            "genre": {
              "description": "Category or genre label when available.",
              "nullable": true,
              "type": "string"
            },
            "id": {
              "description": "YouTube video identifier.",
              "minLength": 1,
              "type": "string"
            },
            "isPaidPromotion": {
              "description": "Whether the video is marked as paid promotion.",
              "type": "boolean"
            },
            "keywords": {
              "description": "Keyword tags associated with the video when available.",
              "items": {
                "minLength": 1,
                "type": "string"
              },
              "type": "array"
            },
            "publishDateText": {
              "description": "Human-readable publish date label when available.",
              "nullable": true,
              "type": "string"
            },
            "publishedAt": {
              "description": "Publish timestamp when available.",
              "nullable": true,
              "type": "string"
            },
            "thumbnailUrl": {
              "description": "Best available thumbnail image URL.",
              "minLength": 1,
              "type": "string"
            },
            "title": {
              "description": "Video title.",
              "type": "string"
            },
            "url": {
              "description": "Canonical public YouTube URL.",
              "minLength": 1,
              "type": "string"
            }
          },
          "required": [
            "id",
            "url",
            "title",
            "description",
            "descriptionLinks",
            "thumbnailUrl",
            "publishedAt",
            "publishDateText",
            "durationMs",
            "durationFormatted",
            "genre",
            "keywords",
            "isPaidPromotion"
          ],
          "type": "object"
        }
      },
      "required": [
        "lookupStatus",
        "video",
        "channel",
        "metrics",
        "chapters",
        "captions",
        "relatedVideos"
      ],
      "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"
}