{ "openapi": "3.1.0", "info": { "title": "AttentionPilot Agent API", "version": "1.2.0", "description": "Connect accounts at /onboarding/connect. Agent instructions: /agent-api.md. Publishing requires user authorization." }, "servers": [ { "url": "https://attentionpilot.com/api/v1" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "pilot_ API key" } } }, "paths": { "/accounts": { "get": { "operationId": "listAccounts", "responses": { "200": { "description": "Success. Inspect per-target statuses.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; inspect before retrying", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/accounts/{id}/options": { "get": { "operationId": "getProviderOptions", "responses": { "200": { "description": "Success. Inspect per-target statuses.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; inspect before retrying", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/posts": { "get": { "operationId": "listPosts", "responses": { "200": { "description": "Success. Inspect per-target statuses.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; inspect before retrying", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "operationId": "createPost", "responses": { "200": { "description": "Success. Inspect per-target statuses.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; inspect before retrying", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "Pre-flight validation failed", "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "description": "Workspace limit", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "caption" ], "additionalProperties": false, "properties": { "caption": { "type": "string", "minLength": 1, "maxLength": 20000 }, "accounts": { "oneOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "uniqueItems": true } ] }, "media": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20, "uniqueItems": true }, "overrides": { "type": "object", "additionalProperties": { "type": "string" } }, "options": { "type": "object", "additionalProperties": { "type": "object", "description": "Per-account provider options: see /agent-api.md" } }, "schedule": { "type": "string", "description": "draft, now, or ISO timestamp with timezone. Omit to queue." }, "dryRun": { "type": "boolean", "default": false } } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Stable identity for one logical post. Always reuse after timeouts." } ] } }, "/posts/{id}": { "get": { "operationId": "getPost", "responses": { "200": { "description": "Success. Inspect per-target statuses.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; inspect before retrying", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/posts/{id}/retry": { "post": { "operationId": "retryFailedTargets", "responses": { "200": { "description": "Success. Inspect per-target statuses.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; inspect before retrying", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/media/presign": { "post": { "operationId": "prepareMediaUpload", "responses": { "200": { "description": "Success. Inspect per-target statuses.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; inspect before retrying", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "PUT raw bytes to uploadUrl with returned headers, then complete. Never send the API bearer token to the upload URL.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "filename", "contentType", "size" ], "properties": { "filename": { "type": "string" }, "contentType": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp", "video/mp4", "video/quicktime", "video/webm" ] }, "size": { "type": "integer", "minimum": 1, "maximum": 536870912 } } } } } } } }, "/media/complete": { "post": { "operationId": "completeMediaUpload", "responses": { "200": { "description": "Success. Inspect per-target statuses.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; inspect before retrying", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uploadId" ], "properties": { "uploadId": { "type": "string", "format": "uuid" }, "width": { "type": "integer", "minimum": 1, "description": "Optional measured media metadata; video duration is required for TikTok." }, "height": { "type": "integer", "minimum": 1, "description": "Optional measured media metadata; video duration is required for TikTok." }, "durationMs": { "type": "integer", "minimum": 1, "description": "Optional measured media metadata; video duration is required for TikTok." } } } } } } } }, "/posts/{id}/reconcile": { "post": { "operationId": "reconcileUncertainDelivery", "description": "Human-confirmed provider inspection only. Does not publish.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targetId", "action", "confirmed" ], "properties": { "targetId": { "type": "string", "format": "uuid" }, "action": { "enum": [ "mark_published", "confirm_not_published" ] }, "confirmed": { "const": true }, "remoteId": { "type": "string" }, "remoteUrl": { "type": "string", "format": "uri" }, "note": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Ledger reconciled; no publishing occurred." }, "409": { "description": "Active, settled or inaccessible target." } } } }, "/posts/{id}/cancel": { "post": { "operationId": "cancelPost", "summary": "Cancel a scheduled post before publishing starts; keep it as a draft.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Canceled; returns the draft with canceled:true. Safe to repeat." }, "401": { "description": "Missing or revoked key." }, "404": { "description": "Post not found in this profile." }, "409": { "description": "Publishing has started or delivery already occurred; cannot cancel." }, "503": { "description": "Cancellation not confirmed; inspect and retry with the same post ID." } } } } } }