{ "components": { "schemas": { "ErrorBody": { "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" } }, "required": [ "error" ], "type": "object" }, "ErrorDetail": { "properties": { "code": { "description": "Machine-readable error code (see the error codes list).", "enum": [ "invalid_input", "invalid_cursor", "unauthorized", "insufficient_credits", "rate_limited", "method_not_allowed", "not_found", "private_or_unavailable", "no_transcript", "upstream_blocked", "upstream_error", "overloaded", "internal" ], "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ], "type": "object" }, "FacebookTranscriptResponse": { "properties": { "data": { "$ref": "#/components/schemas/Transcript" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "InstagramTranscriptResponse": { "properties": { "data": { "$ref": "#/components/schemas/Transcript" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "ResponseMeta": { "properties": { "credits_charged": { "description": "Credits charged for this request (0 for errors and cache hits).", "format": "int64", "type": "integer" }, "fetched_at": { "description": "When the data was fetched from the platform, RFC 3339 UTC (older than the request for cache hits).", "format": "date-time", "type": "string" }, "is_cached": { "description": "True when served from the cache (free); see max_age.", "type": "boolean" }, "latency_ms": { "description": "Time SocialTap spent on the request, in milliseconds.", "format": "int64", "type": "integer" }, "platform": { "description": "Platform ID of the endpoint (youtube, tiktok, …).", "examples": [ "youtube" ], "type": "string" }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "source": { "description": "Which upstream strategy produced the data.", "examples": [ "captions" ], "type": "string" } }, "required": [ "request_id", "platform", "source", "is_cached", "credits_charged", "latency_ms", "fetched_at" ], "type": "object" }, "Segment": { "properties": { "end_ms": { "description": "End time in milliseconds from the beginning of the media.", "format": "int64", "type": "integer" }, "start_ms": { "description": "Start time in milliseconds from the beginning of the media.", "format": "int64", "type": "integer" }, "text": { "description": "Cue text, whitespace-normalized.", "type": "string" } }, "required": [ "start_ms", "end_ms", "text" ], "type": "object" }, "TiktokTranscriptResponse": { "properties": { "data": { "$ref": "#/components/schemas/Transcript" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "Transcript": { "properties": { "available_languages": { "description": "BCP-47 caption languages the platform offers for this post; [] if none or not listed.", "items": { "type": "string" }, "type": "array" }, "duration_ms": { "description": "Media duration in milliseconds; null when unknown.", "format": "int64", "type": [ "integer", "null" ] }, "id": { "description": "Platform-native ID of the post (equals post.id).", "type": "string" }, "is_auto_generated": { "description": "True when the track was machine-generated (platform auto-captions or ASR).", "type": "boolean" }, "language": { "description": "BCP-47 language of the returned transcript; null when unknown.", "examples": [ "en" ], "type": [ "string", "null" ] }, "platform": { "description": "Platform the media is hosted on.", "examples": [ "youtube" ], "type": "string" }, "segments": { "description": "Timed cues in order; never empty on success.", "items": { "$ref": "#/components/schemas/Segment" }, "type": "array" }, "source": { "description": "captions = platform caption track; asr = speech-to-text on the audio.", "enum": [ "captions", "asr" ], "type": "string" }, "text": { "description": "Full transcript: segment texts joined with single spaces.", "type": "string" }, "url": { "description": "Canonical URL of the post.", "format": "uri", "type": "string" } }, "required": [ "platform", "id", "url", "language", "source", "is_auto_generated", "available_languages", "duration_ms", "segments", "text" ], "type": "object" }, "YoutubeTranscriptResponse": { "properties": { "data": { "$ref": "#/components/schemas/Transcript" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" } }, "securitySchemes": { "apiKey": { "in": "header", "name": "x-api-key", "type": "apiKey" } } }, "info": { "description": "SocialTap returns public social media data (transcripts today; profiles, posts and comments next) from every major platform through one API key, one credit balance and one response schema per resource. Failed requests and cache hits are free. Docs: https://staging.socialtap.dev/docs", "title": "SocialTap API", "version": "1" }, "openapi": "3.1.0", "paths": { "/status.json": { "get": { "description": "Public, no API key. `status` is health from the scheduled canaries: an endpoint is degraded after repeated failed runs and healthy again after several passes; unknown until first checked. `success_rate` is the share of real requests in the last `success_rate_window_minutes` that got an answer (upstream failures count against it), rounded down; null when there was too little traffic. Cached for 60 seconds.", "operationId": "live-status", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "endpoints": { "items": { "properties": { "id": { "type": "string" }, "last_checked": { "format": "date-time", "type": [ "string", "null" ] }, "since": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "enum": [ "healthy", "degraded", "unknown" ], "type": "string" }, "success_rate": { "description": "Real-traffic success rate over the window (0..1, rounded down); null when there was too little traffic.", "maximum": 1, "minimum": 0, "type": [ "number", "null" ] } }, "required": [ "id", "status", "since", "last_checked" ], "type": "object" }, "type": "array" }, "environment": { "type": "string" }, "generated_at": { "format": "date-time", "type": "string" }, "success_rate_window_minutes": { "description": "Window of every endpoint's success_rate.", "type": "integer" } }, "required": [ "generated_at", "environment", "endpoints" ], "type": "object" } } }, "description": "Health document" } }, "security": [], "summary": "Live health of every endpoint", "tags": [ "Status" ] } }, "/v1/billing/checkout": { "post": { "description": "Creates a Stripe Checkout session for a credit pack; open the returned url to pay. Credits are added when payment completes.", "operationId": "billing-checkout", "requestBody": { "content": { "application/json": { "schema": { "properties": { "pack": { "description": "Pack ID.", "enum": [ "25k", "100k", "500k", "2m" ], "type": "string" } }, "required": [ "pack" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } } }, "description": "Checkout session" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "invalid_input" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "unauthorized" } }, "summary": "Buy a credit pack (Stripe Checkout)", "tags": [ "Billing" ] } }, "/v1/facebook/transcript": { "get": { "description": "Returns the timed transcript of a public Facebook video or reel: the uploaded or auto-generated caption track when Facebook has one, otherwise speech-to-text on the video's audio. Accepts reel, watch, page video, video.php, fb.watch and share links, or a numeric video ID.\n\n**Pricing:** 1 credit (captions) · 2 credits + 2 per started minute of media (asr). Failed requests and cache hits are free.", "operationId": "facebook-transcript", "parameters": [ { "description": "Facebook video URL (reel, watch, page video, video.php, m./mbasic./web. hosts, fb.watch and share/v|r links) or a numeric video ID.", "example": "https://www.facebook.com/reel/1803909017420449", "in": "query", "name": "url", "required": true, "schema": { "description": "Facebook video URL (reel, watch, page video, video.php, m./mbasic./web. hosts, fb.watch and share/v|r links) or a numeric video ID.", "examples": [ "https://www.facebook.com/reel/1803909017420449" ], "maxLength": 2048, "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookTranscriptResponse" } } }, "description": "OK", "headers": { "age": { "description": "Seconds since the data was fetched (cache hits only).", "schema": { "type": "integer" } }, "allow": { "description": "Methods the endpoint accepts (method_not_allowed only).", "schema": { "type": "string" } }, "x-credits-charged": { "description": "Credits charged for this request (0 for errors and cache hits).", "schema": { "type": "integer" } }, "x-credits-remaining": { "description": "Account balance after this request.", "schema": { "type": "integer" } }, "x-request-id": { "description": "Unique request ID; include it when contacting support.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "invalid_input" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "unauthorized" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "insufficient_credits" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "private_or_unavailable" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "not_found / no_transcript" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "rate_limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "internal" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "upstream_error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "upstream_blocked / overloaded" } }, "summary": "Facebook video transcript", "tags": [ "Facebook" ] } }, "/v1/instagram/transcript": { "get": { "description": "Returns the timed transcript of a public Instagram reel or video post. Instagram rarely exposes caption tracks to logged-out clients, so most transcripts are speech-to-text on the post's audio. Accepts reel, post, tv, instagr.am and share links or a raw shortcode; for carousels, img_index selects the item.\n\n**Pricing:** 1 credit (captions) · 2 credits + 2 per started minute of media (asr). Failed requests and cache hits are free.", "operationId": "instagram-transcript", "parameters": [ { "description": "Instagram reel/post URL (instagram.com/reel/…, /reels/…, /p/…, /tv/…, instagr.am, instagram.com/share/… links) or a raw shortcode. For carousel posts, ?img_index=N selects the item; default is the first video.", "example": "https://www.instagram.com/reel/De1S3KpCXf0/", "in": "query", "name": "url", "required": true, "schema": { "description": "Instagram reel/post URL (instagram.com/reel/…, /reels/…, /p/…, /tv/…, instagr.am, instagram.com/share/… links) or a raw shortcode. For carousel posts, ?img_index=N selects the item; default is the first video.", "examples": [ "https://www.instagram.com/reel/De1S3KpCXf0/" ], "maxLength": 2048, "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstagramTranscriptResponse" } } }, "description": "OK", "headers": { "age": { "description": "Seconds since the data was fetched (cache hits only).", "schema": { "type": "integer" } }, "allow": { "description": "Methods the endpoint accepts (method_not_allowed only).", "schema": { "type": "string" } }, "x-credits-charged": { "description": "Credits charged for this request (0 for errors and cache hits).", "schema": { "type": "integer" } }, "x-credits-remaining": { "description": "Account balance after this request.", "schema": { "type": "integer" } }, "x-request-id": { "description": "Unique request ID; include it when contacting support.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "invalid_input" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "unauthorized" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "insufficient_credits" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "private_or_unavailable" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "not_found / no_transcript" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "rate_limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "internal" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "upstream_error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "upstream_blocked / overloaded" } }, "summary": "Instagram reel / video transcript", "tags": [ "Instagram" ] } }, "/v1/tiktok/transcript": { "get": { "description": "Returns the timed transcript of a public TikTok video: creator-edited captions, TikTok's auto-captions, or TikTok's own translation when you ask for another language with lang. Videos without any caption track are transcribed from their audio with speech-to-text. Accepts tiktok.com video, mobile, embed and vm./vt./t/ share links, or a numeric video ID.\n\n**Pricing:** 1 credit (captions) · 2 credits + 2 per started minute of media (asr). Failed requests and cache hits are free.", "operationId": "tiktok-transcript", "parameters": [ { "description": "TikTok video URL (tiktok.com/@user/video/, m.tiktok.com/v/.html, vm.tiktok.com/, vt.tiktok.com/, tiktok.com/t/, embed URLs) or a numeric video ID.", "example": "https://www.tiktok.com/@scout2015/video/6718335390845095173", "in": "query", "name": "url", "required": true, "schema": { "description": "TikTok video URL (tiktok.com/@user/video/, m.tiktok.com/v/.html, vm.tiktok.com/, vt.tiktok.com/, tiktok.com/t/, embed URLs) or a numeric video ID.", "examples": [ "https://www.tiktok.com/@scout2015/video/6718335390845095173" ], "maxLength": 2048, "type": "string" } }, { "description": "Preferred caption language (e.g. en, eng-US, fr). Falls back to the video's original language, then any track.", "example": "en", "in": "query", "name": "lang", "schema": { "description": "Preferred caption language (e.g. en, eng-US, fr). Falls back to the video's original language, then any track.", "examples": [ "en" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TiktokTranscriptResponse" } } }, "description": "OK", "headers": { "age": { "description": "Seconds since the data was fetched (cache hits only).", "schema": { "type": "integer" } }, "allow": { "description": "Methods the endpoint accepts (method_not_allowed only).", "schema": { "type": "string" } }, "x-credits-charged": { "description": "Credits charged for this request (0 for errors and cache hits).", "schema": { "type": "integer" } }, "x-credits-remaining": { "description": "Account balance after this request.", "schema": { "type": "integer" } }, "x-request-id": { "description": "Unique request ID; include it when contacting support.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "invalid_input" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "unauthorized" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "insufficient_credits" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "private_or_unavailable" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "not_found / no_transcript" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "rate_limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "internal" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "upstream_error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "upstream_blocked / overloaded" } }, "summary": "TikTok video transcript", "tags": [ "TikTok" ] } }, "/v1/youtube/transcript": { "get": { "description": "Returns the timed transcript of a public YouTube video, short or live replay: the creator's manual captions when they exist, otherwise YouTube's auto-generated track, in the language you ask for. Videos without any caption track are transcribed from their audio with speech-to-text. Accepts every YouTube URL form (watch, youtu.be, shorts, live, embed, music.) or a bare 11-character video ID.\n\n**Pricing:** 1 credit (captions) · 2 credits + 2 per started minute of media (asr). Failed requests and cache hits are free.", "operationId": "youtube-transcript", "parameters": [ { "description": "YouTube video URL (watch, youtu.be, shorts, live, embed, m./music. hosts) or an 11-character video ID.", "example": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "in": "query", "name": "url", "required": true, "schema": { "description": "YouTube video URL (watch, youtu.be, shorts, live, embed, m./music. hosts) or an 11-character video ID.", "examples": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ" ], "maxLength": 2048, "type": "string" } }, { "description": "Caption language (BCP-47, e.g. en, pt-BR). A manual track is preferred over auto-generated. Default: the video's original-language manual track, else its auto-generated track.", "example": "en", "in": "query", "name": "lang", "schema": { "description": "Caption language (BCP-47, e.g. en, pt-BR). A manual track is preferred over auto-generated. Default: the video's original-language manual track, else its auto-generated track.", "examples": [ "en" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YoutubeTranscriptResponse" } } }, "description": "OK", "headers": { "age": { "description": "Seconds since the data was fetched (cache hits only).", "schema": { "type": "integer" } }, "allow": { "description": "Methods the endpoint accepts (method_not_allowed only).", "schema": { "type": "string" } }, "x-credits-charged": { "description": "Credits charged for this request (0 for errors and cache hits).", "schema": { "type": "integer" } }, "x-credits-remaining": { "description": "Account balance after this request.", "schema": { "type": "integer" } }, "x-request-id": { "description": "Unique request ID; include it when contacting support.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "invalid_input" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "unauthorized" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "insufficient_credits" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "private_or_unavailable" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "not_found / no_transcript" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "rate_limited" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "internal" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "upstream_error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "upstream_blocked / overloaded" } }, "summary": "YouTube video transcript", "tags": [ "YouTube" ] } } }, "security": [ { "apiKey": [] } ], "servers": [ { "url": "https://staging.socialtap.dev" } ], "tags": [ { "description": "Transcripts of public Facebook videos and reels.", "name": "Facebook" }, { "description": "Transcripts of public Instagram reels and video posts.", "name": "Instagram" }, { "description": "Transcripts of public TikTok videos, from creator captions, auto-captions or the audio.", "name": "TikTok" }, { "description": "Transcripts of public YouTube videos, shorts and live replays.", "name": "YouTube" }, { "description": "Buy credit packs.", "name": "Billing" }, { "description": "Live endpoint health.", "name": "Status" } ] }