{"openapi":"3.1.0","info":{"title":"PostSocials REST API","version":"1.0.0","description":"Unified social media publishing API. Publish videos, Reels, Shorts, photos, carousels, and text across 14 social networks with one HTTP call.","contact":{"name":"PostSocials API Support","url":"https://postsocials.dev/docs"}},"servers":[{"url":"https://postsocials.dev/api/v1","description":"PostSocials Public REST API v1"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ps_live_...","description":"Create a scoped API key in Dashboard -> Developers and pass it as `Authorization: Bearer ps_live_...`."}},"schemas":{"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["BAD_REQUEST","VALIDATION_ERROR","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","CONFLICT","QUOTA_EXCEEDED","PLAN_UPGRADE_REQUIRED","RATE_LIMITED","INTERNAL_ERROR"]},"message":{"type":"string"},"details":{"type":"object"}}}}},"PlatformId":{"type":"string","enum":["tiktok","instagram","youtube","x","linkedin","facebook","threads","pinterest","reddit","bluesky","google_business","mastodon","discord","telegram"]},"ApiKeyScope":{"type":"string","enum":["uploads:write","uploads:read","profiles:read","profiles:write","analytics:read"]},"WebhookEvent":{"type":"string","enum":["upload.completed","upload.failed","upload.partial_failure","profile.connected","profile.disconnected"]},"UsageResponse":{"type":"object","properties":{"planId":{"type":"string","enum":["free","basic","professional","advanced","business"]},"planName":{"type":"string"},"uploadsUsed":{"type":"integer"},"uploadsLimit":{"type":["integer","null"]},"remainingUploads":{"type":["integer","null"]},"periodKey":{"type":"string","example":"2026-11"},"resetsAt":{"type":"string","format":"date-time"},"profilesUsed":{"type":"integer"},"profilesLimit":{"type":"integer"},"seatsUsed":{"type":"integer"},"seatsLimit":{"type":"integer"}}},"Profile":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string"},"connectedPlatforms":{"type":"array","items":{"$ref":"#/components/schemas/PlatformId"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"CreateProfileRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":80},"description":{"type":"string","maxLength":280}}},"CreateConnectUrlRequest":{"type":"object","properties":{"redirectUrl":{"type":"string","format":"uri"},"expiresInMinutes":{"type":"integer","minimum":5,"maximum":1440,"default":60}}},"MediaItem":{"type":"object","required":["url","mimeType","sizeBytes"],"properties":{"storagePath":{"type":"string"},"url":{"type":"string","format":"uri"},"mimeType":{"type":"string","example":"video/mp4"},"sizeBytes":{"type":"integer","example":14500000},"durationSec":{"type":"number","example":42}}},"CreateUploadRequest":{"type":"object","required":["profileId","mediaType","targetPlatforms"],"properties":{"profileId":{"type":"string","example":"prof_01abc"},"mediaType":{"type":"string","enum":["video","photo","carousel","text"]},"mediaItems":{"type":"array","items":{"$ref":"#/components/schemas/MediaItem"}},"title":{"type":"string","maxLength":300},"caption":{"type":"string","maxLength":63206},"targetPlatforms":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/PlatformId"}},"scheduledAt":{"type":["string","null"],"format":"date-time","description":"Optional ISO-8601 UTC timestamp in the future. Omit to publish immediately."},"platformConfig":{"type":"object","description":"Per-platform overrides (youtube, tiktok, instagram, reddit, x, linkedin, facebook, pinterest)."}}},"UploadJob":{"type":"object","properties":{"id":{"type":"string"},"profileId":{"type":"string"},"source":{"type":"string","enum":["dashboard","api"]},"mediaType":{"type":"string","enum":["video","photo","carousel","text"]},"title":{"type":"string"},"caption":{"type":"string"},"targetPlatforms":{"type":"array","items":{"$ref":"#/components/schemas/PlatformId"}},"status":{"type":"string","enum":["draft","scheduled","queued","processing","completed","partial_failure","failed"]},"scheduledAt":{"type":["string","null"],"format":"date-time"},"publishedAt":{"type":["string","null"],"format":"date-time"},"platformResults":{"type":"object"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}},"paths":{"/usage":{"get":{"summary":"Get current plan and quota usage","operationId":"getUsage","tags":["Usage"],"responses":{"200":{"description":"Current billing period usage and profile/seat limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/profiles":{"get":{"summary":"List all profiles","operationId":"listProfiles","tags":["Profiles"],"responses":{"200":{"description":"Array of workspace profiles","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Profile"}}}}}}}}},"post":{"summary":"Create a profile","operationId":"createProfile","tags":["Profiles"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProfileRequest"}}}},"responses":{"201":{"description":"Created profile","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Profile"}}}}}},"403":{"description":"Profile cap exceeded for current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/profiles/{id}/connect-url":{"post":{"summary":"Generate Whitelabel Connect Portal URL","description":"Generates a single-use hosted OAuth Connect link styled with your workspace whitelabel settings. Requires the Professional plan or higher.","operationId":"createProfileConnectUrl","tags":["Whitelabel"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateConnectUrlRequest"}}}},"responses":{"201":{"description":"Single-use hosted connect URL","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"connectUrl":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}}}}}},"403":{"description":"Plan upgrade required (Professional+)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/uploads":{"get":{"summary":"List upload jobs","operationId":"listUploads","tags":["Uploads"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"profileId","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of uploads"}}},"post":{"summary":"Create and publish (or schedule) a multi-platform upload","operationId":"createUpload","tags":["Uploads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUploadRequest"}}}},"responses":{"201":{"description":"Upload created and dispatched or scheduled","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UploadJob"},"usage":{"type":"object","properties":{"periodKey":{"type":"string"},"used":{"type":"integer"},"limit":{"type":["integer","null"]}}}}}}}},"402":{"description":"Monthly quota exceeded on Free plan (30 uploads/month)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Target platform requires a higher plan (e.g., TikTok on Basic+)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/uploads/{id}":{"get":{"summary":"Get upload job status & per-platform results","operationId":"getUpload","tags":["Uploads"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Upload job details"},"404":{"description":"Upload not found"}}},"delete":{"summary":"Cancel a scheduled upload or delete a draft","operationId":"deleteUpload","tags":["Uploads"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Upload canceled/deleted"}}}},"/analytics":{"get":{"summary":"Query aggregated analytics metrics","operationId":"getAnalytics","tags":["Analytics"],"parameters":[{"name":"profileId","in":"query","schema":{"type":"string"}},{"name":"platform","in":"query","schema":{"$ref":"#/components/schemas/PlatformId"}},{"name":"from","in":"query","schema":{"type":"string","example":"2026-10-01"}},{"name":"to","in":"query","schema":{"type":"string","example":"2026-11-19"}}],"responses":{"200":{"description":"Aggregated KPIs, daily series, and platform breakdown"}}}}}}