{ "openapi": "3.1.0", "info": { "title": "Bumpups API", "version": "1.0.0", "summary": "Chapters and answers for YouTube videos.", "description": "Included with the Pro plan. Minutes and chat limits are shared with the Bumpups web app: a video costs its length in whole minutes (at least 1), and each video allows 25 questions across web chat and the API. Slow work is asynchronous: POST answers 202 with a Location to poll. New fields and endpoints can appear in v1; ignore what you don't recognize." }, "servers": [ { "url": "https://bumpups.com/api/v1" } ], "security": [ { "apiKey": [] } ], "paths": { "/account": { "get": { "operationId": "getAccount", "summary": "Plan, minutes left and when they reset", "responses": { "200": { "description": "The account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/videos": { "post": { "operationId": "createVideo", "summary": "Process a YouTube video into chapters (uses minutes)", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "additionalProperties": false, "properties": { "url": { "type": "string", "description": "A YouTube video link (watch, youtu.be, shorts, live or embed)." } } } } } }, "responses": { "202": { "$ref": "#/components/responses/VideoAccepted" }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "402": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" } } } }, "/videos/{video_id}": { "parameters": [ { "$ref": "#/components/parameters/VideoId" } ], "get": { "operationId": "getVideo", "summary": "A video's status and chapters", "responses": { "200": { "description": "The video. While it's processing, Retry-After says when to check again.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Video" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" } } } }, "/videos/{video_id}/questions": { "parameters": [ { "$ref": "#/components/parameters/VideoId" } ], "post": { "operationId": "createQuestion", "summary": "Ask a question about a ready video (no minutes; counts toward the video's 25)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "question" ], "additionalProperties": false, "properties": { "question": { "type": "string", "maxLength": 2000 } } } } } }, "responses": { "202": { "description": "Accepted; poll the Location URL", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Question" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } } }, "/videos/{video_id}/questions/{question_id}": { "parameters": [ { "$ref": "#/components/parameters/VideoId" }, { "$ref": "#/components/parameters/QuestionId" } ], "get": { "operationId": "getQuestion", "summary": "A question and its answer", "responses": { "200": { "description": "The question", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Question" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An API key from the API page in Bumpups: bu_live_ followed by 40 letters and digits." } }, "parameters": { "VideoId": { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{6,64}$" } }, "QuestionId": { "name": "question_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9]{8,40}$" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retrying with the same key within 24 hours returns the same video without charging again. While the first request with the key is still running, a retry gets 409 idempotency_key_in_use.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "headers": { "Location": { "description": "Where to poll", "schema": { "type": "string" } }, "RetryAfter": { "description": "Seconds to wait before checking again", "schema": { "type": "integer" } } }, "responses": { "VideoAccepted": { "description": "Accepted; poll the Location URL", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Video" } } } }, "Problem": { "description": "An error, as RFC 9457 problem details", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "Account": { "type": "object", "required": [ "object", "plan", "minutes_limit", "minutes_used", "minutes_left", "resets_at" ], "properties": { "object": { "const": "account" }, "plan": { "type": "string" }, "minutes_limit": { "type": "integer" }, "minutes_used": { "type": "integer" }, "minutes_left": { "type": "integer", "description": "Shared with the web app" }, "resets_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Chapter": { "type": "object", "required": [ "start_seconds", "timestamp", "title" ], "properties": { "start_seconds": { "type": "integer" }, "timestamp": { "type": "string", "examples": [ "0:00", "1:02:03" ] }, "title": { "type": "string" } } }, "Error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "Video": { "type": "object", "required": [ "object", "id", "status", "youtube_id", "title", "duration_seconds", "minutes_charged", "chapters", "chapters_text", "error", "app_url", "created_at" ], "properties": { "object": { "const": "video" }, "id": { "type": "string" }, "status": { "type": "string", "enum": [ "processing", "ready", "failed" ] }, "youtube_id": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "duration_seconds": { "type": "integer" }, "minutes_charged": { "type": "integer", "description": "0 when processing failed: the minutes were refunded" }, "chapters": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Chapter" } }, "chapters_text": { "type": [ "string", "null" ], "description": "Lines like '0:00 - Intro', ready to paste into a YouTube description" }, "error": { "$ref": "#/components/schemas/Error" }, "app_url": { "type": "string", "format": "uri" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Question": { "type": "object", "required": [ "object", "id", "video_id", "status", "question", "answer", "error", "created_at" ], "properties": { "object": { "const": "question" }, "id": { "type": "string" }, "video_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "answered", "failed" ] }, "question": { "type": "string" }, "answer": { "type": [ "string", "null" ], "description": "Markdown, the same answer the web chat gives (it cites moments as m:ss)" }, "error": { "$ref": "#/components/schemas/Error" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Problem": { "type": "object", "required": [ "type", "title", "status", "detail", "code", "request_id" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "invalid_request", "invalid_url", "invalid_api_key", "not_enough_minutes", "pro_required", "not_found", "method_not_allowed", "video_not_ready", "question_in_progress", "idempotency_key_in_use", "payload_too_large", "unsupported_media_type", "video_not_supported", "idempotency_key_reused", "question_limit_reached", "internal_error", "unavailable" ] }, "request_id": { "type": "string" }, "reason": { "type": "string", "enum": [ "private", "unlisted_short", "live", "too_long", "not_found" ] }, "minutes_needed": { "type": "integer" }, "minutes_left": { "type": "integer" } } } } } }