{"openapi":"3.1.0","info":{"title":"PostAgent API","version":"1.0.0","description":"Social media scheduling API built for AI agents. One POST schedules a post to any combination of X, LinkedIn, Facebook, Instagram, YouTube and TikTok."},"servers":[{"url":"https://postagent.pro/api/v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"sk_live_...","description":"Create keys at /developers."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","idempotency_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","code","message"]}}},"MediaItem":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"type":{"type":"string","enum":["image","video"]}},"required":["url","type"]},"Target":{"oneOf":[{"type":"string","enum":["x","linkedin","facebook","instagram","youtube","tiktok","bluesky"]},{"type":"object","properties":{"platform":{"type":"string","enum":["x","linkedin","facebook","instagram","youtube","tiktok","bluesky"]},"account_id":{"type":"string","description":"Required when more than one account of this platform is connected. From GET /accounts."},"content":{"type":"string","description":"Per-platform content override."},"options":{"type":"object","description":"Platform-specific options, e.g. {\"privacy_level\": \"SELF_ONLY\"} for TikTok, {\"title\", \"privacy_status\"} for YouTube."}},"required":["platform"]}]},"PostTarget":{"type":"object","properties":{"id":{"type":"string"},"platform":{"type":"string","enum":["x","linkedin","facebook","instagram","youtube","tiktok","bluesky"]},"account_id":{"type":"string","nullable":true},"account_name":{"type":"string"},"status":{"type":"string","enum":["scheduled","publishing","published","failed","canceled"]},"content":{"type":"string","nullable":true},"options":{"type":"object","nullable":true},"simulated":{"type":"boolean"},"platform_post_id":{"type":"string","nullable":true},"platform_post_url":{"type":"string","nullable":true},"error":{"type":"string","nullable":true},"attempt_count":{"type":"integer"},"published_at":{"type":"string","format":"date-time","nullable":true}}},"Post":{"type":"object","properties":{"id":{"type":"string","example":"post_x1y2z3"},"object":{"type":"string","const":"post"},"content":{"type":"string"},"media":{"type":"array","items":{"$ref":"#/components/schemas/MediaItem"}},"status":{"type":"string","enum":["draft","scheduled","publishing","published","partial","failed","canceled"]},"schedule_at":{"type":"string","format":"date-time","nullable":true},"published_at":{"type":"string","format":"date-time","nullable":true},"source":{"type":"string","enum":["app","api"]},"created_at":{"type":"string","format":"date-time"},"targets":{"type":"array","items":{"$ref":"#/components/schemas/PostTarget"}}}},"Account":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"account"},"platform":{"type":"string","enum":["x","linkedin","facebook","instagram","youtube","tiktok","bluesky"]},"name":{"type":"string"},"avatar_url":{"type":"string","nullable":true},"simulated":{"type":"boolean"},"connected_at":{"type":"string","format":"date-time"}}},"CreatePost":{"type":"object","properties":{"content":{"type":"string","maxLength":63206},"media":{"type":"array","items":{"$ref":"#/components/schemas/MediaItem"},"maxItems":10},"targets":{"type":"array","items":{"$ref":"#/components/schemas/Target"},"minItems":1},"schedule_at":{"type":"string","format":"date-time","description":"ISO 8601. Omit to publish immediately."},"status":{"type":"string","enum":["draft"],"description":"Pass \"draft\" to hold the post without scheduling."},"idempotency_key":{"type":"string","maxLength":255}},"required":["content","targets"]},"UpdatePost":{"type":"object","properties":{"content":{"type":"string"},"media":{"type":"array","items":{"$ref":"#/components/schemas/MediaItem"}},"targets":{"type":"array","items":{"$ref":"#/components/schemas/Target"}},"schedule_at":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["draft","scheduled"]}}}}},"paths":{"/posts":{"post":{"summary":"Create a post (draft, scheduled, or publish now)","description":"The hero endpoint: fan one post out to any number of connected platforms. Send an Idempotency-Key header to make retries safe.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePost"}}}},"responses":{"200":{"description":"Idempotent replay — the original post, with header Idempotency-Replayed: true","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List posts","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"scheduled_after","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"scheduled_before","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"starting_after","in":"query","schema":{"type":"string"},"description":"Post id cursor"}],"responses":{"200":{"description":"List","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Post"}},"has_more":{"type":"boolean"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/posts/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a post with per-target status","responses":{"200":{"description":"Post","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update a draft or scheduled post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePost"}}}},"responses":{"200":{"description":"Updated post","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Cancel a scheduled post or delete a draft/failed post","responses":{"200":{"description":"Canceled post, or {id, object: \"post\", deleted: true} when hard-deleted"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/posts/{id}/publish":{"post":{"summary":"Publish a draft or scheduled post now","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Post (publishing kicks off immediately)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/accounts":{"get":{"summary":"List connected social accounts (valid targets)","responses":{"200":{"description":"List","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Account"}},"has_more":{"type":"boolean"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/platforms":{"get":{"summary":"Platform capabilities (public)","security":[],"responses":{"200":{"description":"List of platforms with char limits, media support and simulated flag"}}}}}}