{ "openapi": "3.0.3", "info": { "title": "Afilipost API", "version": "1.0.0", "description": "Publishing infrastructure for Instagram, Facebook Pages, Threads, YouTube, Pinterest, TikTok and LinkedIn. Schedule posts across connected accounts, attach comment-to-DM automations, and receive signed webhooks. Accounts connect only through each platform's own OAuth flow — no password ever enters this system.", "contact": { "email": "1burakbabacan@gmail.com" } }, "servers": [ { "url": "https://api.afilipost.com/api", "description": "Primary (Zernio-shaped base)" }, { "url": "https://api.afilipost.com", "description": "Same routes without the /api prefix" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key issued in the panel, shown once. Format: yay_…" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable reason" } }, "required": [ "error" ] }, "Account": { "type": "object", "properties": { "_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "platform": { "$ref": "#/components/schemas/Platform" }, "username": { "type": "string", "nullable": true }, "displayName": { "type": "string", "nullable": true }, "avatarUrl": { "type": "string", "nullable": true }, "isActive": { "type": "boolean" }, "status": { "type": "string", "enum": [ "ok", "error", "expired" ] }, "statusMessage": { "type": "string", "nullable": true }, "profileId": { "type": "object", "properties": { "_id": { "type": "string", "format": "uuid" } }, "description": "The workspace (tenant) the account belongs to" }, "meta": { "type": "object", "additionalProperties": true } } }, "Platform": { "type": "string", "enum": [ "instagram", "facebook", "threads", "youtube", "pinterest", "tiktok", "linkedin" ] }, "MediaItem": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "video", "image" ] }, "url": { "type": "string", "description": "Public URL returned by presign" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer" } }, "required": [ "type", "url" ] }, "PlatformEntry": { "type": "object", "properties": { "platform": { "$ref": "#/components/schemas/Platform" }, "accountId": { "type": "string", "format": "uuid" }, "platformSpecificData": { "type": "object", "additionalProperties": true, "description": "Per-platform options. Instagram: shareToFeed, firstComment. YouTube: title, privacy, tags. Pinterest: boardId, title, link. TikTok: privacyLevel, isAigc." } }, "required": [ "accountId" ] }, "PostTarget": { "type": "object", "properties": { "platform": { "$ref": "#/components/schemas/Platform" }, "accountId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "partial", "failed" ] }, "platformPostId": { "type": "string", "nullable": true, "description": "Null until the target actually goes live. Comment automations need it." }, "permalink": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "Post": { "type": "object", "properties": { "_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "content": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "partial", "failed" ] }, "scheduledFor": { "type": "string", "format": "date-time", "nullable": true }, "timezone": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "mediaItems": { "type": "array", "items": { "$ref": "#/components/schemas/MediaItem" } }, "platforms": { "type": "array", "items": { "$ref": "#/components/schemas/PostTarget" } } } }, "WebhookEvent": { "type": "object", "description": "Delivered to registered endpoints with header X-Afilipost-Signature: t=,v1=.", "properties": { "type": { "type": "string", "enum": [ "post.published", "post.failed", "account.expired", "dm.received", "comment.received", "webhook.test" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": true } } } }, "responses": { "Unauthorized": { "description": "API key missing, malformed or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadRequest": { "description": "The request body is wrong; the message names the field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "The record belongs to another workspace or does not exist — deliberately the same answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/v1/accounts": { "get": { "summary": "Connected accounts", "operationId": "listAccounts", "parameters": [ { "name": "platform", "in": "query", "schema": { "$ref": "#/components/schemas/Platform" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "description": "Too many requests from this address. Retry-After header gives the wait in seconds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/v1/media/presign": { "post": { "summary": "Signed upload address — PUT the file straight to storage", "operationId": "presignMedia", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string" }, "contentType": { "type": "string", "example": "video/mp4" }, "size": { "type": "integer" } }, "required": [ "filename" ] } } } }, "responses": { "200": { "description": "Upload grant. PUT the bytes to uploadUrl with the same Content-Type; reference publicUrl in mediaItems.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mediaId": { "type": "string", "format": "uuid" }, "uploadUrl": { "type": "string" }, "publicUrl": { "type": "string" }, "expiresIn": { "type": "integer", "example": 3600 }, "contentType": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "description": "Storage quota exceeded. Delete old media or wait for automatic cleanup of published files.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests from this address. Retry-After header gives the wait in seconds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/v1/posts": { "post": { "summary": "Create or schedule a post across one or more accounts", "operationId": "createPost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" }, "mediaItems": { "type": "array", "items": { "$ref": "#/components/schemas/MediaItem" } }, "coverUrl": { "type": "string" }, "platforms": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformEntry" } }, "scheduledFor": { "description": "ISO 8601 date-time, or the literal string \"auto\" to let the server pick the slot from the channel's rhythm (gap, daily cap, day window, collision buffer; isolated per API key). Omit to create a draft.", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "enum": [ "auto" ] } ] }, "timezone": { "type": "string", "default": "UTC" }, "idempotencyKey": { "type": "string", "description": "Strongly recommended: a retried request returns the existing post under existingPost instead of creating a duplicate" }, "chain": { "type": "array", "maxItems": 5, "description": "Post-publish steps, triggered once when the first target goes live.", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "followUp", "crossPost" ] }, "afterMinutes": { "type": "integer", "minimum": 0, "maximum": 1440 }, "accountIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "content": { "type": "string", "description": "followUp: new caption. crossPost inherits the parent's." }, "mediaItems": { "type": "array", "items": { "$ref": "#/components/schemas/MediaItem" } }, "options": { "type": "object", "additionalProperties": true } }, "required": [ "kind", "accountIds" ] } } }, "required": [ "platforms" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "post": { "$ref": "#/components/schemas/Post" } } } } } }, "200": { "description": "Idempotent replay — the post already existed", "content": { "application/json": { "schema": { "type": "object", "properties": { "existingPost": { "$ref": "#/components/schemas/Post" }, "post": { "$ref": "#/components/schemas/Post" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "description": "Too many requests from this address. Retry-After header gives the wait in seconds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "get": { "summary": "List posts", "operationId": "listPosts", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "partial", "failed" ] } }, { "name": "accountId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 500 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "posts": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "description": "Too many requests from this address. Retry-After header gives the wait in seconds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/v1/posts/{id}": { "get": { "summary": "One post with per-destination status", "operationId": "getPost", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "post": { "$ref": "#/components/schemas/Post" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "description": "Too many requests from this address. Retry-After header gives the wait in seconds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/v1/comment-automations": { "post": { "summary": "Attach a keyword → DM rule to a published Instagram post", "operationId": "createCommentAutomation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "platformPostId": { "type": "string", "description": "The live post's platform id — read it from GET /v1/posts/{id} after publish" }, "name": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "matchMode": { "type": "string", "enum": [ "contains", "exact", "starts_with", "word" ] }, "typoTolerance": { "type": "boolean" }, "commentReply": { "type": "string", "description": "Public reply to the comment" }, "dmMessage": { "type": "string" }, "buttons": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "title": { "type": "string" }, "url": { "type": "string" } } } }, "followGate": { "type": "object", "description": "Hold the link behind a button. On tap, Meta's is_user_follow_business flag is checked; if the flag is missing the link is sent anyway.", "properties": { "message": { "type": "string" }, "buttonLabel": { "type": "string" }, "notFollowingMessage": { "type": "string" } } }, "trackLinks": { "type": "boolean", "default": true, "description": "Button links pass through /r/ so clicks are counted per rule. Set false to send raw URLs." } }, "required": [ "accountId", "platformPostId" ] } } } }, "responses": { "201": { "description": "Rule created" }, "200": { "description": "Rule already existed for this post — not an error" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "description": "Too many requests from this address. Retry-After header gives the wait in seconds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/r/{code}": { "get": { "summary": "Tracked-link redirect — public, no auth", "operationId": "redirect", "security": [], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirects to the target URL and counts the click. No personal data is collected." }, "404": { "description": "Unknown code" } } } } } }