{ "openapi": "3.1.0", "info": { "title": "Social0 API", "version": "1.0.0", "summary": "Publish and schedule social posts across 9 networks", "description": "Programmatic access to Social0 publishing. Authenticate with `Authorization: Bearer sk_live_...` (API key) or OAuth 2.0 (MCP connector).\n\n## Versioning\nThe public API is versioned in the URL (`/v1`). Additive changes may ship in v1. Breaking changes get a new prefix or a Sunset window. Policy: https://social0.app/api-versioning.md\n\nDeprecated operations are marked `deprecated: true` in this spec and return `Deprecation: true`. When a removal date is known, responses include `Sunset`.\n\n## Rate limits\nResponses include `RateLimit`, `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, and `RateLimit-Policy`. 429 responses also include `Retry-After`.\n\nFree 60/hour, Starter 300, Growth 1000, Pro 5000, Max 10000.\n\n## Async publish\n`POST /v1/posts/publish` and `POST /v1/posts/{id}/publish` return `202 Accepted` with `Location: /v1/jobs/{tracking_id}` and a `tracking_id` in the body. Poll `GET /v1/jobs/{tracking_id}` until `completed`, `failed`, or `partial`.\n\n## Examples\n\n### cURL - list accounts\n```bash\ncurl https://api.social0.app/v1/accounts \\\n -H \"Authorization: Bearer sk_live_YOUR_KEY\"\n```\n\n### JavaScript - create and publish\n```javascript\nconst res = await fetch('https://api.social0.app/v1/posts/publish', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer sk_live_YOUR_KEY',\n 'Content-Type': 'application/json',\n 'Idempotency-Key': crypto.randomUUID(),\n },\n body: JSON.stringify({\n content: 'Hello from the API!',\n platforms: ['account-uuid-here'],\n }),\n});\nconst { tracking_id } = await res.json();\n```\n\n## Errors\nEvery 4xx and 5xx response uses a typed error object `{ \"error\": { \"code\": string, \"message\": string, \"details\"?: object } }`. The same payload is also documented as RFC 9457 `application/problem+json` (`type`, `title`, `status`, `detail`). 401 responses include `WWW-Authenticate`. 429 responses include `Retry-After`.", "termsOfService": "https://social0.app/terms", "contact": { "name": "Social0 support", "email": "support@social0.app", "url": "https://social0.app/contact" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.social0.app", "description": "Production" } ], "tags": [ { "name": "Auth", "description": "Authenticated user profile" }, { "name": "Accounts", "description": "Connected social accounts" }, { "name": "Posts", "description": "Drafts, schedules, and publishes" }, { "name": "Jobs", "description": "Async publish job status" }, { "name": "Media", "description": "Uploads for image and video posts" }, { "name": "Webhooks", "description": "Outbound event subscriptions" }, { "name": "Analytics", "description": "Live metrics for posts published through Social0" }, { "name": "Inbox", "description": "Comments and DMs on connected accounts" } ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "social0:read", "social0:write" ] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Social0 API key (`sk_live_...`). Keys currently have full account access; prefer OAuth scopes when using MCP." }, "oauth2": { "type": "oauth2", "description": "OAuth 2.0 authorization code + PKCE used by the hosted MCP connector. Request the narrowest scopes you need.", "flows": { "authorizationCode": { "authorizationUrl": "https://mcp.social0.app/oauth/authorize", "tokenUrl": "https://mcp.social0.app/oauth/token", "refreshUrl": "https://mcp.social0.app/oauth/token", "scopes": { "me:read": "Read the authenticated user profile and plan.", "accounts:read": "List connected social accounts.", "accounts:write": "Start OAuth connect and disconnect social accounts.", "posts:read": "List and get posts and publication events.", "posts:write": "Create, update, delete, schedule, and publish posts.", "media:write": "Presign, confirm, and read media uploads.", "jobs:read": "Read publish job status and event streams.", "webhooks:read": "List webhook subscriptions.", "webhooks:write": "Create, update, and delete webhook subscriptions.", "social0:read": "Umbrella read access (MCP default).", "social0:write": "Umbrella write access (MCP default)." } } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique request ID for debugging" }, "Location": { "schema": { "type": "string" }, "description": "URL to poll for an async job" }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Client-supplied key so retries do not double-publish." }, "WindowRange": { "name": "range", "in": "query", "required": false, "description": "Lookback window. `custom` uses `since`/`until` (max 365 days).", "schema": { "type": "string", "enum": [ "7d", "14d", "28d", "90d", "365d", "custom" ], "default": "7d" } }, "WindowSince": { "name": "since", "in": "query", "required": false, "description": "ISO 8601 start, only used with `range=custom`.", "schema": { "type": "string", "format": "date-time" } }, "WindowUntil": { "name": "until", "in": "query", "required": false, "description": "ISO 8601 end, only used with `range=custom`.", "schema": { "type": "string", "format": "date-time" } }, "Fresh": { "name": "fresh", "in": "query", "required": false, "description": "Bypass warm cache and hit the platform APIs. Entries younger than 90s are still served from cache to protect shared platform quotas.", "schema": { "type": "boolean", "default": false } }, "InboxBefore": { "name": "before", "in": "query", "required": false, "description": "Cursor from the previous response's `next_before`.", "schema": { "type": "string" } }, "InboxLimit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 24 } }, "AccountIdQuery": { "name": "account_id", "in": "query", "required": false, "description": "Restrict to one connected account.", "schema": { "type": "string", "format": "uuid" } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_api_key", "api_key_revoked", "api_key_expired", "unauthorized", "forbidden", "not_found", "validation_error", "rate_limit_exceeded", "idempotency_conflict", "limit_exceeded", "not_implemented", "internal_error" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } }, "User": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "plan": { "type": "string" }, "timezone": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "api_key": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string" } } } } }, "Account": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "profile_image_url": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "token_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "token_status": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "AccountList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } } }, "ConnectUrl": { "type": "object", "properties": { "authorization_url": { "type": "string", "format": "uri" } } }, "Post": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "content": { "type": "string" }, "status": { "type": "string" }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "failure_reason": { "type": [ "string", "null" ] }, "media_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "platforms": { "type": "array", "items": { "$ref": "#/components/schemas/Publication" } } } }, "Publication": { "type": "object", "properties": { "publication_id": { "type": "string" }, "connected_account_id": { "type": [ "string", "null" ] }, "platform": { "type": "string" }, "status": { "type": "string" }, "platform_post_id": { "type": [ "string", "null" ] }, "platform_post_url": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] } } }, "PostList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "CreatePostRequest": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "accounts": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "media": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "metadata": { "type": "object", "additionalProperties": true }, "platform_options": { "type": "object", "additionalProperties": true } } }, "CreatedPost": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } } }, "ScheduledPost": { "type": "object", "properties": { "post_id": { "type": "string", "format": "uuid" }, "scheduled_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "example": "scheduled" } } }, "JobQueued": { "type": "object", "properties": { "post_id": { "type": "string", "format": "uuid" }, "tracking_id": { "type": "string" }, "status": { "type": "string" }, "stream_url": { "type": "string" } } }, "Job": { "type": "object", "properties": { "tracking_id": { "type": "string" }, "post_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed", "partial" ] }, "total": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "platform_statuses": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "connected_account_id": { "type": [ "string", "null" ] }, "phase": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] } } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "connected_account_id": { "type": [ "string", "null" ] }, "message": { "type": "string" } } } }, "failure_reason": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] } } }, "PostEvents": { "type": "object", "properties": { "postId": { "type": "string" }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "phase": { "type": "string" }, "platform": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } } } } } }, "PresignRequest": { "type": "object", "required": [ "filename", "content_type", "size_bytes" ], "properties": { "filename": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" } } }, "PresignResponse": { "type": "object", "properties": { "upload_url": { "type": "string", "format": "uri" }, "key": { "type": "string" }, "storage_filename": { "type": "string" } } }, "ConfirmMediaRequest": { "type": "object", "required": [ "key", "storage_filename", "original_filename", "content_type", "size_bytes" ], "properties": { "key": { "type": "string" }, "storage_filename": { "type": "string" }, "original_filename": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" } } }, "Media": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "url": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "secret": { "type": "string", "description": "Returned once, on create." }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When Social0 last attempted a delivery to this endpoint. Null means nothing has been attempted yet." }, "last_delivery_status": { "type": "string", "nullable": true, "enum": [ "delivered", "failed", "blocked", null ] }, "last_delivery_response_status": { "type": "integer", "nullable": true, "description": "HTTP status the endpoint returned on the last attempt, or null if it never responded." }, "last_delivery_error": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WebhookList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } }, "WebhookDelivery": { "type": "object", "description": "One delivery attempt group. Retries of the same event collapse into a single record; `attempts` says how many requests were made.", "properties": { "id": { "type": "string", "format": "uuid" }, "delivery_id": { "type": "string", "format": "uuid", "description": "Payload `id`, sent to the endpoint as X-Social0-Delivery-Id." }, "event": { "type": "string", "enum": [ "post.published", "post.failed", "post.scheduled", "post.deleted", "webhook.test" ] }, "url": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": [ "delivered", "failed", "blocked" ], "description": "`blocked` means Social0 never sent the request — the URL is not a public address, or the signing secret could not be read." }, "response_status": { "type": "integer", "nullable": true }, "attempts": { "type": "integer" }, "duration_ms": { "type": "integer", "nullable": true }, "error": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "WebhookDeliveryList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "next_before": { "type": "string", "format": "date-time", "nullable": true, "description": "Pass as `before` to fetch the next page; null when the page was not full." } } }, "ProblemDetails": { "type": "object", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } } }, "MetricSet": { "type": "object", "description": "Metric values the platform actually reported. `null` means the network does not expose that metric for this post.", "properties": { "views": { "type": "integer", "nullable": true }, "impressions": { "type": "integer", "nullable": true }, "reach": { "type": "integer", "nullable": true }, "likes": { "type": "integer", "nullable": true }, "comments": { "type": "integer", "nullable": true }, "shares": { "type": "integer", "nullable": true }, "reposts": { "type": "integer", "nullable": true }, "quotes": { "type": "integer", "nullable": true }, "saves": { "type": "integer", "nullable": true }, "clicks": { "type": "integer", "nullable": true }, "engagement": { "type": "integer", "description": "likes + comments + shares + reposts + quotes + saves + clicks" } } }, "ReconnectHint": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string", "nullable": true }, "missing_scopes": { "description": "OAuth scopes the account still needs for this feature. The marker `token_expired` means the stored token itself was revoked or expired; reconnect the account either way.", "type": "array", "items": { "type": "string" } } } }, "AnalyticsAccountList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string", "nullable": true }, "profile_image_url": { "type": "string", "nullable": true }, "missing_scopes": { "description": "OAuth scopes the account still needs for this feature. The marker `token_expired` means the stored token itself was revoked or expired; reconnect the account either way.", "type": "array", "items": { "type": "string" } } } } } } }, "PublicationMetrics": { "type": "object", "properties": { "publication_id": { "type": "string", "format": "uuid" }, "post_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "account_id": { "type": "string", "nullable": true }, "account_username": { "type": "string", "nullable": true }, "platform_post_id": { "type": "string", "nullable": true }, "platform_post_url": { "type": "string", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string", "enum": [ "ok", "scope_missing", "unsupported", "error", "no_platform_id", "skipped" ] }, "error": { "type": "string", "nullable": true }, "missing_scopes": { "description": "Scopes missing on the publishing account, or the marker `token_expired` when its token was revoked or expired. Reconnect either way.", "type": "array", "items": { "type": "string" } }, "metrics": { "$ref": "#/components/schemas/MetricSet" } } }, "AnalyticsOverview": { "type": "object", "properties": { "range": { "type": "string" }, "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "fetched_at": { "type": "string", "format": "date-time" }, "sampled": { "type": "boolean", "description": "True when only the most recent `sample_limit` publications were read." }, "sample_limit": { "type": "integer" }, "partial": { "type": "boolean", "description": "True when the live request budget expired before every publication was read." }, "totals": { "$ref": "#/components/schemas/MetricSet" }, "by_platform": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "post_count": { "type": "integer" }, "metrics": { "$ref": "#/components/schemas/MetricSet" } } } }, "series": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "views": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "engagement": { "type": "integer" } } } }, "top_posts": { "type": "array", "items": { "type": "object", "properties": { "post_id": { "type": "string", "format": "uuid" }, "snippet": { "type": "string" }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "platforms": { "type": "array", "items": { "type": "string" } }, "metrics": { "$ref": "#/components/schemas/MetricSet" } } } }, "publications": { "type": "array", "items": { "$ref": "#/components/schemas/PublicationMetrics" } }, "accounts_needing_reconnect": { "type": "array", "items": { "$ref": "#/components/schemas/ReconnectHint" } } } }, "PostAnalytics": { "type": "object", "properties": { "post_id": { "type": "string", "format": "uuid" }, "fetched_at": { "type": "string", "format": "date-time" }, "partial": { "type": "boolean" }, "totals": { "$ref": "#/components/schemas/MetricSet" }, "publications": { "type": "array", "items": { "$ref": "#/components/schemas/PublicationMetrics" } }, "accounts_needing_reconnect": { "type": "array", "items": { "$ref": "#/components/schemas/ReconnectHint" } } } }, "InboxAttachment": { "type": "object", "nullable": true, "properties": { "type": { "type": "string", "enum": [ "image", "video" ] }, "url": { "type": "string" }, "thumbnail_url": { "type": "string", "nullable": true } } }, "InboxComment": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "type": "string" }, "account_id": { "type": "string", "format": "uuid" }, "account_username": { "type": "string", "nullable": true }, "post_id": { "type": "string", "format": "uuid" }, "publication_id": { "type": "string", "format": "uuid", "description": "Required when replying to, liking, or hiding this comment." }, "platform_post_id": { "type": "string" }, "platform_post_url": { "type": "string", "nullable": true }, "post_snippet": { "type": "string" }, "author_name": { "type": "string" }, "author_handle": { "type": "string", "nullable": true }, "text": { "type": "string" }, "attachment": { "$ref": "#/components/schemas/InboxAttachment" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "like_count": { "type": "integer", "nullable": true }, "liked_by_me": { "type": "boolean", "nullable": true }, "parent_id": { "type": "string", "nullable": true }, "can_reply": { "type": "boolean" }, "is_own": { "type": "boolean" } } }, "InboxCommentList": { "type": "object", "properties": { "range": { "type": "string" }, "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "fetched_at": { "type": "string", "format": "date-time" }, "threads": { "type": "array", "items": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/InboxComment" }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/InboxComment" } }, "answered": { "type": "boolean", "description": "True when the connected account already replied in this thread." } } } }, "has_more": { "type": "boolean" }, "next_before": { "type": "string", "nullable": true, "description": "Pass as `before` to page older publications." }, "sampled": { "type": "boolean" }, "sample_limit": { "type": "integer" }, "unsupported": { "type": "array", "items": { "type": "string" } }, "accounts_needing_reconnect": { "type": "array", "items": { "$ref": "#/components/schemas/ReconnectHint" } }, "fetch_errors": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string" }, "platform": { "type": "string" }, "error": { "type": "string" } } } }, "notices": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "message": { "type": "string" } } } } } }, "InboxConversation": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "platform": { "type": "string" }, "account_id": { "type": "string", "format": "uuid" }, "account_username": { "type": "string", "nullable": true }, "peer_id": { "type": "string" }, "peer_name": { "type": "string" }, "peer_handle": { "type": "string", "nullable": true }, "peer_avatar_url": { "type": "string", "nullable": true }, "last_message_at": { "type": "string", "format": "date-time", "nullable": true }, "snippet": { "type": "string" }, "can_reply": { "type": "boolean" }, "media_kinds": { "type": "array", "items": { "type": "string", "enum": [ "image", "video" ] } } } }, "InboxDmList": { "type": "object", "properties": { "range": { "type": "string" }, "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "fetched_at": { "type": "string", "format": "date-time" }, "conversations": { "type": "array", "items": { "$ref": "#/components/schemas/InboxConversation" } }, "has_more": { "type": "boolean" }, "next_before": { "type": "string", "nullable": true }, "sampled": { "type": "boolean" }, "sample_limit": { "type": "integer" }, "unsupported": { "type": "array", "items": { "type": "string" } }, "accounts_needing_reconnect": { "type": "array", "items": { "$ref": "#/components/schemas/ReconnectHint" } }, "fetch_errors": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string" }, "platform": { "type": "string" }, "error": { "type": "string" } } } }, "notices": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "message": { "type": "string" } } } } } }, "InboxDmThread": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "conversation": { "$ref": "#/components/schemas/InboxConversation" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "is_own": { "type": "boolean" }, "author_id": { "type": "string", "nullable": true }, "author_name": { "type": "string" }, "author_handle": { "type": "string", "nullable": true }, "attachment": { "$ref": "#/components/schemas/InboxAttachment" } } } }, "fetched_at": { "type": "string", "format": "date-time" } } }, "InboxMutationResult": { "type": "object", "properties": { "ok": { "type": "boolean" }, "reply_id": { "type": "string" }, "message_id": { "type": "string" } } } }, "responses": { "Error": { "description": "Typed error with machine-readable code and human-readable message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "Missing or invalid API key / OAuth token", "headers": { "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "RateLimited": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "ServerError": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "paths": { "/v1/me": { "get": { "operationId": "getCurrentUser", "summary": "Get current user", "description": "Return the API-key owner profile, plan, and key prefix.", "tags": [ "Auth" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "me:read", "social0:read" ] } ], "responses": { "200": { "description": "Authenticated user profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/accounts": { "get": { "operationId": "listAccounts", "summary": "List connected accounts", "description": "List social accounts in the personal workspace.", "tags": [ "Accounts" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "accounts:read", "social0:read" ] } ], "responses": { "200": { "description": "List of connected social accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/accounts/connect": { "post": { "operationId": "connectAccount", "summary": "Get OAuth authorization URL", "description": "Return a URL the human should open to connect a platform.", "tags": [ "Accounts" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "accounts:write", "social0:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "platform" ], "properties": { "platform": { "type": "string", "example": "linkedin" } } } } } }, "responses": { "200": { "description": "Authorization URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectUrl" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/accounts/{id}": { "delete": { "operationId": "disconnectAccount", "summary": "Disconnect account", "description": "Revoke and remove a connected social account.", "tags": [ "Accounts" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "accounts:write", "social0:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Disconnected" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/posts": { "get": { "operationId": "listPosts", "summary": "List posts", "description": "Paginated drafts, schedules, and published posts (offset/page).", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "posts:read", "social0:read" ] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100 } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "platform", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "connected_account_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Paginated posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createDraft", "summary": "Create draft post", "description": "Create an unpublished draft. Does not post to any network.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "posts:write", "social0:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePostRequest" } } } }, "responses": { "201": { "description": "Post created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedPost" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/posts/{id}": { "get": { "operationId": "getPost", "summary": "Get post", "description": "Post detail including per-platform publication rows.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "posts:read", "social0:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Post details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateDraft", "summary": "Update draft", "description": "Update an unpublished draft or scheduled post.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "posts:write", "social0:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePostRequest" } } } }, "responses": { "200": { "description": "Updated post", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "deleteDraft", "summary": "Delete draft", "description": "Delete an unpublished draft or scheduled post. Does not delete live network posts.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "posts:write", "social0:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/posts/{id}/events": { "get": { "operationId": "listPostEvents", "summary": "List publish events for a post", "description": "Timeline of per-platform publish phases.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "posts:read", "jobs:read", "social0:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Event timeline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostEvents" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/posts/{id}/publish": { "post": { "operationId": "publishPost", "summary": "Publish post immediately", "description": "Queue an existing draft for publish. Returns 202 and Location of the job.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "posts:write", "social0:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Publish queued", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueued" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/posts/{id}/schedule": { "post": { "operationId": "schedulePost", "summary": "Schedule post", "description": "Schedule an existing draft for a UTC (or timezone-resolved) time.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "posts:write", "social0:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scheduledAt" ], "properties": { "scheduledAt": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" } } } } } }, "responses": { "200": { "description": "Scheduled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledPost" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/posts/publish": { "post": { "operationId": "createAndPublish", "summary": "Create and publish in one request", "description": "Create a post and queue publish. 202 Accepted with Location of the job.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "posts:write", "social0:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePostRequest" } } } }, "responses": { "202": { "description": "Created and queued", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobQueued" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/posts/schedule": { "post": { "operationId": "createAndSchedule", "summary": "Create and schedule in one request", "description": "Create a post and schedule it.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "posts:write", "social0:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreatePostRequest" }, { "type": "object", "required": [ "scheduledAt" ], "properties": { "scheduledAt": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" } } } ] } } } }, "responses": { "201": { "description": "Created and scheduled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledPost" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/jobs/{trackingId}": { "get": { "operationId": "getPublishJob", "summary": "Get publish job status", "description": "Poll until status is completed, failed, or partial.", "tags": [ "Jobs" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "jobs:read", "social0:read" ] } ], "parameters": [ { "name": "trackingId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job status and platform progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/jobs/{trackingId}/stream": { "get": { "operationId": "streamPublishJob", "summary": "Stream publish job events", "description": "Server-sent events for an in-flight publish job.", "tags": [ "Jobs" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "jobs:read", "social0:read" ] } ], "parameters": [ { "name": "trackingId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SSE stream", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/media/presign": { "post": { "operationId": "presignMediaUpload", "summary": "Get presigned upload URL", "description": "Create an R2 presign for a media file, then PUT bytes to upload_url.", "tags": [ "Media" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "media:write", "social0:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresignRequest" } } } }, "responses": { "200": { "description": "Presigned URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresignResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/media/confirm": { "post": { "operationId": "confirmMediaUpload", "summary": "Confirm media upload", "description": "Finalize a presigned upload and return a media id for posts.", "tags": [ "Media" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "media:write", "social0:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmMediaRequest" } } } }, "responses": { "201": { "description": "Media ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Media" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/media/{id}": { "get": { "operationId": "getMedia", "summary": "Get media", "description": "Fetch a previously confirmed media object.", "tags": [ "Media" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "media:write", "social0:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Media object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Media" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List webhooks", "description": "List webhook subscriptions for the API-key owner.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "webhooks:read", "social0:read" ] } ], "responses": { "200": { "description": "Webhook subscriptions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createWebhook", "summary": "Create webhook", "description": "Create a webhook. The secret is returned once.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "webhooks:write", "social0:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "post.published", "post.failed", "post.scheduled", "post.deleted" ] } } } } } } }, "responses": { "201": { "description": "Webhook created with secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/webhooks/{id}": { "get": { "operationId": "getWebhook", "summary": "Get webhook", "description": "Fetch one webhook subscription, including the outcome of its most recent delivery attempt.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "webhooks:read", "social0:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateWebhook", "summary": "Update webhook", "description": "Update URL, events, or active flag.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "webhooks:write", "social0:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "deleteWebhook", "summary": "Delete webhook", "description": "Remove a webhook subscription.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "webhooks:write", "social0:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "List webhook deliveries", "description": "Delivery attempts for one endpoint, newest first. An event that was never attempted has no row; one the endpoint rejected records the response code. Page with `before` (the `next_before` of the previous page).", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "webhooks:read", "social0:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "before", "in": "query", "required": false, "description": "Return deliveries created strictly before this timestamp.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Delivery attempts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "summary": "Send a test delivery", "description": "Sends a signed `webhook.test` event to the endpoint now, regardless of its event filter, and returns what the endpoint answered. Subject to the per-minute mutation budget.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "webhooks:write", "social0:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Delivery outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/analytics/accounts": { "get": { "operationId": "listAnalyticsAccounts", "summary": "List accounts with live analytics", "description": "Connected accounts on networks where live analytics is currently enabled.", "tags": [ "Analytics" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "analytics:read", "social0:read" ] } ], "responses": { "200": { "description": "Accounts eligible for live analytics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsAccountList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/analytics/overview": { "get": { "operationId": "getAnalyticsOverview", "summary": "Aggregate metrics for a window", "description": "Live metrics for posts published through Social0 in the window. Metrics are fetched from each platform at request time; check `sampled` and `partial` before treating totals as complete.", "tags": [ "Analytics" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "analytics:read", "social0:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/WindowRange" }, { "$ref": "#/components/parameters/WindowSince" }, { "$ref": "#/components/parameters/WindowUntil" }, { "$ref": "#/components/parameters/AccountIdQuery" }, { "$ref": "#/components/parameters/Fresh" } ], "responses": { "200": { "description": "Aggregated live metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsOverview" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/analytics/posts/{postId}": { "get": { "operationId": "getPostAnalytics", "summary": "Live metrics for one post", "description": "Per-publication metrics for a single Social0 post, across every network it went out on.", "tags": [ "Analytics" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "analytics:read", "social0:read" ] } ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Live metrics for the post", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostAnalytics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" }, "404": { "description": "Post not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/inbox/accounts": { "get": { "operationId": "listInboxAccounts", "summary": "List accounts with a live inbox", "description": "Connected accounts on networks where comments (or DMs) are currently enabled.", "tags": [ "Inbox" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "inbox:read", "social0:read" ] } ], "parameters": [ { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "comments", "dms" ], "default": "comments" } } ], "responses": { "200": { "description": "Accounts eligible for the live inbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsAccountList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/inbox/comments": { "get": { "operationId": "listInboxComments", "summary": "List comment threads", "description": "Comments on posts published through Social0, fetched live from each platform. Page older publications with `before=next_before`.", "tags": [ "Inbox" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "inbox:read", "social0:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/WindowRange" }, { "$ref": "#/components/parameters/WindowSince" }, { "$ref": "#/components/parameters/WindowUntil" }, { "$ref": "#/components/parameters/AccountIdQuery" }, { "$ref": "#/components/parameters/InboxBefore" }, { "$ref": "#/components/parameters/InboxLimit" }, { "$ref": "#/components/parameters/Fresh" }, { "name": "platform", "in": "query", "required": false, "description": "Limit to one network. Only networks with a live comments inbox are accepted (see GET /v1/inbox/accounts); a network that is still rolling out returns 400.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comment threads in the window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxCommentList" } } } }, "400": { "description": "Invalid query, or `platform` names a network whose comments inbox is not live yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/inbox/comments/{commentId}/reply": { "post": { "operationId": "replyToInboxComment", "summary": "Reply to a comment", "description": "Posts a reply on the originating network. The comment must belong to `publication_id` \u2014 Social0 verifies this against the live thread before sending.", "tags": [ "Inbox" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "inbox:write", "social0:write" ] } ], "parameters": [ { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "publication_id" ], "properties": { "publication_id": { "type": "string", "format": "uuid" }, "text": { "type": "string" }, "media_id": { "type": "string", "format": "uuid", "description": "Media upload id. Only X and Bluesky accept attachments on comment replies." } } } } } }, "responses": { "200": { "description": "Reply posted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxMutationResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" }, "400": { "description": "Reply rejected by Social0 or the platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/inbox/comments/{commentId}/like": { "post": { "operationId": "likeInboxComment", "summary": "Like or unlike a comment", "tags": [ "Inbox" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "inbox:write", "social0:write" ] } ], "parameters": [ { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "publication_id" ], "properties": { "publication_id": { "type": "string", "format": "uuid" }, "unlike": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "Like applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxMutationResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" }, "400": { "description": "Not supported for this network, or rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/inbox/comments/{commentId}/hide": { "post": { "operationId": "hideInboxComment", "summary": "Hide a comment", "description": "Moderation. Supported on Instagram and Facebook Pages.", "tags": [ "Inbox" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "inbox:write", "social0:write" ] } ], "parameters": [ { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "publication_id" ], "properties": { "publication_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Comment hidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxMutationResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" }, "400": { "description": "Not supported for this network, or rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/inbox/dms": { "get": { "operationId": "listInboxDms", "summary": "List DM conversations", "tags": [ "Inbox" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "inbox:read", "social0:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/WindowRange" }, { "$ref": "#/components/parameters/WindowSince" }, { "$ref": "#/components/parameters/WindowUntil" }, { "$ref": "#/components/parameters/AccountIdQuery" }, { "$ref": "#/components/parameters/InboxBefore" }, { "$ref": "#/components/parameters/InboxLimit" }, { "$ref": "#/components/parameters/Fresh" } ], "responses": { "200": { "description": "DM conversations in the window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxDmList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/inbox/dms/{conversationId}": { "get": { "operationId": "getInboxDmThread", "summary": "Get one DM conversation", "tags": [ "Inbox" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "inbox:read", "social0:read" ] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "peer_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Fresh" } ], "responses": { "200": { "description": "Messages in the conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxDmThread" } } } }, "400": { "description": "Unsupported network, invalid input, or the platform read failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" }, "404": { "description": "Account not found in the personal pool", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/inbox/dms/{conversationId}/reply": { "post": { "operationId": "replyToInboxDm", "summary": "Send a DM reply", "description": "Sends into an existing conversation. Social0 verifies the conversation belongs to `account_id` before sending.", "tags": [ "Inbox" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "inbox:write", "social0:write" ] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_id" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "peer_id": { "type": "string" }, "text": { "type": "string" }, "media_id": { "type": "string", "format": "uuid", "description": "Media upload id. X accepts image and video; TikTok image only; Bluesky text only." } } } } } }, "responses": { "200": { "description": "Message sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxMutationResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "$ref": "#/components/responses/Error" }, "400": { "description": "Rejected by Social0 or the platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }