{ "openapi": "3.1.0", "info": { "title": "BrainyShorts API", "version": "1.0.0", "summary": "Publish and schedule agent-made media to connected social accounts.", "description": "BrainyShorts is a free social publishing control plane. Agents upload finished media and create, schedule, or publish posts to connected TikTok, Instagram, YouTube, LinkedIn, and X accounts, plus long-form articles to DEV.to, Hashnode, Reddit, LinkedIn, and X. BrainyShorts does not generate media.\n\n**Host:** `https://www.brainyshorts.com`. Do not use `api.brainyshorts.com`; it is only a fallback alias for these REST paths.\n\n**Auth:** send `Authorization: Bearer ba_sk_...`. Create keys at https://www.brainyshorts.com/dashboard/api-keys. The `x-api-key` header is not accepted.\n\n**MCP:** the same capabilities are available as a hosted MCP server at `https://www.brainyshorts.com/api/mcp` (streamable HTTP, OAuth).", "contact": { "name": "BrainyShorts", "url": "https://www.brainyshorts.com" } }, "externalDocs": { "description": "Agent-readable overview", "url": "https://www.brainyshorts.com/llms.txt" }, "servers": [ { "url": "https://www.brainyshorts.com", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Accounts", "description": "Connected social accounts" }, { "name": "Posts", "description": "Create, schedule, update, and delete social posts" }, { "name": "Bulk", "description": "Idempotent batches of up to 100 drafts or schedules" }, { "name": "Media", "description": "Upload finished media to managed storage" }, { "name": "Articles", "description": "Long-form articles for DEV.to, Hashnode, Reddit, LinkedIn, and X" }, { "name": "Analytics", "description": "Owner-scoped performance metrics" }, { "name": "Skills", "description": "Public, versioned instruction skills. No auth." }, { "name": "Automations", "description": "Scheduled agent runs and the runner protocol" } ], "paths": { "/api/cli/accounts": { "get": { "tags": [ "Accounts" ], "operationId": "listAccounts", "summary": "List connected accounts", "description": "Returns connected social accounts, newest first. Use `id` as `social_account_id` in post targets.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/cli/posts": { "get": { "tags": [ "Posts" ], "operationId": "listPosts", "summary": "List posts", "description": "Each row is one platform delivery. `id` is the delivery id and `post_id` is the parent post.", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "examples": [ "draft", "scheduled", "posted", "failed" ] } }, { "name": "platform", "in": "query", "schema": { "$ref": "#/components/schemas/Platform" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "posts": { "type": "array", "items": { "$ref": "#/components/schemas/PostDelivery" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Posts" ], "operationId": "createPost", "summary": "Create a post", "description": "**If `action` is omitted, the post is scheduled when `scheduled_at` is present and published immediately otherwise.** Send `action: \"draft\"` to create a draft. Publishing or scheduling to YouTube is not available through this endpoint; use an agent automation instead.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePost" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "post": { "type": "object", "description": "Parent post" }, "social_posts": { "type": "array", "items": { "type": "object" }, "description": "One delivery per target" } } } } } }, "400": { "description": "Invalid post", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "issues": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "patch": { "tags": [ "Posts" ], "operationId": "updatePost", "summary": "Update or unschedule a post", "description": "Accepts a delivery id or a parent post id. Every still-scheduled delivery under the parent is updated together. `status: \"draft\"` cancels the schedule.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Delivery id or parent post id" }, "status": { "type": "string", "enum": [ "draft", "scheduled" ] }, "caption": { "type": "string", "maxLength": 2200 }, "scheduled_at": { "type": "string", "format": "date-time", "description": "Must be in the future. `scheduled_time` is accepted as an alias." }, "add_targets": { "type": "array", "maxItems": 12, "items": { "$ref": "#/components/schemas/Target" } } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostBundle" } } } }, "400": { "description": "INVALID_POST_UPDATE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Posts" ], "operationId": "deletePost", "summary": "Delete a post delivery", "description": "Only `draft`, `scheduled`, `retry_scheduled`, or `failed` deliveries can be deleted.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Post is not deletable in its current status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cli/posts/bulk": { "post": { "tags": [ "Bulk" ], "operationId": "createPostsBulk", "summary": "Create up to 100 drafts or schedules", "description": "Idempotent per `batch_id` + `item_key`: retry an identical request after a timeout. Changing an item while keeping its key is a conflict. Bulk cannot publish immediately. Media must be managed uploads referenced by `asset_id`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkBatch" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "400": { "description": "Invalid batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Bulk" ], "operationId": "getPostBatch", "summary": "Inspect a batch", "parameters": [ { "name": "batch_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "patch": { "tags": [ "Bulk" ], "operationId": "updatePostsBulk", "summary": "Update up to 100 scheduled posts", "description": "Each update is applied independently; the response reports per-item results.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "updates": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "properties": { "post_id": { "type": "string" }, "caption": { "type": "string", "maxLength": 2200 }, "scheduled_at": { "type": "string", "format": "date-time" }, "add_targets": { "type": "array", "maxItems": 12, "items": { "$ref": "#/components/schemas/Target" } } }, "required": [ "post_id" ] } } }, "required": [ "updates" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "updated_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object" } }, "next": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/cli/media/uploads": { "post": { "tags": [ "Media" ], "operationId": "reserveMediaUpload", "summary": "Reserve a managed media upload", "description": "Returns a presigned PUT URL, valid for 10 minutes. PUT the bytes, then call PATCH to complete. If `already_uploaded` is true, skip the PUT and reuse `asset_id`. Requires the `media:write` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaReservation" } } } }, "responses": { "201": { "description": "Reserved", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_id": { "type": "string", "format": "uuid" }, "already_uploaded": { "type": "boolean" }, "upload_url": { "type": "string", "format": "uri" }, "upload_method": { "type": "string", "const": "PUT" }, "upload_headers": { "type": "object", "additionalProperties": { "type": "string" } }, "expires_at": { "type": "string", "format": "date-time" }, "media": { "type": "object", "description": "Existing asset when already_uploaded is true" }, "next": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "MEDIA_UPLOAD_CONFLICT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "MEDIA_STORAGE_QUOTA_EXCEEDED: over 10 pending uploads, 2,000 objects, or 20 GiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Media" ], "operationId": "completeMediaUpload", "summary": "Mark an upload complete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_id": { "type": "string", "format": "uuid" } }, "required": [ "asset_id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "public_url": { "type": "string", "format": "uri" }, "media_type": { "type": "string" }, "mime_type": { "type": "string" }, "bytes": { "type": "integer" }, "metadata": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "MEDIA_UPLOAD_CONFLICT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cli/articles": { "get": { "tags": [ "Articles" ], "operationId": "listArticles", "summary": "List articles", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "publishing", "published", "failed" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "articles": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Articles" ], "operationId": "createArticle", "summary": "Create, schedule, or publish an article", "description": "`action` defaults to `draft`. `publish` delivers inline and returns per-target `results`. X publishes a native X Article. LinkedIn publishes a post with an article link card.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateArticle" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid article", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "delete": { "tags": [ "Articles" ], "operationId": "deleteArticle", "summary": "Delete an article", "description": "Removes the BrainyShorts record and its publication targets. Copies already published elsewhere are not removed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cli/analytics": { "get": { "tags": [ "Analytics" ], "operationId": "getAnalytics", "summary": "Get analytics", "description": "Returns an overview, or a single post when `post_id` is set.", "parameters": [ { "name": "platform", "in": "query", "schema": { "$ref": "#/components/schemas/Platform" } }, { "name": "account_id", "in": "query", "schema": { "type": "string" } }, { "name": "post_id", "in": "query", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid platform or date", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Post not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/skills": { "get": { "tags": [ "Skills" ], "operationId": "listSkills", "summary": "List skills", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "skills": { "type": "array", "items": { "$ref": "#/components/schemas/SkillSummary" } } } } } } } } } }, "/api/skills/{id}": { "get": { "tags": [ "Skills" ], "operationId": "getSkill", "summary": "Get a skill", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "examples": [ "social-post-from-brief", "source-to-social-post", "topic-watch" ] } }, { "name": "version", "in": "query", "schema": { "type": "string", "examples": [ "1.3.0" ] } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "markdown" ] }, "description": "Return the skill as a Markdown download" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "skill": { "type": "object" }, "versions": { "type": "array", "items": { "type": "string" } } } } }, "text/markdown": { "schema": { "type": "string" } } } }, "404": { "description": "Skill or version not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/automations": { "get": { "tags": [ "Automations" ], "operationId": "listAutomations", "summary": "List automations", "description": "Create and edit automations in the dashboard or over MCP.", "security": [ { "runToken": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "automations": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/agent/executors": { "post": { "tags": [ "Automations" ], "operationId": "registerExecutor", "summary": "Register or update an executor", "description": "An executor is the machine and agent that runs local automations. Pass `executor_id` to update an existing one.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "executor_id": { "type": "string" }, "name": { "type": "string", "maxLength": 100 }, "agent_type": { "type": "string", "maxLength": 50, "examples": [ "codex", "claude_code" ] }, "device_label": { "type": "string" }, "capabilities": { "type": "object" } }, "required": [ "name", "agent_type" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "executor": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "EXECUTOR_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/automations/sync": { "get": { "tags": [ "Automations" ], "operationId": "syncAutomations", "summary": "Sync automations for an executor", "parameters": [ { "name": "executor_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "automations": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/agent/automations/{id}/ack": { "post": { "tags": [ "Automations" ], "operationId": "ackAutomation", "summary": "Acknowledge an applied revision", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Automation id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "executor_id": { "type": "string" }, "revision": { "type": "integer" } }, "required": [ "executor_id", "revision" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "automation": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "EXECUTOR_MISMATCH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "REVISION_STALE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/automations/{id}/start": { "post": { "tags": [ "Automations" ], "operationId": "startRun", "summary": "Start a run", "description": "Idempotent per `idempotency_key`; runners use `${automation_id}:${revision}:${scheduled_for}`. Returns a run token (`ba_run_...`, valid for 6 hours) for the child agent.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Automation id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "executor_id": { "type": "string" }, "revision": { "type": "integer" }, "idempotency_key": { "type": "string", "maxLength": 200 }, "scheduled_for": { "type": "string", "format": "date-time" } }, "required": [ "executor_id", "revision", "idempotency_key" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "type": "object" }, "run_token": { "type": "string" }, "run_token_expires_at": { "type": "string", "format": "date-time" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "AUTOMATION_PAUSED, REVISION_STALE, NO_TARGETS, or WRONG_EXECUTION_MODE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/runs/{id}": { "get": { "tags": [ "Automations" ], "operationId": "getRun", "summary": "Get run status", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run id" }, { "name": "executor_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/agent/runs/{id}/events": { "post": { "tags": [ "Automations" ], "operationId": "logRunEvent", "summary": "Record a run step", "security": [ { "runToken": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "executor_id": { "type": "string" }, "step_id": { "type": "string" }, "status": { "type": "string", "enum": [ "started", "completed", "failed", "info" ] }, "message": { "type": "string" }, "metadata": { "type": "object" } }, "required": [ "step_id", "status" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "RUN_NOT_ACTIVE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/runs/{id}/media/uploads": { "post": { "tags": [ "Automations" ], "operationId": "reserveRunMediaUpload", "summary": "Reserve a media upload for a run", "description": "Same contract as `POST /api/cli/media/uploads`, authenticated with the run token.", "security": [ { "runToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaReservation" } } } }, "responses": { "201": { "description": "Reserved", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "RUN_TOKEN_REQUIRED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Automations" ], "operationId": "completeRunMediaUpload", "summary": "Complete a run media upload", "security": [ { "runToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_id": { "type": "string", "format": "uuid" } }, "required": [ "asset_id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "RUN_TOKEN_REQUIRED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/runs/{id}/direct-upload": { "post": { "tags": [ "Automations" ], "operationId": "createDirectUpload", "summary": "Open a TikTok or YouTube direct upload", "description": "MP4 only, up to 64 MiB. YouTube also requires the parent runner to send `x-brainy-runner-key: ba_sk_...`.", "security": [ { "runToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "social_account_id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 2200 }, "content_type": { "type": "string", "const": "video/mp4" }, "content_length": { "type": "integer", "maximum": 67108864 }, "content_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "content_md5": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "social_account_id", "title", "content_type", "content_length", "content_sha256" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object" } } } } } }, "401": { "description": "RUN_TOKEN_REQUIRED or SOCIAL_TOKEN_EXPIRED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "YOUTUBE_PARENT_RUNNER_REQUIRED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "DIRECT_UPLOAD_CONFLICT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/runs/{id}/direct-upload/status": { "post": { "tags": [ "Automations" ], "operationId": "getDirectUploadStatus", "summary": "Check a direct upload", "security": [ { "runToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "direct_upload_id": { "type": "string", "format": "uuid" } }, "required": [ "direct_upload_id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object" } } } } } }, "404": { "description": "DIRECT_UPLOAD_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/runs/{id}/complete-local": { "post": { "tags": [ "Automations" ], "operationId": "completeLocalRun", "summary": "Complete a local run", "description": "In draft mode, send media and caption only. In auto mode, every TikTok and YouTube target needs a `published_targets` entry from a direct upload.", "security": [ { "runToken": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "caption": { "type": "string", "maxLength": 2200 }, "title": { "type": "string" }, "media_type": { "type": "string", "enum": [ "image", "carousel", "video" ] }, "media_urls": { "type": "array", "maxItems": 10, "items": { "type": "string", "format": "uri" } }, "slides": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/Slide" } }, "published_targets": { "type": "array", "maxItems": 12, "items": { "type": "object", "properties": { "social_account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "tiktok", "youtube" ] }, "direct_upload_id": { "type": "string", "format": "uuid" } } } }, "metadata": { "type": "object" }, "executor_id": { "type": "string" } }, "required": [ "caption" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "INVALID_RUN_OUTPUT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "RUN_CONFLICT, AUTOMATION_PAUSED, REVISION_STALE, or AUTOMATION_REMOVED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/runs/{id}/fail": { "post": { "tags": [ "Automations" ], "operationId": "failRun", "summary": "Fail a run", "description": "Local runs authenticate with the run token (or an API key plus `executor_id`). Claimed queue runs send `claim_token`.", "security": [ { "runToken": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "maxLength": 1000 }, "claim_token": { "type": "string" }, "executor_id": { "type": "string" }, "metadata": { "type": "object" } }, "required": [ "error" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "RUN_NOT_ACTIVE or CLAIM_CONFLICT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/runs/claim": { "post": { "tags": [ "Automations" ], "operationId": "claimRun", "summary": "Claim a queued run (legacy queue)", "description": "Atomically claims one pending run. `{\"run\": null}` means no work. The legacy queue publishes to Instagram only; new integrations should use local automations.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "automation_id": { "type": "string" }, "lease_seconds": { "type": "integer", "minimum": 60, "maximum": 3600, "default": 900 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "type": [ "object", "null" ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/agent/runs/{id}/renew": { "post": { "tags": [ "Automations" ], "operationId": "renewRun", "summary": "Renew a claim (legacy queue)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "claim_token": { "type": "string" }, "lease_seconds": { "type": "integer", "minimum": 60, "maximum": 3600, "default": 900 } }, "required": [ "claim_token" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "CLAIM_CONFLICT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/runs/{id}/complete": { "post": { "tags": [ "Automations" ], "operationId": "completeRun", "summary": "Complete a claimed run (legacy queue)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "claim_token": { "type": "string" }, "caption": { "type": "string", "maxLength": 2200 }, "media_urls": { "type": "array", "maxItems": 10, "items": { "type": "string", "format": "uri" } }, "slides": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/Slide" } }, "metadata": { "type": "object" } }, "required": [ "claim_token", "caption" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "type": "object" } } } } } }, "400": { "description": "PLATFORM_NOT_AVAILABLE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "CLAIM_CONFLICT, CLAIM_EXPIRED, or TARGET_MISSING", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/runs/{id}/skip": { "post": { "tags": [ "Automations" ], "operationId": "skipRun", "summary": "Skip a claimed run (legacy queue)", "description": "Finishes a valid no-op without consuming retries.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "claim_token": { "type": "string" }, "reason": { "type": "string", "maxLength": 1000 }, "code": { "type": "string", "maxLength": 100, "default": "SKIPPED" } }, "required": [ "claim_token", "reason" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "ba_sk_...", "description": "API key from /dashboard/api-keys. Keys expire after 365 days." }, "runToken": { "type": "http", "scheme": "bearer", "bearerFormat": "ba_run_...", "description": "Per-run token returned by `start`, valid for 6 hours and bound to one run." } }, "responses": { "Unauthorized": { "description": "Missing, invalid, expired, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] }, "Platform": { "type": "string", "enum": [ "tiktok", "instagram", "youtube", "linkedin", "x" ] }, "Account": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "$ref": "#/components/schemas/Platform" }, "account_handle": { "type": "string" }, "token_valid": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "Target": { "type": "object", "properties": { "social_account_id": { "type": "string", "format": "uuid" }, "platform": { "$ref": "#/components/schemas/Platform" }, "settings": { "type": "object" } }, "required": [ "social_account_id", "platform" ] }, "Slide": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 500 }, "url": { "type": "string", "format": "uri" }, "aspect_ratio": { "type": "string", "default": "9:16" } }, "required": [ "url" ] }, "CreatePost": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 120, "description": "Defaults to the first 120 characters of the caption" }, "caption": { "type": "string", "minLength": 1, "maxLength": 2200, "description": "X targets limit the caption to 280 characters" }, "media_type": { "type": "string", "enum": [ "image", "carousel", "video" ], "description": "Inferred when omitted. image: 1 URL; carousel: 2+; video: 1 MP4." }, "media_urls": { "type": "array", "maxItems": 10, "items": { "type": "string", "format": "uri", "pattern": "^https://" }, "description": "JSON array of HTTPS URLs, not a comma-separated string" }, "slides": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/Slide" } }, "targets": { "type": "array", "maxItems": 12, "items": { "$ref": "#/components/schemas/Target" } }, "action": { "type": "string", "enum": [ "draft", "publish", "schedule" ] }, "scheduled_at": { "type": "string", "format": "date-time", "description": "Required for schedule; must be in the future. `scheduled_time` is accepted as an alias." }, "project_id": { "type": "string", "format": "uuid" } }, "required": [ "caption" ] }, "PostDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "post_id": { "type": "string" }, "platform": { "$ref": "#/components/schemas/Platform" }, "status": { "type": "string" }, "scheduled_time": { "type": [ "string", "null" ], "format": "date-time" }, "posted_time": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "account": { "type": "object" }, "title": { "type": "string" }, "caption": { "type": "string" }, "media_type": { "type": "string" }, "media_urls": { "type": "array", "items": { "type": "string" } }, "video_url": { "type": [ "string", "null" ] } } }, "PostBundle": { "type": "object", "description": "The parent post fields plus `post_id` and its deliveries", "properties": { "post_id": { "type": "string" }, "social_posts": { "type": "array", "items": { "type": "object" } } }, "additionalProperties": true }, "BulkBatch": { "type": "object", "required": [ "batch_id", "items" ], "additionalProperties": false, "properties": { "batch_id": { "type": "string", "format": "uuid" }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "properties": { "item_key": { "type": "string", "maxLength": 100, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:-]*$" }, "title": { "type": "string", "maxLength": 120 }, "caption": { "type": "string", "maxLength": 2200 }, "media_type": { "type": "string", "enum": [ "image", "carousel", "video" ] }, "media": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "object", "properties": { "asset_id": { "type": "string", "format": "uuid" }, "text": { "type": "string", "maxLength": 500 }, "aspect_ratio": { "type": "string" } }, "required": [ "asset_id" ] } }, "targets": { "type": "array", "maxItems": 12, "items": { "$ref": "#/components/schemas/Target" } }, "action": { "type": "string", "enum": [ "draft", "schedule" ] }, "scheduled_at": { "type": "string", "format": "date-time" } }, "required": [ "item_key", "title", "caption", "media_type", "media", "action" ] } } } }, "BulkResult": { "type": "object", "additionalProperties": true, "properties": { "batch_id": { "type": "string", "format": "uuid" }, "items": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" }, "has_more": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "string" } }, "next": { "type": "string" } } }, "MediaReservation": { "type": "object", "additionalProperties": false, "required": [ "content_type", "content_length", "content_sha256", "content_md5" ], "properties": { "asset_id": { "type": "string", "format": "uuid", "description": "Optional, for idempotent retries" }, "content_type": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp", "video/mp4" ] }, "content_length": { "type": "integer", "minimum": 1, "description": "Images up to 15 MiB, MP4 up to 200 MiB" }, "content_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "content_md5": { "type": "string", "pattern": "^[a-f0-9]{32}$" } } }, "CreateArticle": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "subtitle": { "type": "string", "maxLength": 300 }, "markdown": { "type": "string", "minLength": 1, "maxLength": 400000 }, "tags": { "type": "array", "maxItems": 10, "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "maxLength": 50 }, "description": "DEV.to uses the first 4" }, "canonical_url": { "type": "string", "format": "uri" }, "cover_image_url": { "type": "string", "format": "uri" }, "targets": { "type": "array", "maxItems": 12, "items": { "type": "object", "properties": { "social_account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "devto", "hashnode", "linkedin", "x", "reddit" ] }, "settings": { "type": "object" } }, "required": [ "social_account_id", "platform" ] } }, "action": { "type": "string", "enum": [ "draft", "publish", "schedule" ], "default": "draft" }, "scheduled_at": { "type": "string", "format": "date-time" } }, "required": [ "title", "markdown" ] }, "SkillSummary": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "platforms": { "type": "array", "items": { "$ref": "#/components/schemas/Platform" } } } } } } }