{ "openapi": "3.1.0", "info": { "title": "Chirpy API", "version": "1.0.0", "description": "Chirpy's API for your own systems and AI agents. Every action is a POST with a JSON body to /api/v1/{action}, authenticated with an API key from Settings > Developers.\n\nResponses always use the same envelope: { ok: true, data } on success, { ok: false, error: { code, message } } on failure.\n\nScopes: read (look things up), write (drafts, media, Brand Kits; spends AI credits), publish (schedule, publish, approve, send, moderate, delete).\n\nLimits: requests a minute per key, with X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset on every response and Retry-After on 429 rate_limited. Each plan also has daily limits on actions and on publish actions, shared with the MCP server and reset at 00:00 UTC; over them, 429 limit_reached says when they reset.\n\nAI work (images, posters, videos, remixes) and actions that cost Chirpy money per call (such as posting to X) use the account's AI credits. Without enough, 402 insufficient_credits.\n\nThere is no sandbox: calls act on your live workspace. Test with drafts." }, "servers": [ { "url": "https://chirpy.me/api/v1" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Account" }, { "name": "Accounts" }, { "name": "Posts" }, { "name": "Approvals" }, { "name": "Media" }, { "name": "Brand Kits" }, { "name": "Campaigns" }, { "name": "Inbox" }, { "name": "Analytics" } ], "paths": { "/me": { "get": { "operationId": "me", "tags": [ "Account" ], "summary": "Who this key belongs to, its scopes and plan. The quickest way to check a key works.", "responses": { "200": { "$ref": "#/components/responses/Ok" }, "401": { "$ref": "#/components/responses/Error" } } } }, "/tools": { "get": { "operationId": "listTools", "tags": [ "Account" ], "summary": "Every action this API offers, with its scope and input schema. The same list the MCP server will expose.", "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/list_accounts": { "post": { "operationId": "list_accounts", "tags": [ "Accounts" ], "summary": "Connected social accounts you can post to, with platform, name and connection health (healthy, needs_reconnect, expired).", "description": "Connected social accounts you can post to, with platform, name and connection health (healthy, needs_reconnect, expired).\n\nRequires the `read` scope.", "x-chirpy-scope": "read", "x-chirpy-area": "accounts", "x-chirpy-title": "List accounts", "x-chirpy-hints": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/list_posts": { "post": { "operationId": "list_posts", "tags": [ "Posts" ], "summary": "Posts across your team with status, platforms, dates and a content preview. Filter by status, date range (ISO dates) or account. Newest first.", "description": "Posts across your team with status, platforms, dates and a content preview. Filter by status, date range (ISO dates) or account. Newest first.\n\nRequires the `read` scope.", "x-chirpy-scope": "read", "x-chirpy-area": "posts", "x-chirpy-title": "List posts", "x-chirpy-hints": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "scheduled", "published", "posted", "failed", "pending_approval", "all" ] }, "from": { "type": "string", "description": "ISO date, inclusive" }, "to": { "type": "string", "description": "ISO date, inclusive" }, "accountId": { "type": "integer" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/get_post": { "post": { "operationId": "get_post", "tags": [ "Posts" ], "summary": "One post with full content, media count, status and per-platform stats.", "description": "One post with full content, media count, status and per-platform stats.\n\nRequires the `read` scope.", "x-chirpy-scope": "read", "x-chirpy-area": "posts", "x-chirpy-title": "Get post", "x-chirpy-hints": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "postId": { "type": "integer" } }, "required": [ "postId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/create_drafts": { "post": { "operationId": "create_drafts", "tags": [ "Posts" ], "summary": "Saves one or more posts to Drafts. Never schedules or publishes. Target accounts with accountIds from list_accounts, or platforms. Attach media with mediaFileIds from list_media or https mediaUrls returned by Chirpy.", "description": "Saves one or more posts to Drafts. Never schedules or publishes. Target accounts with accountIds from list_accounts, or platforms. Attach media with mediaFileIds from list_media or https mediaUrls returned by Chirpy.\n\nRequires the `write` scope. Send an Idempotency-Key header to make retries safe.", "x-chirpy-scope": "write", "x-chirpy-area": "posts", "x-chirpy-title": "Create drafts", "x-chirpy-hints": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "posts": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "properties": { "content": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "accountIds": { "type": "array", "items": { "type": "integer" } }, "mediaFileIds": { "type": "array", "items": { "type": "integer" }, "description": "Media Library file ids (list_media)" }, "mediaUrls": { "type": "array", "items": { "type": "string" }, "description": "https links returned by our own tools" }, "note": { "type": "string" } }, "required": [ "content" ], "additionalProperties": false } } }, "required": [ "posts" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/attach_media": { "post": { "operationId": "attach_media", "tags": [ "Posts" ], "summary": "Adds Media Library files or Chirpy media links to an existing draft. For a scheduled post use update_scheduled_media.", "description": "Adds Media Library files or Chirpy media links to an existing draft. For a scheduled post use update_scheduled_media.\n\nRequires the `write` scope. Send an Idempotency-Key header to make retries safe.", "x-chirpy-scope": "write", "x-chirpy-area": "posts", "x-chirpy-title": "Attach media", "x-chirpy-hints": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "draftId": { "type": "integer" }, "mediaFileIds": { "type": "array", "items": { "type": "integer" } }, "mediaUrls": { "type": "array", "items": { "type": "string" } }, "replace": { "type": "boolean", "description": "Replace the draft's media instead of adding to it" } }, "required": [ "draftId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/remix_post": { "post": { "operationId": "remix_post", "tags": [ "Posts" ], "summary": "Writes 1 to 5 new draft versions of an existing post, like Remix on the calendar. Uses AI credits. The new drafts land in Drafts; nothing is scheduled.", "description": "Writes 1 to 5 new draft versions of an existing post, like Remix on the calendar. Uses AI credits. The new drafts land in Drafts; nothing is scheduled.\n\nRequires the `write` scope. Send an Idempotency-Key header to make retries safe.", "x-chirpy-scope": "write", "x-chirpy-area": "posts", "x-chirpy-title": "Remix post", "x-chirpy-hints": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "postId": { "type": "integer" }, "platforms": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 8 }, "count": { "type": "integer", "minimum": 1, "maximum": 5 }, "goal": { "type": "string", "enum": [ "variations", "clicks", "comments", "shares", "conversions" ] }, "similarity": { "type": "number", "minimum": 0, "maximum": 1 }, "media": { "type": "string", "enum": [ "none", "reuse", "generate" ] } }, "required": [ "postId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/schedule_posts": { "post": { "operationId": "schedule_posts", "tags": [ "Posts" ], "summary": "Schedules existing drafts at the given times (ISO datetimes with an offset).", "description": "Schedules existing drafts at the given times (ISO datetimes with an offset).\n\nRequires the `publish` scope. Send an Idempotency-Key header to make retries safe.", "x-chirpy-scope": "publish", "x-chirpy-area": "posts", "x-chirpy-title": "Schedule posts", "x-chirpy-hints": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 30, "items": { "type": "object", "properties": { "draftId": { "type": "integer" }, "scheduledFor": { "type": "string" } }, "required": [ "draftId", "scheduledFor" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/update_scheduled_media": { "post": { "operationId": "update_scheduled_media", "tags": [ "Posts" ], "summary": "Adds or replaces media on posts that are already scheduled.", "description": "Adds or replaces media on posts that are already scheduled.\n\nRequires the `publish` scope. Send an Idempotency-Key header to make retries safe.", "x-chirpy-scope": "publish", "x-chirpy-area": "posts", "x-chirpy-title": "Update scheduled media", "x-chirpy-hints": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 30, "items": { "type": "object", "properties": { "postId": { "type": "integer" }, "mediaFileIds": { "type": "array", "items": { "type": "integer" } }, "mediaUrls": { "type": "array", "items": { "type": "string" } }, "replace": { "type": "boolean" } }, "required": [ "postId" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/manage_posts": { "post": { "operationId": "manage_posts", "tags": [ "Posts" ], "summary": "Changes existing posts: reschedule, edit, unschedule, move to drafts, delete, publish now, retry or duplicate.", "description": "Changes existing posts: reschedule, edit, unschedule, move to drafts, delete, publish now, retry or duplicate.\n\nRequires the `publish` scope. Send an Idempotency-Key header to make retries safe.", "x-chirpy-scope": "publish", "x-chirpy-area": "posts", "x-chirpy-title": "Manage posts", "x-chirpy-hints": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 30, "items": { "type": "object", "properties": { "postId": { "type": "integer" }, "action": { "type": "string", "enum": [ "reschedule", "edit", "unschedule", "move_to_drafts", "delete", "publish_now", "retry", "duplicate" ] }, "scheduledFor": { "type": "string", "description": "New time, ISO 8601 with offset (reschedule)." }, "content": { "type": "string", "maxLength": 5000 }, "mediaUrls": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "socialAccountIds": { "type": "array", "items": { "type": "integer" }, "maxItems": 20 }, "platformTargets": { "type": "array", "items": { "type": "string", "enum": [ "instagram", "facebook", "twitter", "linkedin", "linkedin-personal", "tiktok", "pinterest", "youtube" ] }, "maxItems": 8 }, "postType": { "type": "string", "enum": [ "feed", "story", "reel" ] }, "linkUrl": { "type": "string", "maxLength": 2048 }, "pinterestTitle": { "type": "string", "maxLength": 100 }, "tikTokSettings": { "type": "object", "description": "TikTok options as the post editor sends them (privacyLevel, disableComment, disableDuet, disableStitch)." } }, "required": [ "postId", "action" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/best_posting_times": { "post": { "operationId": "best_posting_times", "tags": [ "Posts" ], "summary": "Best posting days and time windows for up to 5 accounts, from each account's last 90 days.", "description": "Best posting days and time windows for up to 5 accounts, from each account's last 90 days.\n\nRequires the `read` scope.", "x-chirpy-scope": "read", "x-chirpy-area": "posts", "x-chirpy-title": "Best posting times", "x-chirpy-hints": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountIds": { "type": "array", "items": { "type": "integer" }, "maxItems": 5 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/list_approvals": { "post": { "operationId": "list_approvals", "tags": [ "Approvals" ], "summary": "Posts waiting for approval in your organisations. Owners and managers only.", "description": "Posts waiting for approval in your organisations. Owners and managers only.\n\nRequires the `read` scope.", "x-chirpy-scope": "read", "x-chirpy-area": "approvals", "x-chirpy-title": "List approvals", "x-chirpy-hints": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/submit_for_approval": { "post": { "operationId": "submit_for_approval", "tags": [ "Approvals" ], "summary": "Sends drafts to your team's approval queue.", "description": "Sends drafts to your team's approval queue.\n\nRequires the `publish` scope. Send an Idempotency-Key header to make retries safe.", "x-chirpy-scope": "publish", "x-chirpy-area": "approvals", "x-chirpy-title": "Submit for approval", "x-chirpy-hints": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "draftIds": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "maxItems": 30 } }, "required": [ "draftIds" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/review_approvals": { "post": { "operationId": "review_approvals", "tags": [ "Approvals" ], "summary": "Approves, rejects or requests changes on posts waiting for approval. Approving schedules the post at its planned time, or publishes it at once when it has none. Owners and managers only.", "description": "Approves, rejects or requests changes on posts waiting for approval. Approving schedules the post at its planned time, or publishes it at once when it has none. Owners and managers only.\n\nRequires the `publish` scope. Send an Idempotency-Key header to make retries safe.", "x-chirpy-scope": "publish", "x-chirpy-area": "approvals", "x-chirpy-title": "Review approvals", "x-chirpy-hints": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 30, "items": { "type": "object", "properties": { "approvalId": { "type": "integer" }, "decision": { "type": "string", "enum": [ "approve", "reject", "request_changes" ] }, "comments": { "type": "string", "maxLength": 2000 } }, "required": [ "approvalId", "decision" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/list_media": { "post": { "operationId": "list_media", "tags": [ "Media" ], "summary": "Files in your team's Media Library, newest first, with id, name, kind and whether AI made them. Use the ids as mediaFileIds on posts.", "description": "Files in your team's Media Library, newest first, with id, name, kind and whether AI made them. Use the ids as mediaFileIds on posts.\n\nRequires the `read` scope.", "x-chirpy-scope": "read", "x-chirpy-area": "media", "x-chirpy-title": "List media", "x-chirpy-hints": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image", "video" ] }, "search": { "type": "string", "description": "Words in the file name" }, "limit": { "type": "integer", "description": "Up to 40" }, "offset": { "type": "integer", "description": "Skip this many of the newest files, to page through a large library" }, "fileIds": { "type": "array", "items": { "type": "integer" }, "maxItems": 12, "description": "Only these files, in this order (for example the matches you found with look_at_media)" }, "show": { "type": "boolean", "description": "true when the user wants to see the files: they appear as thumbnails under your reply (up to 12)" } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/list_media_folders": { "post": { "operationId": "list_media_folders", "tags": [ "Media" ], "summary": "Media Library folders with id, name and parent folder.", "description": "Media Library folders with id, name and parent folder.\n\nRequires the `read` scope.", "x-chirpy-scope": "read", "x-chirpy-area": "media", "x-chirpy-title": "List media folders", "x-chirpy-hints": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parentFolderId": { "type": "integer", "description": "Folders inside this one; leave out for the top level" } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/generate_image": { "post": { "operationId": "generate_image", "tags": [ "Media" ], "summary": "Generates one image from a prompt in your Brand Kit's style and saves it to the Media Library. Give draftId to put it straight onto a draft. Uses AI credits.", "description": "Generates one image from a prompt in your Brand Kit's style and saves it to the Media Library. Give draftId to put it straight onto a draft. Uses AI credits.\n\nRequires the `write` scope. Send an Idempotency-Key header to make retries safe.", "x-chirpy-scope": "write", "x-chirpy-area": "media", "x-chirpy-title": "Generate image", "x-chirpy-hints": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "description": "Subject, composition, background, mood, lighting, style; leave clear space if text will be added later" }, "aspectRatio": { "type": "string", "enum": [ "1:1", "4:5", "9:16", "16:9" ] }, "useBrandStyle": { "type": "boolean", "description": "Apply the Brand Kit palette and logo (default true)" }, "draftId": { "type": "integer", "description": "A draft to add the image to once it is made" }, "referenceFileIds": { "type": "array", "items": { "type": "integer" }, "maxItems": 5, "description": "Up to 5 Media Library image fileIds to use as references: the user's photos, product or style to follow. Use the ids of images the user attached in this chat, or ones you found with list_media and look_at_media." }, "referenceMode": { "type": "string", "enum": [ "inspiration", "variant" ], "description": "inspiration (default): the references guide the look; variant: keep the reference's subject, composition and palette and refresh the rest" } }, "required": [ "prompt" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/edit_image": { "post": { "operationId": "edit_image", "tags": [ "Media" ], "summary": "Edits a Media Library photo: change it with an instruction, remove the background, crop to an aspect ratio or add your logo. Changes use AI credits.", "description": "Edits a Media Library photo: change it with an instruction, remove the background, crop to an aspect ratio or add your logo. Changes use AI credits.\n\nRequires the `write` scope. Send an Idempotency-Key header to make retries safe.", "x-chirpy-scope": "write", "x-chirpy-area": "media", "x-chirpy-title": "Edit image", "x-chirpy-hints": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fileId": { "type": "integer" }, "operation": { "type": "string", "enum": [ "change", "remove_background", "crop", "add_logo" ] }, "instruction": { "type": "string" }, "referenceFileIds": { "type": "array", "items": { "type": "integer" }, "description": "change only: up to 3 Media Library images to copy items from" }, "aspect": { "type": "string", "enum": [ "1:1", "4:5", "9:16", "16:9", "1.91:1" ] }, "position": { "type": "string", "enum": [ "top-left", "top-center", "top-right", "center", "bottom-left", "bottom-center", "bottom-right" ] }, "size": { "type": "string", "enum": [ "small", "medium", "large" ] } }, "required": [ "fileId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/design_poster": { "post": { "operationId": "design_poster", "tags": [ "Media" ], "summary": "Designs a branded poster, infographic or 3 to 6 slide carousel. Text is rendered exactly as given. Saved to the Media Library. Uses AI credits.", "description": "Designs a branded poster, infographic or 3 to 6 slide carousel. Text is rendered exactly as given. Saved to the Media Library. Uses AI credits.\n\nRequires the `write` scope. Send an Idempotency-Key header to make retries safe.", "x-chirpy-scope": "write", "x-chirpy-area": "media", "x-chirpy-title": "Design poster", "x-chirpy-hints": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "poster", "infographic", "carousel" ] }, "platformSize": { "type": "string", "enum": [ "instagram_square", "instagram_portrait", "story", "linkedin_horizontal", "facebook_post", "a4_poster" ] }, "headline": { "type": "string", "description": "Poster: main line" }, "supportingText": { "type": "string", "description": "Poster: one or two short lines" }, "offer": { "type": "string" }, "dateTime": { "type": "string" }, "cta": { "type": "string" }, "contactInfo": { "type": "string" }, "notes": { "type": "string", "description": "Style or layout notes" }, "title": { "type": "string", "description": "Infographic title" }, "subtitle": { "type": "string" }, "stats": { "type": "array", "description": "Infographic: 2 to 8 figures", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label", "value" ], "additionalProperties": false } }, "source": { "type": "string", "description": "Infographic: where the figures come from" }, "topic": { "type": "string", "description": "Carousel: what it is about" }, "audience": { "type": "string" }, "slides": { "type": "array", "description": "Carousel: 3 to 10 slides, text rendered on each", "items": { "type": "object", "properties": { "role": { "type": "string" }, "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false } }, "referenceFileIds": { "type": "array", "items": { "type": "integer" }, "maxItems": 5, "description": "Up to 5 Media Library image fileIds to use as references: the user's photos, product or style to follow. Use the ids of images the user attached in this chat, or ones you found with list_media and look_at_media." } }, "required": [ "kind" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/make_video": { "post": { "operationId": "make_video", "tags": [ "Media" ], "summary": "Starts an AI video (about 10 seconds, 16:9 or 9:16) from a prompt, or animates 1 to 5 Media Library images. Uses one video from the monthly allowance. Poll video_status for the result.", "description": "Starts an AI video (about 10 seconds, 16:9 or 9:16) from a prompt, or animates 1 to 5 Media Library images. Uses one video from the monthly allowance. Poll video_status for the result.\n\nRequires the `write` scope. Send an Idempotency-Key header to make retries safe.", "x-chirpy-scope": "write", "x-chirpy-area": "media", "x-chirpy-title": "Make video", "x-chirpy-hints": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string" }, "aspectRatio": { "type": "string", "enum": [ "16:9", "9:16" ] }, "negativePrompt": { "type": "string", "description": "Things to avoid in the video" }, "imageFileIds": { "type": "array", "items": { "type": "integer" }, "maxItems": 5, "description": "Media Library image ids, 1 to 5: the first is the opening frame, the rest are references to include" }, "videoFileId": { "type": "integer", "description": "A Media Library video to edit (instead of images)" }, "framing": { "type": "string", "enum": [ "fit", "fill" ], "description": "fit keeps the whole image on a blurred backdrop (default); fill crops to fill the frame" } }, "required": [ "prompt" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/video_status": { "post": { "operationId": "video_status", "tags": [ "Media" ], "summary": "Your AI video allowance and recent AI videos with their status (queued, processing, completed, failed).", "description": "Your AI video allowance and recent AI videos with their status (queued, processing, completed, failed).\n\nRequires the `read` scope.", "x-chirpy-scope": "read", "x-chirpy-area": "media", "x-chirpy-title": "Video status", "x-chirpy-hints": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "description": "One video's job id, for its current status" } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/manage_media": { "post": { "operationId": "manage_media", "tags": [ "Media" ], "summary": "Organises the Media Library: tag, move, delete files, and create, rename or delete folders. Deleting removes files for good.", "description": "Organises the Media Library: tag, move, delete files, and create, rename or delete folders. Deleting removes files for good.\n\nRequires the `publish` scope. Send an Idempotency-Key header to make retries safe.", "x-chirpy-scope": "publish", "x-chirpy-area": "media", "x-chirpy-title": "Manage media", "x-chirpy-hints": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "tag", "move", "delete", "create_folder", "rename_folder", "delete_folder" ] }, "fileIds": { "type": "array", "items": { "type": "integer" }, "maxItems": 50 }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 20 }, "folderId": { "type": "integer" }, "parentFolderId": { "type": "integer" }, "name": { "type": "string", "maxLength": 100 } }, "required": [ "action" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/list_brand_kits": { "post": { "operationId": "list_brand_kits", "tags": [ "Brand Kits" ], "summary": "The Brand Kits you can use, with id, name and business name.", "description": "The Brand Kits you can use, with id, name and business name.\n\nRequires the `read` scope.", "x-chirpy-scope": "read", "x-chirpy-area": "brand_kits", "x-chirpy-title": "List brand kits", "x-chirpy-hints": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/get_brand_kit": { "post": { "operationId": "get_brand_kit", "tags": [ "Brand Kits" ], "summary": "One Brand Kit's saved fields, logos and images. Defaults to your default kit.", "description": "One Brand Kit's saved fields, logos and images. Defaults to your default kit.\n\nRequires the `read` scope.", "x-chirpy-scope": "read", "x-chirpy-area": "brand_kits", "x-chirpy-title": "Get brand kit", "x-chirpy-hints": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kitId": { "type": "integer" } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/update_brand_kit": { "post": { "operationId": "update_brand_kit", "tags": [ "Brand Kits" ], "summary": "Changes a Brand Kit's fields, colours or images. Read it with get_brand_kit first.", "description": "Changes a Brand Kit's fields, colours or images. Read it with get_brand_kit first.\n\nRequires the `write` scope. Send an Idempotency-Key header to make retries safe.", "x-chirpy-scope": "write", "x-chirpy-area": "brand_kits", "x-chirpy-title": "Update brand kit", "x-chirpy-hints": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kitId": { "type": "integer" }, "action": { "type": "string", "enum": [ "update", "set_default", "add_logo", "add_image", "remove_item", "delete" ] }, "name": { "type": "string" }, "businessName": { "type": "string" }, "businessType": { "type": "string" }, "brandDescription": { "type": "string" }, "preferredTone": { "type": "string" }, "targetAudience": { "type": "string" }, "hashtagStrategy": { "type": "string" }, "website": { "type": "string" }, "contactEmail": { "type": "string" }, "contactPhone": { "type": "string" }, "address": { "type": "string" }, "link": { "type": "string" }, "keyMessages": { "type": "array", "items": { "type": "string" } }, "brandValues": { "type": "array", "items": { "type": "string" } }, "contentThemes": { "type": "array", "items": { "type": "string" } }, "colors": { "type": "array", "maxItems": 8, "items": { "type": "object", "properties": { "hex": { "type": "string" }, "name": { "type": "string" } }, "required": [ "hex" ], "additionalProperties": false } }, "includePhone": { "type": "boolean" }, "includeAddress": { "type": "boolean" }, "includeWebsite": { "type": "boolean" }, "includeLink": { "type": "boolean" }, "includeEmail": { "type": "boolean" }, "fileId": { "type": "integer" }, "itemId": { "type": "integer" } }, "required": [ "action" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/list_campaigns": { "post": { "operationId": "list_campaigns", "tags": [ "Campaigns" ], "summary": "Campaigns across your team with name, status, dates and post counts.", "description": "Campaigns across your team with name, status, dates and post counts.\n\nRequires the `read` scope.", "x-chirpy-scope": "read", "x-chirpy-area": "campaigns", "x-chirpy-title": "List campaigns", "x-chirpy-hints": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/get_campaign": { "post": { "operationId": "get_campaign", "tags": [ "Campaigns" ], "summary": "One campaign in full: settings, plan and posts.", "description": "One campaign in full: settings, plan and posts.\n\nRequires the `read` scope.", "x-chirpy-scope": "read", "x-chirpy-area": "campaigns", "x-chirpy-title": "Get campaign", "x-chirpy-hints": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "campaignId": { "type": "integer" } }, "required": [ "campaignId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/create_campaign": { "post": { "operationId": "create_campaign", "tags": [ "Campaigns" ], "summary": "Saves a campaign draft with a name, goal, brief and optional offer, dates, cadence and accounts. It does not write or schedule posts; use manage_campaign for that.", "description": "Saves a campaign draft with a name, goal, brief and optional offer, dates, cadence and accounts. It does not write or schedule posts; use manage_campaign for that.\n\nRequires the `write` scope. Send an Idempotency-Key header to make retries safe.", "x-chirpy-scope": "write", "x-chirpy-area": "campaigns", "x-chirpy-title": "Create campaign", "x-chirpy-hints": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "goal": { "type": "string", "enum": [ "awareness", "engagement", "traffic", "leads", "sales", "launch", "event" ] }, "brief": { "type": "string", "description": "What the campaign is about, its key message and audience" }, "offer": { "type": "string" }, "startDate": { "type": "string", "description": "YYYY-MM-DD" }, "cadence": { "type": "string", "enum": [ "daily", "every other day", "3x per week", "weekly" ] }, "postCount": { "type": "integer", "minimum": 1, "maximum": 30 }, "accountIds": { "type": "array", "items": { "type": "integer" } }, "tone": { "type": "string" }, "teamId": { "type": "integer", "description": "Only when the user is in more than one team: the organisation id the campaign belongs to (ask the user which team)." } }, "required": [ "name", "goal", "brief" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/manage_campaign": { "post": { "operationId": "manage_campaign", "tags": [ "Campaigns" ], "summary": "Runs one step of the campaign flow: update, plan, write posts, and the other campaign actions. Planning and writing use AI credits.", "description": "Runs one step of the campaign flow: update, plan, write posts, and the other campaign actions. Planning and writing use AI credits.\n\nRequires the `publish` scope. Send an Idempotency-Key header to make retries safe.", "x-chirpy-scope": "publish", "x-chirpy-area": "campaigns", "x-chirpy-title": "Manage campaign", "x-chirpy-hints": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "campaignId": { "type": "integer" }, "action": { "type": "string", "enum": [ "update", "plan", "write_posts", "edit_brief", "regenerate_brief", "delete_brief", "schedule_posts", "unschedule_posts", "unschedule_all", "undo_plan", "archive", "delete" ] }, "name": { "type": "string", "maxLength": 120 }, "goal": { "type": "string", "enum": [ "awareness", "engagement", "traffic", "leads", "sales", "launch", "event" ] }, "brief": { "type": "string", "maxLength": 4000 }, "offer": { "type": "string", "maxLength": 1000 }, "startDate": { "type": "string", "description": "YYYY-MM-DD" }, "cadence": { "type": "string", "enum": [ "daily", "every other day", "3x per week", "weekly" ] }, "postCount": { "type": "integer", "minimum": 1, "maximum": 30 }, "count": { "type": "integer", "minimum": 1, "maximum": 30, "description": "plan: how many post ideas" }, "tone": { "type": "string", "maxLength": 40 }, "replan": { "type": "boolean" }, "tweak": { "type": "string", "maxLength": 500 }, "briefId": { "type": "integer" }, "briefIds": { "type": "array", "items": { "type": "integer" }, "maxItems": 60 }, "postIds": { "type": "array", "items": { "type": "integer" }, "maxItems": 60 }, "headline": { "type": "string", "maxLength": 200 }, "hook": { "type": "string", "maxLength": 500 }, "angle": { "type": "string", "maxLength": 500 }, "cta": { "type": "string", "maxLength": 200 }, "platform": { "type": "string" }, "publishDate": { "type": "string", "description": "ISO 8601 with offset" } }, "required": [ "campaignId", "action" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/list_inbox": { "post": { "operationId": "list_inbox", "tags": [ "Inbox" ], "summary": "Recent comments, direct messages and reviews across your accounts, with author, platform, text, age and whether they need a reply.", "description": "Recent comments, direct messages and reviews across your accounts, with author, platform, text, age and whether they need a reply.\n\nRequires the `read` scope.", "x-chirpy-scope": "read", "x-chirpy-area": "inbox", "x-chirpy-title": "List inbox", "x-chirpy-hints": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "replied", "all" ] }, "platform": { "type": "string" }, "tag": { "type": "string", "maxLength": 40 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/get_inbox_item": { "post": { "operationId": "get_inbox_item", "tags": [ "Inbox" ], "summary": "One inbox item with its replies and the post it belongs to.", "description": "One inbox item with its replies and the post it belongs to.\n\nRequires the `read` scope.", "x-chirpy-scope": "read", "x-chirpy-area": "inbox", "x-chirpy-title": "Get inbox item", "x-chirpy-hints": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "itemId": { "type": "integer" } }, "required": [ "itemId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/list_saved_replies": { "post": { "operationId": "list_saved_replies", "tags": [ "Inbox" ], "summary": "Your team's saved replies (id, title, text).", "description": "Your team's saved replies (id, title, text).\n\nRequires the `read` scope.", "x-chirpy-scope": "read", "x-chirpy-area": "inbox", "x-chirpy-title": "List saved replies", "x-chirpy-hints": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/send_inbox_reply": { "post": { "operationId": "send_inbox_reply", "tags": [ "Inbox" ], "summary": "Replies to one comment, message or review on the platform.", "description": "Replies to one comment, message or review on the platform.\n\nRequires the `publish` scope. Send an Idempotency-Key header to make retries safe.", "x-chirpy-scope": "publish", "x-chirpy-area": "inbox", "x-chirpy-title": "Send inbox reply", "x-chirpy-hints": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "itemId": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "itemId", "message" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/moderate_inbox": { "post": { "operationId": "moderate_inbox", "tags": [ "Inbox" ], "summary": "Acts on inbox items: like, unlike, hide, unhide, delete on the platform, change status, or classify.", "description": "Acts on inbox items: like, unlike, hide, unhide, delete on the platform, change status, or classify.\n\nRequires the `publish` scope. Send an Idempotency-Key header to make retries safe.", "x-chirpy-scope": "publish", "x-chirpy-area": "inbox", "x-chirpy-title": "Moderate inbox", "x-chirpy-hints": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 30, "items": { "type": "object", "properties": { "itemId": { "type": "integer" }, "action": { "type": "string", "enum": [ "like", "unlike", "hide", "unhide", "delete", "mark_done", "mark_open", "mark_in_progress", "ignore", "classify" ] }, "classification": { "type": "string", "enum": [ "question", "buying_intent", "praise", "complaint", "noise", "solicitation" ] } }, "required": [ "itemId", "action" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/account_performance": { "post": { "operationId": "account_performance", "tags": [ "Analytics" ], "summary": "One account's performance over 7 to 90 days: engagement, top and weakest posts, best days and times, format breakdown.", "description": "One account's performance over 7 to 90 days: engagement, top and weakest posts, best days and times, format breakdown.\n\nRequires the `read` scope.", "x-chirpy-scope": "read", "x-chirpy-area": "analytics", "x-chirpy-title": "Account performance", "x-chirpy-hints": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "integer" }, "days": { "type": "integer", "minimum": 7, "maximum": 90 } }, "required": [ "accountId" ], "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/weekly_brief": { "post": { "operationId": "weekly_brief", "tags": [ "Analytics" ], "summary": "The latest Weekly Brief: score and change, summary, wins, risks and suggested actions.", "description": "The latest Weekly Brief: score and change, summary, wins, risks and suggested actions.\n\nRequires the `read` scope.", "x-chirpy-scope": "read", "x-chirpy-area": "analytics", "x-chirpy-title": "Weekly brief", "x-chirpy-hints": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/BrandKit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer chirpy_sk_..." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string up to 128 characters. Retrying with the same key returns the first result instead of acting twice. Kept for 24 hours.", "schema": { "type": "string", "maxLength": 128 } }, "BrandKit": { "name": "Chirpy-Brand-Kit", "in": "header", "required": false, "description": "Brand Kit id to work with (from list_brand_kits). Defaults to your default kit.", "schema": { "type": "integer" } } }, "responses": { "Ok": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "Error": { "description": "Failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Ok": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "description": "The action's result." }, "actions": { "type": "array", "description": "Things the call carried out (for example a scheduled post or a generated image), with their outcome.", "items": { "type": "object" } } } }, "Error": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "const": false }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "rate_limited", "insufficient_credits", "limit_reached", "tool_error", "internal_error" ] }, "message": { "type": "string" } } } } } } } }