{ "openapi": "3.1.0", "info": { "title": "Vid0 API", "version": "1.0.0", "summary": "YouTube creator intelligence: outlier videos, channel baselines, keyword odds and best times to post.", "description": "Read-only REST API for Vid0 (vid0.in). Authenticate with an API token (`yti_…`) created in Vid0 under Settings → API tokens, sent as `Authorization: Bearer `. Errors are JSON `{ error: { code, message, requestId } }`. Numbers Vid0 computes (outlier multiples, expected views, scores) are estimates, not YouTube data. Requests that need YouTube data share a daily YouTube API quota and return 429 `quota_exhausted` when it runs out.", "termsOfService": "https://vid0.in/terms", "contact": { "name": "Vid0 support", "email": "support@vid0.in", "url": "https://vid0.in/contact" }, "license": { "name": "Proprietary", "url": "https://vid0.in/terms" } }, "externalDocs": { "description": "Developer docs", "url": "https://vid0.in/developers" }, "servers": [ { "url": "https://api.vid0.in", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Status", "description": "Service health." }, { "name": "Account", "description": "The token's user, workspace, plan and quota." }, { "name": "Videos", "description": "One video against its channel's baseline." }, { "name": "Channels", "description": "Channel stats, outliers and posting times." }, { "name": "Research", "description": "Outlier discovery and keyword research." } ], "paths": { "/health": { "get": { "operationId": "getHealth", "summary": "Check the API status", "description": "Whether the Vid0 API is up and which integrations are configured. Needs no token.", "tags": [ "Status" ], "security": [], "responses": { "200": { "description": "The API is up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } } } }, "/v1/me": { "get": { "operationId": "getMe", "summary": "Get the signed-in user, workspace and plan", "description": "The user and workspace the API token belongs to, including the workspace kind (creator or brand) and plan. Call this first to check a token works.", "tags": [ "Account" ], "responses": { "200": { "description": "The token's user and workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "$ref": "#/components/responses/Error401" } } } }, "/v1/quota": { "get": { "operationId": "getQuota", "summary": "Get today's YouTube API quota", "description": "How much of today's YouTube Data API quota each bucket has used. Requests that need YouTube data fail with 429 once it runs out.", "tags": [ "Account" ], "responses": { "200": { "description": "Quota buckets for today (Pacific time, as YouTube counts it).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaStatus" } } } }, "401": { "$ref": "#/components/responses/Error401" } } } }, "/v1/videos/{id}/insights": { "get": { "operationId": "getVideoInsights", "summary": "Analyse one video against its channel's baseline", "description": "Compares a YouTube video with its own channel's typical video at the same age: outlier multiple (× typical views), expected views, views per hour and engagement. Derived numbers are Vid0 estimates, not YouTube data.", "tags": [ "Videos" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The 11-character YouTube video id, as in youtube.com/watch?v=.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{11}$" }, "example": "dQw4w9WgXcQ" } ], "responses": { "200": { "description": "The video's stats and its score against the channel baseline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoInsights" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/v1/channels/{ref}": { "get": { "operationId": "getChannel", "summary": "Get a channel's stats, top outliers and latest uploads", "description": "Public statistics for a YouTube channel, its typical views, the uploads that beat that baseline the most, and its latest uploads.", "tags": [ "Channels" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "The channel: an @handle, a UC… channel id, or a channel URL. URL-encode it (an @ becomes %40).", "schema": { "type": "string", "minLength": 2, "maxLength": 200 }, "example": "@mkbhd" } ], "responses": { "200": { "description": "The channel overview.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelOverview" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/v1/channels/{ref}/best-time": { "get": { "operationId": "getChannelBestTime", "summary": "Find the best weekdays and hours a channel posts", "description": "Which weekdays and hours a channel's public uploads did best, judged by how each upload did against the channel's typical video.", "tags": [ "Channels" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "The channel: an @handle, a UC… channel id, or a channel URL. URL-encode it (an @ becomes %40).", "schema": { "type": "string", "minLength": 2, "maxLength": 200 }, "example": "@mkbhd" } ], "responses": { "200": { "description": "Weekday and hour buckets with the best slot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BestTime" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/v1/outliers": { "get": { "operationId": "listOutliers", "summary": "List videos beating their channel's baseline", "description": "Recent videos from the given channels (or the workspace's tracked competitors) that got at least minScore × their channel's typical views at the same age, best first.", "tags": [ "Research" ], "parameters": [ { "name": "channels", "in": "query", "required": false, "description": "Comma-separated UC… channel ids. Defaults to the workspace's tracked competitors.", "schema": { "type": "string", "maxLength": 2000 } }, { "name": "format", "in": "query", "required": false, "description": "Long-form videos, Shorts, or both.", "schema": { "default": "all", "type": "string", "enum": [ "long", "short", "all" ] } }, { "name": "minScore", "in": "query", "required": false, "description": "Minimum outlier multiple (× the channel's typical views at the same age).", "schema": { "default": 2, "type": "number", "minimum": 0 }, "example": 3 }, { "name": "maxAgeDays", "in": "query", "required": false, "description": "Only videos published in the last this-many days.", "schema": { "default": 90, "type": "integer", "minimum": 1, "maximum": 365 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of videos to return.", "schema": { "default": 60, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Outlier videos, highest multiple first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutliersResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/v1/keywords": { "get": { "operationId": "getKeywordReport", "summary": "Score a keyword's competition, demand and opportunity", "description": "Competition, demand and overall opportunity scores (0–100) for a YouTube search term, with the videos ranking for it. Pass mySubs to also get how winnable it is for a channel of that size. Uses one keyword lookup from the workspace's plan.", "tags": [ "Research" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "The search term, 2–100 characters.", "schema": { "type": "string", "minLength": 2, "maxLength": 100 }, "example": "home espresso" }, { "name": "mySubs", "in": "query", "required": false, "description": "Your channel's subscriber count; adds the \"winnable for you\" score.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "example": 12000 } ], "responses": { "200": { "description": "The keyword report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordReport" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "yti_…", "description": "A Vid0 API token from Settings → API tokens." } }, "schemas": { "Health": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "version": { "type": "string" }, "youtubeConfigured": { "type": "boolean" }, "anthropicConfigured": { "type": "boolean" }, "aiConfigured": { "type": "boolean" }, "aiProvider": { "anyOf": [ { "type": "string", "enum": [ "anthropic", "nebius" ] }, { "type": "null" } ] }, "authMode": { "type": "string", "enum": [ "local", "google" ] }, "googleOAuthConfigured": { "type": "boolean" } }, "required": [ "ok", "version", "youtubeConfigured", "anthropicConfigured", "authMode", "googleOAuthConfigured" ], "additionalProperties": false }, "Me": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "avatarUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "email", "name", "avatarUrl" ], "additionalProperties": false }, "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "plan": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "member" ] }, "kind": { "default": null, "anyOf": [ { "type": "string", "enum": [ "creator", "brand" ] }, { "type": "null" } ] } }, "required": [ "id", "name", "plan", "role", "kind" ], "additionalProperties": false }, "workspaces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "plan": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "member" ] }, "kind": { "default": null, "anyOf": [ { "type": "string", "enum": [ "creator", "brand" ] }, { "type": "null" } ] } }, "required": [ "id", "name", "plan", "role", "kind" ], "additionalProperties": false } }, "authMode": { "type": "string", "enum": [ "local", "google" ] }, "via": { "type": "string", "enum": [ "local", "session", "token" ] }, "googleOAuthConfigured": { "type": "boolean" } }, "required": [ "user", "workspace", "workspaces", "authMode", "via", "googleOAuthConfigured" ], "additionalProperties": false }, "QuotaStatus": { "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "used": { "type": "number" }, "limit": { "type": "number" }, "unit": { "type": "string", "enum": [ "units", "calls" ] }, "resetsAt": { "type": "string" } }, "required": [ "name", "used", "limit", "unit", "resetsAt" ], "additionalProperties": false } } }, "required": [ "buckets" ], "additionalProperties": false }, "VideoInsights": { "type": "object", "properties": { "video": { "type": "object", "properties": { "id": { "type": "string" }, "channelId": { "type": "string" }, "channelTitle": { "type": "string" }, "title": { "type": "string" }, "publishedAt": { "type": "string" }, "durationSec": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "format": { "type": "string", "enum": [ "long", "short" ] }, "views": { "type": [ "number", "null" ] }, "likes": { "type": [ "number", "null" ] }, "comments": { "type": [ "number", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "hasPaidPromotion": { "type": [ "boolean", "null" ] }, "liveStatus": { "anyOf": [ { "type": "string", "enum": [ "upcoming", "live", "completed" ] }, { "type": "null" } ] }, "ageHours": { "type": "number" }, "vphAvg": { "type": [ "number", "null" ] }, "vphLive": { "type": [ "number", "null" ] }, "outlier": { "type": [ "number", "null" ] }, "expectedViews": { "type": [ "number", "null" ] }, "outlierInfo": { "type": "object", "properties": { "status": { "type": "string" }, "peers": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "band": { "anyOf": [ { "type": "object", "properties": { "low": { "type": "number" }, "high": { "type": "number" } }, "required": [ "low", "high" ], "additionalProperties": false }, { "type": "null" } ] }, "p90": { "type": [ "number", "null" ] }, "confidence": { "anyOf": [ { "type": "string", "enum": [ "low", "medium", "high" ] }, { "type": "null" } ] } }, "required": [ "status", "peers", "band", "p90", "confidence" ], "additionalProperties": false } }, "required": [ "id", "channelId", "channelTitle", "title", "publishedAt", "durationSec", "format", "views", "likes", "comments", "thumbnailUrl", "tags", "hasPaidPromotion", "ageHours", "vphAvg", "vphLive", "outlier", "expectedViews" ], "additionalProperties": false }, "channel": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "handle": { "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "subscribers": { "type": [ "number", "null" ] }, "views": { "type": [ "number", "null" ] }, "videoCount": { "type": [ "number", "null" ] }, "uploadsPlaylistId": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "publishedAt": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "handle", "thumbnailUrl", "subscribers", "views", "videoCount", "uploadsPlaylistId", "country", "publishedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "metrics": { "type": "object", "properties": { "vphAvg": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "method": { "type": "string" }, "inputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "number", "string", "boolean", "null" ] } }, "note": { "type": "string" } }, "required": [ "value", "method", "inputs" ], "additionalProperties": false }, "vphLive": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "method": { "type": "string" }, "inputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "number", "string", "boolean", "null" ] } }, "note": { "type": "string" } }, "required": [ "value", "method", "inputs" ], "additionalProperties": false }, "engagementRate": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "method": { "type": "string" }, "inputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "number", "string", "boolean", "null" ] } }, "note": { "type": "string" } }, "required": [ "value", "method", "inputs" ], "additionalProperties": false }, "outlier": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "method": { "type": "string" }, "inputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "number", "string", "boolean", "null" ] } }, "note": { "type": "string" } }, "required": [ "value", "method", "inputs" ], "additionalProperties": false } }, "required": [ "vphAvg", "vphLive", "engagementRate", "outlier" ], "additionalProperties": false }, "baseline": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "long", "short" ] }, "peers": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "medianViews": { "type": [ "number", "null" ] } }, "required": [ "format", "peers", "medianViews" ], "additionalProperties": false }, "trajectory": { "type": "object", "properties": { "typical": { "type": "array", "items": { "type": "object", "properties": { "ageHours": { "type": "number" }, "views": { "type": "number" } }, "required": [ "ageHours", "views" ], "additionalProperties": false } }, "recorded": { "type": "array", "items": { "type": "object", "properties": { "ageHours": { "type": "number" }, "views": { "type": "number" } }, "required": [ "ageHours", "views" ], "additionalProperties": false } } }, "required": [ "typical", "recorded" ], "additionalProperties": false }, "label": { "type": "string", "const": "Vid0 estimate, not YouTube data" }, "fetchedAt": { "type": "string" } }, "required": [ "video", "channel", "metrics", "baseline", "label", "fetchedAt" ], "additionalProperties": false }, "ChannelOverview": { "type": "object", "properties": { "channel": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "handle": { "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "subscribers": { "type": [ "number", "null" ] }, "views": { "type": [ "number", "null" ] }, "videoCount": { "type": [ "number", "null" ] }, "uploadsPlaylistId": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "publishedAt": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "handle", "thumbnailUrl", "subscribers", "views", "videoCount", "uploadsPlaylistId", "country", "publishedAt" ], "additionalProperties": false }, "stats": { "type": "object", "properties": { "sampleSize": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "medianViewsLong": { "type": [ "number", "null" ] }, "medianViewsShort": { "type": [ "number", "null" ] }, "uploadsPerWeek": { "type": [ "number", "null" ] }, "outlierRate": { "type": [ "number", "null" ] }, "shortShare": { "type": [ "number", "null" ] } }, "required": [ "sampleSize", "medianViewsLong", "medianViewsShort", "uploadsPerWeek", "outlierRate", "shortShare" ], "additionalProperties": false }, "recent": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "channelId": { "type": "string" }, "channelTitle": { "type": "string" }, "title": { "type": "string" }, "publishedAt": { "type": "string" }, "durationSec": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "format": { "type": "string", "enum": [ "long", "short" ] }, "views": { "type": [ "number", "null" ] }, "likes": { "type": [ "number", "null" ] }, "comments": { "type": [ "number", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "hasPaidPromotion": { "type": [ "boolean", "null" ] }, "liveStatus": { "anyOf": [ { "type": "string", "enum": [ "upcoming", "live", "completed" ] }, { "type": "null" } ] }, "ageHours": { "type": "number" }, "vphAvg": { "type": [ "number", "null" ] }, "vphLive": { "type": [ "number", "null" ] }, "outlier": { "type": [ "number", "null" ] }, "expectedViews": { "type": [ "number", "null" ] }, "outlierInfo": { "type": "object", "properties": { "status": { "type": "string" }, "peers": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "band": { "anyOf": [ { "type": "object", "properties": { "low": { "type": "number" }, "high": { "type": "number" } }, "required": [ "low", "high" ], "additionalProperties": false }, { "type": "null" } ] }, "p90": { "type": [ "number", "null" ] }, "confidence": { "anyOf": [ { "type": "string", "enum": [ "low", "medium", "high" ] }, { "type": "null" } ] } }, "required": [ "status", "peers", "band", "p90", "confidence" ], "additionalProperties": false } }, "required": [ "id", "channelId", "channelTitle", "title", "publishedAt", "durationSec", "format", "views", "likes", "comments", "thumbnailUrl", "tags", "hasPaidPromotion", "ageHours", "vphAvg", "vphLive", "outlier", "expectedViews" ], "additionalProperties": false } }, "topOutliers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "channelId": { "type": "string" }, "channelTitle": { "type": "string" }, "title": { "type": "string" }, "publishedAt": { "type": "string" }, "durationSec": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "format": { "type": "string", "enum": [ "long", "short" ] }, "views": { "type": [ "number", "null" ] }, "likes": { "type": [ "number", "null" ] }, "comments": { "type": [ "number", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "hasPaidPromotion": { "type": [ "boolean", "null" ] }, "liveStatus": { "anyOf": [ { "type": "string", "enum": [ "upcoming", "live", "completed" ] }, { "type": "null" } ] }, "ageHours": { "type": "number" }, "vphAvg": { "type": [ "number", "null" ] }, "vphLive": { "type": [ "number", "null" ] }, "outlier": { "type": [ "number", "null" ] }, "expectedViews": { "type": [ "number", "null" ] }, "outlierInfo": { "type": "object", "properties": { "status": { "type": "string" }, "peers": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "band": { "anyOf": [ { "type": "object", "properties": { "low": { "type": "number" }, "high": { "type": "number" } }, "required": [ "low", "high" ], "additionalProperties": false }, { "type": "null" } ] }, "p90": { "type": [ "number", "null" ] }, "confidence": { "anyOf": [ { "type": "string", "enum": [ "low", "medium", "high" ] }, { "type": "null" } ] } }, "required": [ "status", "peers", "band", "p90", "confidence" ], "additionalProperties": false } }, "required": [ "id", "channelId", "channelTitle", "title", "publishedAt", "durationSec", "format", "views", "likes", "comments", "thumbnailUrl", "tags", "hasPaidPromotion", "ageHours", "vphAvg", "vphLive", "outlier", "expectedViews" ], "additionalProperties": false } }, "label": { "type": "string", "const": "Vid0 estimate, not YouTube data" }, "fetchedAt": { "type": "string" } }, "required": [ "channel", "stats", "recent", "topOutliers", "label", "fetchedAt" ], "additionalProperties": false }, "BestTime": { "type": "object", "properties": { "channelId": { "type": "string" }, "timezone": { "type": "string" }, "timezoneSource": { "type": "string", "enum": [ "channel_country", "utc" ] }, "sampleSize": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "byWeekday": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "type": "string" }, "uploads": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "medianOutlier": { "type": [ "number", "null" ] } }, "required": [ "key", "label", "uploads", "medianOutlier" ], "additionalProperties": false } }, "byHour": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "type": "string" }, "uploads": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "medianOutlier": { "type": [ "number", "null" ] } }, "required": [ "key", "label", "uploads", "medianOutlier" ], "additionalProperties": false } }, "top": { "type": "array", "items": { "type": "object", "properties": { "weekday": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hourStart": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hourEnd": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "type": "string" }, "uploads": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "medianOutlier": { "type": "number" }, "low": { "type": "number" }, "high": { "type": "number" } }, "required": [ "weekday", "hourStart", "hourEnd", "label", "uploads", "medianOutlier" ], "additionalProperties": false } }, "method": { "type": "string" }, "note": { "type": "string" }, "heuristic": { "type": "boolean", "const": true }, "format": { "type": "string", "enum": [ "long", "short" ] }, "verdict": { "type": "string" }, "formats": { "type": "array", "items": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "long", "short" ] }, "sampleSize": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "verdict": { "type": "string" }, "top": { "type": "array", "items": { "type": "object", "properties": { "weekday": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hourStart": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hourEnd": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "type": "string" }, "uploads": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "medianOutlier": { "type": "number" }, "low": { "type": "number" }, "high": { "type": "number" } }, "required": [ "weekday", "hourStart", "hourEnd", "label", "uploads", "medianOutlier" ], "additionalProperties": false } } }, "required": [ "format", "sampleSize", "verdict", "top" ], "additionalProperties": false } }, "label": { "type": "string", "const": "Vid0 estimate, not YouTube data" } }, "required": [ "channelId", "timezone", "timezoneSource", "sampleSize", "byWeekday", "byHour", "top", "method", "note", "heuristic", "label" ], "additionalProperties": false }, "OutliersResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "channelId": { "type": "string" }, "channelTitle": { "type": "string" }, "title": { "type": "string" }, "publishedAt": { "type": "string" }, "durationSec": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "format": { "type": "string", "enum": [ "long", "short" ] }, "views": { "type": [ "number", "null" ] }, "likes": { "type": [ "number", "null" ] }, "comments": { "type": [ "number", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "hasPaidPromotion": { "type": [ "boolean", "null" ] }, "liveStatus": { "anyOf": [ { "type": "string", "enum": [ "upcoming", "live", "completed" ] }, { "type": "null" } ] }, "ageHours": { "type": "number" }, "vphAvg": { "type": [ "number", "null" ] }, "vphLive": { "type": [ "number", "null" ] }, "outlier": { "type": [ "number", "null" ] }, "expectedViews": { "type": [ "number", "null" ] }, "outlierInfo": { "type": "object", "properties": { "status": { "type": "string" }, "peers": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "band": { "anyOf": [ { "type": "object", "properties": { "low": { "type": "number" }, "high": { "type": "number" } }, "required": [ "low", "high" ], "additionalProperties": false }, { "type": "null" } ] }, "p90": { "type": [ "number", "null" ] }, "confidence": { "anyOf": [ { "type": "string", "enum": [ "low", "medium", "high" ] }, { "type": "null" } ] } }, "required": [ "status", "peers", "band", "p90", "confidence" ], "additionalProperties": false }, "channelSubscribers": { "type": [ "number", "null" ] } }, "required": [ "id", "channelId", "channelTitle", "title", "publishedAt", "durationSec", "format", "views", "likes", "comments", "thumbnailUrl", "tags", "hasPaidPromotion", "ageHours", "vphAvg", "vphLive", "outlier", "expectedViews", "channelSubscribers" ], "additionalProperties": false } }, "channels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "handle": { "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "subscribers": { "type": [ "number", "null" ] }, "views": { "type": [ "number", "null" ] }, "videoCount": { "type": [ "number", "null" ] }, "uploadsPlaylistId": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "publishedAt": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "handle", "thumbnailUrl", "subscribers", "views", "videoCount", "uploadsPlaylistId", "country", "publishedAt" ], "additionalProperties": false } }, "params": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "long", "short", "all" ] }, "minScore": { "type": "number" }, "maxAgeDays": { "type": "number" }, "limit": { "type": "number" } }, "required": [ "format", "minScore", "maxAgeDays", "limit" ], "additionalProperties": false }, "label": { "type": "string", "const": "Vid0 estimate, not YouTube data" }, "fetchedAt": { "type": "string" } }, "required": [ "items", "channels", "params", "label", "fetchedAt" ], "additionalProperties": false }, "KeywordReport": { "type": "object", "properties": { "term": { "type": "string" }, "cached": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "video": { "type": "object", "properties": { "id": { "type": "string" }, "channelId": { "type": "string" }, "channelTitle": { "type": "string" }, "title": { "type": "string" }, "publishedAt": { "type": "string" }, "durationSec": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "format": { "type": "string", "enum": [ "long", "short" ] }, "views": { "type": [ "number", "null" ] }, "likes": { "type": [ "number", "null" ] }, "comments": { "type": [ "number", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "hasPaidPromotion": { "type": [ "boolean", "null" ] }, "liveStatus": { "anyOf": [ { "type": "string", "enum": [ "upcoming", "live", "completed" ] }, { "type": "null" } ] }, "ageHours": { "type": "number" }, "vphAvg": { "type": [ "number", "null" ] }, "vphLive": { "type": [ "number", "null" ] }, "outlier": { "type": [ "number", "null" ] }, "expectedViews": { "type": [ "number", "null" ] }, "outlierInfo": { "type": "object", "properties": { "status": { "type": "string" }, "peers": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "band": { "anyOf": [ { "type": "object", "properties": { "low": { "type": "number" }, "high": { "type": "number" } }, "required": [ "low", "high" ], "additionalProperties": false }, { "type": "null" } ] }, "p90": { "type": [ "number", "null" ] }, "confidence": { "anyOf": [ { "type": "string", "enum": [ "low", "medium", "high" ] }, { "type": "null" } ] } }, "required": [ "status", "peers", "band", "p90", "confidence" ], "additionalProperties": false } }, "required": [ "id", "channelId", "channelTitle", "title", "publishedAt", "durationSec", "format", "views", "likes", "comments", "thumbnailUrl", "tags", "hasPaidPromotion", "ageHours", "vphAvg", "vphLive", "outlier", "expectedViews" ], "additionalProperties": false }, "channel": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "subscribers": { "type": [ "number", "null" ] } }, "required": [ "id", "title", "subscribers" ], "additionalProperties": false } }, "required": [ "rank", "video", "channel" ], "additionalProperties": false } }, "scores": { "type": "object", "properties": { "competition": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "method": { "type": "string" }, "inputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "number", "string", "boolean", "null" ] } }, "note": { "type": "string" } }, "required": [ "value", "method", "inputs" ], "additionalProperties": false }, "winnable": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "method": { "type": "string" }, "inputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "number", "string", "boolean", "null" ] } }, "note": { "type": "string" } }, "required": [ "value", "method", "inputs" ], "additionalProperties": false }, "demandProxy": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "method": { "type": "string" }, "inputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "number", "string", "boolean", "null" ] } }, "note": { "type": "string" } }, "required": [ "value", "method", "inputs" ], "additionalProperties": false }, "opportunity": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "method": { "type": "string" }, "inputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "number", "string", "boolean", "null" ] } }, "note": { "type": "string" } }, "required": [ "value", "method", "inputs" ], "additionalProperties": false } }, "required": [ "competition", "winnable", "demandProxy", "opportunity" ], "additionalProperties": false }, "label": { "type": "string", "const": "Vid0 estimate, not YouTube data" }, "fetchedAt": { "type": "string" } }, "required": [ "term", "cached", "results", "scores", "label", "fetchedAt" ], "additionalProperties": false }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "limit_reached", "not_configured", "conflict", "not_found", "youtube_not_configured", "anthropic_not_configured", "quota_exhausted", "upstream_error", "ai_refused", "internal" ], "description": "Machine-readable error code." }, "message": { "type": "string", "description": "What went wrong, in plain words." }, "requestId": { "type": "string", "description": "Quote this when contacting support." } } } } } }, "responses": { "Error400": { "description": "Invalid parameters (`bad_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error401": { "description": "Missing, invalid or revoked API token (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error402": { "description": "The workspace's plan limit for this feature is used up (`limit_reached`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error403": { "description": "The token's workspace kind (creator or brand) can't use this route (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error404": { "description": "Unknown video or channel (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error429": { "description": "Today's YouTube API quota is used up, or too many requests (`quota_exhausted`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }