{ "openapi": "3.1.0", "info": { "title": "Autoposter AI Agent API", "version": "1.0.0", "description": "Automated social media publishing, scheduling, draft creation, and receipt tracking for AI assistants (ChatGPT, Claude, Cursor, Windsurf, OpenClaw).", "contact": { "name": "Autoposter AI Support", "url": "https://autoposter.ai" } }, "servers": [ { "url": "https://agent.autoposter.ai", "description": "Autoposter AI Agent Gateway" } ], "security": [ { "BearerAuth": [] }, { "OAuth2": [ "accounts:read", "posts:create", "posts:publish", "posts:read", "rules:read" ] } ], "paths": { "/v1/accounts": { "get": { "operationId": "listAccounts", "summary": "List connected social accounts", "description": "Returns all active social media channels connected to the workspace (Twitter, LinkedIn, Instagram, TikTok, Facebook, YouTube, Threads, Bluesky, Pinterest).", "responses": { "200": { "description": "List of accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "name": { "type": "string" }, "username": { "type": "string", "nullable": true }, "avatarUrl": { "type": "string", "nullable": true }, "status": { "type": "string" } } } } } } } } } } } }, "/v1/rules": { "get": { "operationId": "getPlatformRules", "summary": "Get platform posting rules & limits", "description": "Returns character limits, supported media formats, and platform-specific constraints.", "security": [], "responses": { "200": { "description": "Platform rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "captionLimits": { "type": "object", "description": "Platform-specific caption character limits." }, "mediaRequirements": { "type": "object", "description": "Supported image and video requirements per platform." }, "automatedSafeguards": { "type": "object", "description": "Automated safeguards applied to captions and media." }, "guidelines": { "type": "array", "items": { "type": "string" }, "description": "Platform publishing guidelines." } } } } } } } } }, "/v1/posts": { "get": { "operationId": "listPosts", "summary": "List recent and scheduled posts", "description": "Returns recent posts, upcoming scheduled queue, and delivery status.", "responses": { "200": { "description": "List of posts", "content": { "application/json": { "schema": { "type": "object", "properties": { "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "text": { "type": "string" }, "state": { "type": "string" }, "scheduledAt": { "type": "string" }, "postedAt": { "type": "string", "nullable": true }, "postLink": { "type": "string", "nullable": true }, "errorMessage": { "type": "string", "nullable": true } } } } } } } } } } }, "post": { "operationId": "createPost", "summary": "Create draft, scheduled, or live post", "description": "Creates posts across one or more social accounts. If publishMode is 'immediate', post is enqueued or sent to human approval queue.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "accountIds" ], "properties": { "accountIds": { "type": "array", "items": { "type": "string" }, "description": "Target account IDs from GET /v1/accounts." }, "content": { "type": "string", "description": "Base text content for the post." }, "platformContent": { "type": "object", "description": "Platform-specific content overrides (e.g. twitter, linkedin).", "additionalProperties": { "type": "string" } }, "mediaUrls": { "type": "array", "items": { "type": "string" }, "description": "External public URLs for image or video attachments." }, "mediaIds": { "type": "array", "items": { "type": "string" }, "description": "Workspace media IDs uploaded via /v1/media or /v1/media/upload-url." }, "publishMode": { "type": "string", "enum": [ "draft", "schedule", "immediate" ], "default": "draft", "description": "Mode: 'draft' saves to workspace, 'schedule' requires scheduledAt, 'immediate' publishes or requests approval." }, "scheduledAt": { "type": "string", "description": "ISO timestamp or local datetime string for scheduled publishing, e.g. 2026-10-05T14:00:00 or 2026-10-05T14:00:00Z." }, "timezone": { "type": "string", "description": "Optional IANA timezone (e.g. 'America/New_York'). If omitted, defaults to workspace or user timezone." }, "title": { "type": "string", "description": "Optional title (used for YouTube, Pinterest, etc.)." } } } } } }, "responses": { "201": { "description": "Post created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "postIds": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "scheduledAt": { "type": "string" }, "timezone": { "type": "string" }, "message": { "type": "string" }, "preview": { "type": "object" } } } } } } } } }, "/v1/posts/{id}": { "get": { "operationId": "getPost", "summary": "Get post status & live receipt URL", "description": "Returns the current state and live receipt link for a post.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Post ID." } ], "responses": { "200": { "description": "Post details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "state": { "type": "string" }, "text": { "type": "string" }, "postLink": { "type": "string", "nullable": true }, "errorMessage": { "type": "string", "nullable": true } } } } } } } }, "delete": { "operationId": "deletePost", "summary": "Delete / cancel a post", "description": "Deletes a draft or scheduled post.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Post deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } } } } }, "/v1/posts/{id}/publish": { "post": { "operationId": "publishDraftPost", "summary": "Approve & publish a draft or pending post", "description": "Triggers live delivery for an approved post. Tagged as consequential to trigger inline human confirmation in ChatGPT and Claude.", "x-openai-isConsequential": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Post ID to approve and publish." } ], "responses": { "200": { "description": "Post approved and enqueued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/v1/media/upload-url": { "post": { "operationId": "getMediaUploadUrl", "summary": "Get direct S3 presigned upload URL", "description": "Generates a presigned S3 upload URL for direct, high-speed upload of videos or images up to 5GB without Lambda timeout or memory limits. Returns direct PUT URL, multipart POST fields, and public CDN URL.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fileName", "contentType" ], "properties": { "fileName": { "type": "string", "description": "File name with extension, e.g. 'promo.mp4' or 'banner.png'." }, "contentType": { "type": "string", "description": "MIME type, e.g. 'video/mp4' or 'image/png'." } } } } } }, "responses": { "200": { "description": "Presigned upload URLs generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "cdnUrl": { "type": "string" }, "directPutUrl": { "type": "string" }, "upload": { "type": "object", "properties": { "url": { "type": "string" }, "fields": { "type": "object" } } }, "instructions": { "type": "object" } } } } } } } } }, "/v1/media": { "get": { "operationId": "listMedia", "summary": "List workspace media", "description": "Returns all media assets stored in the workspace library.", "responses": { "200": { "description": "List of media items", "content": { "application/json": { "schema": { "type": "object", "properties": { "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "key": { "type": "string" }, "url": { "type": "string" }, "thumbnailUrl": { "type": "string" } } } } } } } } } } }, "post": { "operationId": "createMedia", "summary": "Register uploaded media", "description": "Registers an S3 object key into the workspace media library after direct upload.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "S3 key returned from /v1/media/upload-url." }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "video", "image", "gif", "audio" ] }, "metadata": { "type": "object" }, "folderId": { "type": "string" } } } } } }, "responses": { "201": { "description": "Media item registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "key": { "type": "string" }, "url": { "type": "string" }, "thumbnailUrl": { "type": "string" } } } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "ap_live_*", "description": "Enter your Autoposter workspace API Key (e.g. ap_live_...)." }, "OAuth2": { "type": "oauth2", "description": "OAuth 2.0 Authorization Code flow for ChatGPT, Claude, Gemini, Copilot, and third-party AI agents.", "flows": { "authorizationCode": { "authorizationUrl": "https://agent.autoposter.ai/oauth/authorize", "tokenUrl": "https://agent.autoposter.ai/oauth/token", "scopes": { "accounts:read": "View connected social media channels and profiles", "posts:create": "Create and schedule social media posts", "posts:publish": "Approve and publish draft or pending posts", "posts:read": "Read post publishing status and receipts", "rules:read": "Read platform caption limits and media specs" } } } } } } }