{ "openapi": "3.1.0", "info": { "title": "gronka api", "version": "1.0.0-preview", "description": "paste a link, get the file. preview: not live yet and may change." }, "servers": [{ "url": "https://api.gronka.dev" }], "tags": [ { "name": "download" }, { "name": "account", "description": "the account page uses a cookie session. scripts can use an api key." } ], "paths": { "/v1/health": { "get": { "summary": "check the service", "responses": { "200": { "description": "service is up", "content": { "application/json": { "example": { "ok": true } } } } } } }, "/v1/download": { "post": { "tags": ["download"], "summary": "download from a link", "security": [{ "apiKey": [] }, {}], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadRequest" }, "examples": { "plain": { "value": { "url": "https://x.com/user/status/123" } }, "trimmedAudio": { "value": { "url": "https://youtu.be/abc", "mode": "audio", "start": "1:00", "end": "1:30" } } } } } }, "responses": { "200": { "description": "download result or error after leading spaces", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DownloadResult" }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "direct": { "value": { "lane": "direct", "files": [ { "url": "https://video.twimg.com/...", "filename": null, "type": "video" } ] } }, "merge": { "value": { "lane": "worker", "merge": true, "filename": "clip.mp4", "files": [ { "url": "https://dl.gronka.dev/f/...", "filename": "clip.video.mp4", "kind": "video", "size": 30123456 }, { "url": "https://dl.gronka.dev/f/...", "filename": "clip.audio.m4a", "kind": "audio", "size": 1234567 } ] } }, "failed": { "value": { "error": { "code": "VALIDATION_ERROR", "message": "video duration exceeds the maximum allowed (60 minutes)." } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/account": { "post": { "tags": ["account"], "summary": "create an account", "description": "returns the account number once. we cannot recover it.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Turnstile" } } } }, "responses": { "201": { "description": "account created and session cookie set", "content": { "application/json": { "example": { "id": "7K3P9", "number": "GW-7K3P9-ABCDE-FGHJK-MNPQR-STVWX-YZ012-3" } } } }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "get": { "tags": ["account"], "summary": "get account and keys", "security": [{ "session": [] }], "responses": { "200": { "description": "account and keys", "content": { "application/json": { "example": { "id": "7K3P9", "createdOn": "2026-09-28", "keys": [ { "id": "gk_ab12cd34", "label": "cli", "createdOn": "2026-09-28", "lastUsedOn": null } ] } } } }, "401": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": ["account"], "summary": "delete the account and its keys immediately", "security": [{ "session": [] }], "responses": { "200": { "description": "account deleted" }, "401": { "$ref": "#/components/responses/Error" } } } }, "/v1/account/rotate": { "post": { "tags": ["account"], "summary": "replace the account number; the old one stops working at once", "security": [{ "session": [] }], "responses": { "200": { "description": "new account number", "content": { "application/json": { "example": { "number": "GW-7K3P9-..." } } } } } } }, "/v1/session": { "post": { "tags": ["account"], "summary": "start a session", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Turnstile" }, { "type": "object", "required": ["number"], "properties": { "number": { "type": "string" } } } ] } } } }, "responses": { "200": { "description": "session cookie set" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": ["account"], "summary": "end a session", "responses": { "200": { "description": "session cookie cleared" } } } }, "/v1/keys": { "post": { "tags": ["account"], "summary": "create an api key", "security": [{ "session": [] }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 40 } } } } } }, "responses": { "201": { "description": "key shown once. up to 10 keys per account.", "content": { "application/json": { "example": { "id": "gk_ab12cd34", "key": "gk_ab12cd34_..." } } } }, "400": { "$ref": "#/components/responses/Error" } } } }, "/v1/keys/{id}": { "delete": { "tags": ["account"], "summary": "revoke an api key", "security": [{ "session": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^gk_[0-9a-z]{8}$" } } ], "responses": { "200": { "description": "key revoked" }, "404": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "api key format: gk__" }, "session": { "type": "apiKey", "in": "cookie", "name": "__Host-gw_session" } }, "responses": { "Error": { "description": "error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Turnstile": { "type": "object", "properties": { "turnstile": { "type": "string", "description": "turnstile token for the web page" } } }, "DownloadRequest": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "description": "link or text containing a link" }, "mode": { "type": "string", "enum": ["auto", "audio"], "default": "auto" }, "start": { "type": "string", "description": "trim start in seconds, m:ss, or h:mm:ss" }, "end": { "type": "string", "description": "trim end in seconds, m:ss, or h:mm:ss" }, "turnstile": { "type": "string", "description": "web page only. scripts use an api key" } } }, "DownloadResult": { "type": "object", "required": ["lane", "files"], "properties": { "lane": { "type": "string", "enum": ["direct", "worker", "r2"], "description": "direct uses the source link. worker streams through dl.gronka.dev; links last one hour. r2 copies to cdn.gronka.dev and is deleted after one hour." }, "merge": { "type": "boolean", "description": "true when separate video and audio files need merging" }, "filename": { "type": "string", "description": "suggested name for the merged file" }, "files": { "type": "array", "items": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string" }, "filename": { "type": ["string", "null"] }, "type": { "type": "string", "description": "media type, such as video, image, gif, or audio" }, "kind": { "type": "string", "enum": ["video", "audio"] }, "size": { "type": ["integer", "null"] } } } } } }, "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "examples": [ "BAD_URL", "RATE_LIMITED", "VERIFICATION_FAILED", "BUSY", "UNAUTHORIZED", "DOWNLOAD_FAILED" ] }, "message": { "type": "string", "description": "safe to show to a person" } } } } } } } }