{"openapi":"3.1.0","info":{"title":"Octopost REST API","version":"1.0.0","description":"Post, thread, schedule and queue social posts. X is live; Threads opens after Meta approval; Bluesky, LinkedIn and Mastodon are in testing. The same features are available as an MCP server at https://octopost.ink/mcp. Request fields are camelCase; snake_case aliases (scheduled_for, queue_status, media) are accepted on create.","contact":{"name":"Octopost (Great Work LLC)","email":"hello@greatwork.company","url":"https://octopost.ink"},"termsOfService":"https://octopost.ink/terms"},"servers":[{"url":"https://octopost.ink"}],"security":[{"bearer":[]}],"externalDocs":{"url":"https://octopost.ink/docs/api/overview.md"},"paths":{"/api/posts":{"get":{"summary":"List posts","description":"All posts in the account, newest first. Filter queued or approval-pending posts with `status`.","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["queued","pending"]}}],"responses":{"200":{"description":"Posts","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"posts":{"type":"array","items":{"$ref":"#/components/schemas/Post"}}}}}}},"401":{"description":"Missing or invalid API key. Send `Authorization: Bearer op_...` with the key from https://octopost.ink/dashboard/api-keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per minute per IP; publishing 50/hour). Retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error. Safe to retry; email hello@greatwork.company if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a post (draft, scheduled, queued, or published now)","description":"Draft by default. Set `published: true` to publish now, `scheduledFor` to publish at a time, or `queueStatus` to add it to the interval queue (`pending` waits for approval).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePost"}}}},"responses":{"201":{"description":"Created. `publishResults` is present when published now.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"post":{"$ref":"#/components/schemas/Post"},"publishResults":{"type":"array","items":{"$ref":"#/components/schemas/PublishResult"}}}}}}},"400":{"description":"Validation error: the message names the field (for example scheduledFor without a timezone offset, or text over a network limit).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key. Send `Authorization: Bearer op_...` with the key from https://octopost.ink/dashboard/api-keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No active plan (finish the $1 trial checkout at https://octopost.ink/dashboard/billing) or the monthly X allowance is used up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per minute per IP; publishing 50/hour). Retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error. Safe to retry; email hello@greatwork.company if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/posts/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Post id from create or list."}],"get":{"summary":"Get a post","responses":{"200":{"description":"The post","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"$ref":"#/components/schemas/Post"}}}}}},"401":{"description":"Missing or invalid API key. Send `Authorization: Bearer op_...` with the key from https://octopost.ink/dashboard/api-keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No post with this id in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per minute per IP; publishing 50/hour). Retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error. Safe to retry; email hello@greatwork.company if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Update a draft or scheduled post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePost"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"$ref":"#/components/schemas/Post"}}}}}},"400":{"description":"Validation error, or the post is already published.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key. Send `Authorization: Bearer op_...` with the key from https://octopost.ink/dashboard/api-keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No post with this id in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per minute per IP; publishing 50/hour). Retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error. Safe to retry; email hello@greatwork.company if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a post","parameters":[{"name":"deleteFromPlatforms","in":"query","schema":{"type":"boolean","default":true},"description":"Also delete published copies where the network allows it."}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key. Send `Authorization: Bearer op_...` with the key from https://octopost.ink/dashboard/api-keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No post with this id in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per minute per IP; publishing 50/hour). Retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error. Safe to retry; email hello@greatwork.company if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/posts/{id}/publish":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Post id from create or list."}],"post":{"summary":"Publish a draft now","responses":{"200":{"description":"Per-network results","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Already published.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key. Send `Authorization: Bearer op_...` with the key from https://octopost.ink/dashboard/api-keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No active plan or X allowance used up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No post with this id in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per minute per IP; publishing 50/hour). Retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error. Safe to retry; email hello@greatwork.company if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/posts/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Post id from create or list."}],"post":{"summary":"Approve a post waiting for approval (queueStatus pending)","responses":{"200":{"description":"Moved to the queue","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The post is not pending approval.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key. Send `Authorization: Bearer op_...` with the key from https://octopost.ink/dashboard/api-keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No post with this id in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per minute per IP; publishing 50/hour). Retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error. Safe to retry; email hello@greatwork.company if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/posts/{id}/retry":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Post id from create or list."}],"post":{"summary":"Retry the networks that failed","responses":{"200":{"description":"Retry results","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Nothing failed on this post.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key. Send `Authorization: Bearer op_...` with the key from https://octopost.ink/dashboard/api-keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No post with this id in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per minute per IP; publishing 50/hour). Retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error. Safe to retry; email hello@greatwork.company if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/accounts":{"get":{"summary":"List connected social accounts","responses":{"200":{"description":"Accounts","content":{"application/json":{"schema":{"type":"object","properties":{"accounts":{"type":"array","items":{"$ref":"#/components/schemas/Account"}}}}}}},"401":{"description":"Missing or invalid API key. Send `Authorization: Bearer op_...` with the key from https://octopost.ink/dashboard/api-keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per minute per IP; publishing 50/hour). Retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error. Safe to retry; email hello@greatwork.company if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/queue-settings":{"get":{"summary":"Get queue settings","responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueueSettings"}}}},"401":{"description":"Missing or invalid API key. Send `Authorization: Bearer op_...` with the key from https://octopost.ink/dashboard/api-keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per minute per IP; publishing 50/hour). Retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error. Safe to retry; email hello@greatwork.company if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Update queue settings","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueueSettings"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueueSettings"}}}},"400":{"description":"Validation error (hours 0-23, interval 1-24).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key. Send `Authorization: Bearer op_...` with the key from https://octopost.ink/dashboard/api-keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (per minute per IP; publishing 50/hour). Retry after the `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error. Safe to retry; email hello@greatwork.company if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Octopost API key, starts with op_. `x-api-key: op_...` also works."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"fix":{"type":"string"},"details":{}},"required":["error"]},"Platform":{"type":"string","enum":["twitter","threads","bluesky","linkedin","mastodon"],"description":"twitter is live; threads after Meta approval; bluesky, linkedin, mastodon in testing."},"Media":{"oneOf":[{"type":"string","format":"uri"},{"type":"object","properties":{"url":{"type":"string","format":"uri"},"altText":{"type":"string","maxLength":1000}},"required":["url"]}]},"CreatePost":{"type":"object","required":["content","platforms"],"properties":{"content":{"type":"string","minLength":1,"maxLength":5000,"description":"Main post text. X counts links as 23 characters."},"platforms":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Platform"}},"scheduledFor":{"type":["string","null"],"format":"date-time","description":"ISO 8601 with a timezone offset."},"published":{"type":"boolean","default":false,"description":"true = publish now."},"queueStatus":{"type":["string","null"],"enum":["queued","pending",null],"description":"queued = interval queue; pending = wait for approval."},"mediaUrls":{"type":"array","items":{"$ref":"#/components/schemas/Media"},"maxItems":4},"segments":{"type":"array","maxItems":24,"description":"Thread replies after the main post.","items":{"type":"object","required":["content"],"properties":{"content":{"type":"string","minLength":1,"maxLength":5000},"mediaUrls":{"type":"array","items":{"$ref":"#/components/schemas/Media"}}}}},"poll":{"type":"object","properties":{"options":{"type":"array","minItems":2,"maxItems":4,"items":{"type":"string","maxLength":25}},"durationMinutes":{"type":"integer","minimum":5,"maximum":10080}}}}},"Post":{"type":"object","properties":{"id":{"type":"string"},"content":{"type":"string"},"platforms":{"type":"array","items":{"type":"string"}},"scheduledFor":{"type":["string","null"]},"published":{"type":"boolean"},"queueStatus":{"type":["string","null"]},"platformPostIds":{"type":["object","null"],"description":"Per network: id, url, or error."},"createdAt":{"type":"string"}}},"PublishResult":{"type":"object","properties":{"platform":{"type":"string"},"success":{"type":"boolean"},"postUrl":{"type":"string"},"error":{"type":"string","description":"What failed and what to do next."}}},"Account":{"type":"object","properties":{"id":{"type":"string"},"platform":{"type":"string"},"accountName":{"type":"string"},"needsReauth":{"type":"boolean"}}},"QueueSettings":{"type":"object","properties":{"enabled":{"type":"boolean"},"intervalHours":{"type":"integer","minimum":1,"maximum":24},"startHour":{"type":"integer","minimum":0,"maximum":23},"endHour":{"type":"integer","minimum":0,"maximum":23},"timezone":{"type":"string"}}}}}}