{ "openapi": "3.1.0", "info": { "title": "PostClock API", "version": "1.0.0", "description": "Schedule and publish posts to Instagram, Threads, TikTok and YouTube, including your own customers' accounts through connect links." }, "servers": [ { "url": "https://postclock.social/api/v1" } ], "security": [ { "apiKey": [] } ], "paths": { "/connect-links": { "post": { "summary": "Create a single-use connect link for an end user", "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectLink" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "platform", "redirectUrl" ], "additionalProperties": false, "properties": { "platform": { "enum": [ "instagram", "threads", "tiktok", "youtube" ] }, "redirectUrl": { "type": "string", "format": "uri", "description": "HTTPS URL on an allowlisted origin. On return PostClock adds accountId and platform, or error and message." }, "profileId": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "tags": [ "Connect" ] } }, "/connect-origins": { "get": { "summary": "List allowed redirect origins", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Origins" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "tags": [ "Connect" ] }, "post": { "summary": "Replace allowed redirect origins", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Origins" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Origins" } } } }, "tags": [ "Connect" ] } }, "/profiles": { "get": { "summary": "List profiles", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Profile" } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "externalId", "in": "query", "required": false, "description": "Find by your own ID", "schema": { "type": "string" } } ], "tags": [ "Profiles" ] }, "post": { "summary": "Create a profile", "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "externalId": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "name" ] } } } }, "tags": [ "Profiles" ] } }, "/profiles/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Get a profile", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "tags": [ "Profiles" ] }, "patch": { "summary": "Update a profile", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "externalId": { "type": [ "string", "null" ], "maxLength": 200 } } } } } }, "tags": [ "Profiles" ] }, "delete": { "summary": "Delete a profile; its accounts stay connected", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "tags": [ "Profiles" ] } }, "/accounts": { "get": { "summary": "List accounts", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "profileId", "in": "query", "required": false, "description": "Only this profile's accounts", "schema": { "type": "string" } } ], "tags": [ "Accounts" ] } }, "/accounts/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "Move an account to a profile or out of it", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "profileId" ], "properties": { "profileId": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "tags": [ "Accounts" ] } }, "/accounts/{id}/disconnect": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Disconnect an account", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "tags": [ "Accounts" ] } }, "/posts": { "get": { "summary": "List posts", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }, "next": { "type": [ "string", "null" ] } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Post status", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1-100", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "before", "in": "query", "required": false, "description": "createdAt cursor from next", "schema": { "type": "string" } }, { "name": "profileId", "in": "query", "required": false, "description": "Posts to any account in this profile", "schema": { "type": "string" } } ], "tags": [ "Posts" ] }, "post": { "summary": "Create a post", "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostInput" } } } }, "tags": [ "Posts" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ] } }, "/posts/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Get a post", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "tags": [ "Posts" ] }, "patch": { "summary": "Replace a draft, scheduled or cancelled post", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostInput" } } } }, "tags": [ "Posts" ] }, "delete": { "summary": "Delete a post", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "tags": [ "Posts" ], "parameters": [ { "name": "alsoOnThreads", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Delete the post's published Threads copies first. Instagram posts cannot be deleted through its API." } ] } }, "/posts/{id}/cancel": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Cancel delivery that has not started", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "tags": [ "Posts" ] } }, "/deliveries/{id}/retry": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Retry a failed or held delivery", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "tags": [ "Posts" ] } }, "/deliveries/{id}/posted": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Mark a delivery as posted by hand", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "tags": [ "Posts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The live post on the delivery network" } } } } } } } }, "/deliveries/{id}/comment/retry": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Retry a failed first comment", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirstComment" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" } }, "tags": [ "Posts" ] } }, "/media": { "post": { "summary": "Get a signed upload URL", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadUrl": { "type": "string" }, "publicUrl": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "enum": [ "video/mp4", "image/jpeg", "image/png" ] } } } } } }, "tags": [ "Media" ] } }, "/inbox": { "get": { "summary": "List comments, replies and mentions", "tags": [ "Inbox" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InboxItem" } }, "errors": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "$ref": "#/components/responses/Error" } } } }, "/inbox/reply": { "post": { "summary": "Reply to a comment or mention", "tags": [ "Inbox" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "accountId", "commentId", "text" ], "properties": { "accountId": { "type": "string" }, "commentId": { "type": "string" }, "text": { "type": "string", "maxLength": 2200 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } } } }, "/inbox/hide": { "post": { "summary": "Hide or unhide an Instagram comment", "tags": [ "Inbox" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "accountId", "commentId" ], "properties": { "accountId": { "type": "string" }, "commentId": { "type": "string" }, "hidden": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } } } } }, "webhooks": { "account.connected": { "post": { "summary": "An end user connected an account", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" } ], "properties": { "data": { "type": "object", "properties": { "accountId": { "type": "string" }, "platform": { "type": "string" }, "name": { "type": "string" }, "handle": { "type": "string" }, "profileId": { "type": [ "string", "null" ] } } } } } } } }, "responses": { "2XX": { "description": "Received" } } } }, "account.disconnected": { "post": { "summary": "An account was disconnected or its access revoked", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" } ], "properties": { "data": { "type": "object", "properties": { "accountId": { "type": "string" }, "platform": { "type": "string" }, "profileId": { "type": [ "string", "null" ] }, "reason": { "enum": [ "disconnected", "revoked" ] } } } } } } } }, "responses": { "2XX": { "description": "Received" } } } }, "delivery.published": { "post": { "summary": "A delivery was published", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received" } } } }, "delivery.failed": { "post": { "summary": "A delivery failed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received" } } } }, "delivery.needs_review": { "post": { "summary": "A delivery outcome is uncertain", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received" } } } }, "network.paused": { "post": { "summary": "PostClock paused publishing to a network for everyone", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" } ], "properties": { "data": { "type": "object", "properties": { "platform": { "type": "string" } } } } } } } }, "responses": { "2XX": { "description": "Received" } } } }, "network.resumed": { "post": { "summary": "Publishing to a paused network started again", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" } ], "properties": { "data": { "type": "object", "properties": { "platform": { "type": "string" } } } } } } } }, "responses": { "2XX": { "description": "Received" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "A pc_ key from Developer API settings" } }, "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "schemas": { "ConnectLink": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "Origins": { "type": "object", "required": [ "origins" ], "properties": { "origins": { "type": "array", "maxItems": 20, "items": { "type": "string", "description": "HTTPS origin, e.g. https://app.example.com" } } } }, "Profile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "externalId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "Account": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "enum": [ "instagram", "threads", "tiktok", "youtube", "linkedin", "bluesky" ] }, "name": { "type": "string" }, "handle": { "type": "string" }, "demo": { "type": "boolean" }, "connected": { "type": "boolean" }, "expiresAt": { "type": [ "string", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "profileId": { "type": [ "string", "null" ] } } }, "PostInput": { "type": "object", "required": [ "accountIds" ], "properties": { "title": { "type": "string", "maxLength": 100, "description": "Required only when a YouTube account is selected" }, "caption": { "type": "string", "maxLength": 5000 }, "mediaType": { "enum": [ "video", "image", "text" ], "default": "video" }, "mediaUrl": { "type": "string", "description": "HTTPS URL; required unless mediaType is text" }, "accountIds": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "type": "string" } }, "status": { "enum": [ "draft", "scheduled" ], "default": "draft" }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time" }, "queue": { "type": "boolean", "description": "POST only. Schedules the post for the next free queue slot, read in its timezone." }, "publishNow": { "type": "boolean" }, "timezone": { "type": "string", "default": "UTC" }, "options": { "type": "object", "properties": { "captions": { "type": "object", "additionalProperties": { "type": "string" } }, "altText": { "type": "string" }, "youtubePrivacy": { "enum": [ "private", "unlisted", "public" ] }, "madeForKids": { "type": "boolean" }, "tiktokPrivacy": { "enum": [ "", "SELF_ONLY", "PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR" ] }, "duration": { "type": "number" }, "consent": { "type": "boolean" }, "allowComments": { "type": "boolean" }, "allowDuet": { "type": "boolean" }, "allowStitch": { "type": "boolean" }, "ownBrand": { "type": "boolean" }, "paidPartnership": { "type": "boolean" }, "aiGenerated": { "type": "boolean" }, "firstComment": { "type": "string", "maxLength": 2200, "description": "Instagram and Threads only. Posted as a comment, or a Threads reply, right after the post goes live. Threads allows 500 characters." }, "firstComments": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Per-network first comment overrides." }, "commentDelay": { "type": "integer", "minimum": 0, "maximum": 1440, "default": 0, "description": "Minutes between the post going live and its first comment." }, "extraImages": { "type": "array", "maxItems": 19, "items": { "type": "string", "format": "uri" }, "description": "A carousel: more image URLs after mediaUrl. Instagram and Facebook take 10 images in all, Threads 20, Bluesky 4." } } } } }, "Delivery": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "platform": { "type": "string" }, "status": { "enum": [ "draft", "queued", "working", "processing", "published", "failed", "uncertain", "cancelled", "held" ] }, "remoteId": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "attempts": { "type": "integer" }, "firstComment": { "oneOf": [ { "$ref": "#/components/schemas/FirstComment" }, { "type": "null" } ] } } }, "Post": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "caption": { "type": "string" }, "mediaType": { "type": "string" }, "mediaUrl": { "type": "string" }, "previewUrl": { "type": "string" }, "scheduledAt": { "type": [ "string", "null" ] }, "status": { "enum": [ "draft", "scheduled", "processing", "published", "partial", "failed", "needs_review", "cancelled" ] }, "createdAt": { "type": "string" }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } } } }, "WebhookEvent": { "type": "object", "description": "Signed with PostClock-Signature: t=,v1=", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object" } } }, "FirstComment": { "type": "object", "properties": { "status": { "enum": [ "waiting", "sending", "posted", "failed" ] }, "text": { "type": "string" }, "id": { "type": "string" }, "error": { "type": "string" }, "at": { "type": "string", "format": "date-time" } } }, "InboxItem": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "platform": { "enum": [ "instagram", "threads" ] }, "kind": { "enum": [ "comment", "mention" ] }, "postId": { "type": "string" }, "text": { "type": "string" }, "username": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "hidden": { "type": "boolean" }, "permalink": { "type": "string" } } } } } }