{"openapi":"3.0.3","info":{"title":"Blotato API","description":"Blotato API documentation","version":"2.0.0"},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"blotato-api-key","in":"header"}},"schemas":{}},"paths":{"/v2/dm-automations":{"get":{"summary":"List DM automations","tags":["automations"],"description":"Lists the current user's DM automations, ordered by creation time (most recent first). Supports cursor-based pagination.","parameters":[{"schema":{"minimum":1,"maximum":250,"default":50,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Maximum number of DM automations to return. Defaults to 50."},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Opaque cursor returned by a previous call. Pass it to fetch the next page."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"description":"List of DM automations","type":"array","items":{"type":"object","properties":{"accountId":{"type":"string"},"buttons":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"title":{"maxLength":20,"type":"string"},"type":{"type":"string","enum":["url"]},"url":{"type":"string"}},"required":["title","type"]}},"createdAt":{"type":"string"},"dmMessage":{"maxLength":640,"type":"string"},"emailGate":{"type":"object","properties":{"message":{"minLength":1,"maxLength":640,"type":"string"}},"required":["message"]},"followGate":{"type":"object","properties":{"buttonTitle":{"default":"I'm following","minLength":1,"maxLength":20,"type":"string"},"message":{"minLength":1,"maxLength":640,"type":"string"}},"required":["message"]},"id":{"type":"string"},"isActive":{"type":"boolean"},"name":{"minLength":1,"maxLength":60,"type":"string"},"platform":{"type":"string","enum":["facebook","instagram"]},"publishedVersionId":{"type":"string","nullable":true},"target":{"type":"object","discriminator":{"propertyName":"targetType"},"oneOf":[{"type":"object","properties":{"pageId":{"type":"string"},"targetType":{"type":"string","enum":["facebook"]}},"required":["pageId","targetType"]},{"type":"object","properties":{"targetType":{"type":"string","enum":["instagram"]}},"required":["targetType"]}]},"trigger":{"type":"object","discriminator":{"propertyName":"type"},"oneOf":[{"type":"object","properties":{"isActive":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"postId":{"type":"string","nullable":true},"type":{"type":"string","enum":["comment-received"]}},"required":["keywords","type"]},{"type":"object","properties":{"isActive":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"type":{"type":"string","enum":["message-received"]}},"required":["keywords","type"]}]},"updatedAt":{"type":"string"},"webhook":{"type":"object","properties":{"headers":{"type":"object","additionalProperties":{"type":"string"}},"method":{"type":"string","enum":["DELETE","GET","PATCH","POST","PUT"]},"url":{"minLength":1,"maxLength":2048,"type":"string"}},"required":["method","url"]}},"required":["accountId","buttons","createdAt","dmMessage","id","isActive","name","platform","publishedVersionId","target","updatedAt"]}},"cursor":{"description":"Cursor for the next page. Absent when there are no more DM automations.","type":"string"}},"required":["items"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}},"post":{"summary":"Create a DM automation","tags":["automations"],"description":"Creates a DM automation: when its trigger fires it sends one direct message (text plus up to 3 link buttons). Set `followGate` (Instagram only) to gate that message behind a follow check, and `emailGate` to gate it behind the contact replying with an email address. Set `webhook` to call an external endpoint once the message is sent; its payload carries the run's contact and identifiers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"buttons":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"title":{"maxLength":20,"type":"string"},"type":{"type":"string","enum":["url"]},"url":{"type":"string"}},"required":["title","type"]}},"dmMessage":{"minLength":1,"maxLength":640,"type":"string"},"emailGate":{"type":"object","properties":{"message":{"minLength":1,"maxLength":640,"type":"string"}},"required":["message"],"nullable":true},"followGate":{"type":"object","properties":{"buttonTitle":{"default":"I'm following","minLength":1,"maxLength":20,"type":"string"},"message":{"minLength":1,"maxLength":640,"type":"string"}},"required":["message"],"nullable":true},"isActive":{"type":"boolean"},"name":{"minLength":1,"maxLength":60,"type":"string"},"platform":{"type":"string","enum":["facebook","instagram"]},"target":{"type":"object","discriminator":{"propertyName":"targetType"},"oneOf":[{"type":"object","properties":{"pageId":{"type":"string"},"targetType":{"type":"string","enum":["facebook"]}},"required":["pageId","targetType"]},{"type":"object","properties":{"targetType":{"type":"string","enum":["instagram"]}},"required":["targetType"]}]},"trigger":{"type":"object","discriminator":{"propertyName":"type"},"oneOf":[{"type":"object","properties":{"isActive":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"postId":{"type":"string","nullable":true},"type":{"type":"string","enum":["comment-received"]}},"required":["keywords","type"]},{"type":"object","properties":{"isActive":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"type":{"type":"string","enum":["message-received"]}},"required":["keywords","type"]}],"nullable":true},"webhook":{"type":"object","properties":{"headers":{"type":"object","additionalProperties":{"type":"string"}},"method":{"type":"string","enum":["DELETE","GET","PATCH","POST","PUT"]},"url":{"minLength":1,"maxLength":2048,"type":"string"}},"required":["method","url"],"nullable":true}},"required":["accountId","buttons","dmMessage","name","platform","target"]}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"flow":{"type":"object","properties":{"accountId":{"type":"string"},"buttons":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"title":{"maxLength":20,"type":"string"},"type":{"type":"string","enum":["url"]},"url":{"type":"string"}},"required":["title","type"]}},"createdAt":{"type":"string"},"dmMessage":{"maxLength":640,"type":"string"},"emailGate":{"type":"object","properties":{"message":{"minLength":1,"maxLength":640,"type":"string"}},"required":["message"]},"followGate":{"type":"object","properties":{"buttonTitle":{"default":"I'm following","minLength":1,"maxLength":20,"type":"string"},"message":{"minLength":1,"maxLength":640,"type":"string"}},"required":["message"]},"id":{"type":"string"},"isActive":{"type":"boolean"},"name":{"minLength":1,"maxLength":60,"type":"string"},"platform":{"type":"string","enum":["facebook","instagram"]},"publishedVersionId":{"type":"string","nullable":true},"target":{"type":"object","discriminator":{"propertyName":"targetType"},"oneOf":[{"type":"object","properties":{"pageId":{"type":"string"},"targetType":{"type":"string","enum":["facebook"]}},"required":["pageId","targetType"]},{"type":"object","properties":{"targetType":{"type":"string","enum":["instagram"]}},"required":["targetType"]}]},"trigger":{"type":"object","discriminator":{"propertyName":"type"},"oneOf":[{"type":"object","properties":{"isActive":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"postId":{"type":"string","nullable":true},"type":{"type":"string","enum":["comment-received"]}},"required":["keywords","type"]},{"type":"object","properties":{"isActive":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"type":{"type":"string","enum":["message-received"]}},"required":["keywords","type"]}]},"updatedAt":{"type":"string"},"webhook":{"type":"object","properties":{"headers":{"type":"object","additionalProperties":{"type":"string"}},"method":{"type":"string","enum":["DELETE","GET","PATCH","POST","PUT"]},"url":{"minLength":1,"maxLength":2048,"type":"string"}},"required":["method","url"]}},"required":["accountId","buttons","createdAt","dmMessage","id","isActive","name","platform","publishedVersionId","target","updatedAt"]}},"required":["flow"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Validation error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Validation error","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/dm-automations/{id}":{"get":{"summary":"Get a DM automation","tags":["automations"],"description":"Fetches a single DM automation by id, including its trigger and the message it sends.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"flow":{"type":"object","properties":{"accountId":{"type":"string"},"buttons":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"title":{"maxLength":20,"type":"string"},"type":{"type":"string","enum":["url"]},"url":{"type":"string"}},"required":["title","type"]}},"createdAt":{"type":"string"},"dmMessage":{"maxLength":640,"type":"string"},"emailGate":{"type":"object","properties":{"message":{"minLength":1,"maxLength":640,"type":"string"}},"required":["message"]},"followGate":{"type":"object","properties":{"buttonTitle":{"default":"I'm following","minLength":1,"maxLength":20,"type":"string"},"message":{"minLength":1,"maxLength":640,"type":"string"}},"required":["message"]},"id":{"type":"string"},"isActive":{"type":"boolean"},"name":{"minLength":1,"maxLength":60,"type":"string"},"platform":{"type":"string","enum":["facebook","instagram"]},"publishedVersionId":{"type":"string","nullable":true},"target":{"type":"object","discriminator":{"propertyName":"targetType"},"oneOf":[{"type":"object","properties":{"pageId":{"type":"string"},"targetType":{"type":"string","enum":["facebook"]}},"required":["pageId","targetType"]},{"type":"object","properties":{"targetType":{"type":"string","enum":["instagram"]}},"required":["targetType"]}]},"trigger":{"type":"object","discriminator":{"propertyName":"type"},"oneOf":[{"type":"object","properties":{"isActive":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"postId":{"type":"string","nullable":true},"type":{"type":"string","enum":["comment-received"]}},"required":["keywords","type"]},{"type":"object","properties":{"isActive":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"type":{"type":"string","enum":["message-received"]}},"required":["keywords","type"]}]},"updatedAt":{"type":"string"},"webhook":{"type":"object","properties":{"headers":{"type":"object","additionalProperties":{"type":"string"}},"method":{"type":"string","enum":["DELETE","GET","PATCH","POST","PUT"]},"url":{"minLength":1,"maxLength":2048,"type":"string"}},"required":["method","url"]}},"required":["accountId","buttons","createdAt","dmMessage","id","isActive","name","platform","publishedVersionId","target","updatedAt"]}},"required":["flow"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}},"patch":{"summary":"Update a DM automation","tags":["automations"],"description":"Updates a DM automation. Each field present in the patch replaces that field; omitted fields are left unchanged. Pass `null` for `emailGate`, `followGate`, `trigger`, or `webhook` to remove it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"patch":{"type":"object","properties":{"buttons":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"title":{"maxLength":20,"type":"string"},"type":{"type":"string","enum":["url"]},"url":{"type":"string"}},"required":["title","type"]}},"dmMessage":{"minLength":1,"maxLength":640,"type":"string"},"emailGate":{"type":"object","properties":{"message":{"minLength":1,"maxLength":640,"type":"string"}},"required":["message"],"nullable":true},"followGate":{"type":"object","properties":{"buttonTitle":{"default":"I'm following","minLength":1,"maxLength":20,"type":"string"},"message":{"minLength":1,"maxLength":640,"type":"string"}},"required":["message"],"nullable":true},"isActive":{"type":"boolean"},"name":{"minLength":1,"maxLength":60,"type":"string"},"trigger":{"type":"object","discriminator":{"propertyName":"type"},"oneOf":[{"type":"object","properties":{"isActive":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"postId":{"type":"string","nullable":true},"type":{"type":"string","enum":["comment-received"]}},"required":["keywords","type"]},{"type":"object","properties":{"isActive":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"type":{"type":"string","enum":["message-received"]}},"required":["keywords","type"]}],"nullable":true},"webhook":{"type":"object","properties":{"headers":{"type":"object","additionalProperties":{"type":"string"}},"method":{"type":"string","enum":["DELETE","GET","PATCH","POST","PUT"]},"url":{"minLength":1,"maxLength":2048,"type":"string"}},"required":["method","url"],"nullable":true}}}},"required":["patch"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"flow":{"type":"object","properties":{"accountId":{"type":"string"},"buttons":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"title":{"maxLength":20,"type":"string"},"type":{"type":"string","enum":["url"]},"url":{"type":"string"}},"required":["title","type"]}},"createdAt":{"type":"string"},"dmMessage":{"maxLength":640,"type":"string"},"emailGate":{"type":"object","properties":{"message":{"minLength":1,"maxLength":640,"type":"string"}},"required":["message"]},"followGate":{"type":"object","properties":{"buttonTitle":{"default":"I'm following","minLength":1,"maxLength":20,"type":"string"},"message":{"minLength":1,"maxLength":640,"type":"string"}},"required":["message"]},"id":{"type":"string"},"isActive":{"type":"boolean"},"name":{"minLength":1,"maxLength":60,"type":"string"},"platform":{"type":"string","enum":["facebook","instagram"]},"publishedVersionId":{"type":"string","nullable":true},"target":{"type":"object","discriminator":{"propertyName":"targetType"},"oneOf":[{"type":"object","properties":{"pageId":{"type":"string"},"targetType":{"type":"string","enum":["facebook"]}},"required":["pageId","targetType"]},{"type":"object","properties":{"targetType":{"type":"string","enum":["instagram"]}},"required":["targetType"]}]},"trigger":{"type":"object","discriminator":{"propertyName":"type"},"oneOf":[{"type":"object","properties":{"isActive":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"postId":{"type":"string","nullable":true},"type":{"type":"string","enum":["comment-received"]}},"required":["keywords","type"]},{"type":"object","properties":{"isActive":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"type":{"type":"string","enum":["message-received"]}},"required":["keywords","type"]}]},"updatedAt":{"type":"string"},"webhook":{"type":"object","properties":{"headers":{"type":"object","additionalProperties":{"type":"string"}},"method":{"type":"string","enum":["DELETE","GET","PATCH","POST","PUT"]},"url":{"minLength":1,"maxLength":2048,"type":"string"}},"required":["method","url"]}},"required":["accountId","buttons","createdAt","dmMessage","id","isActive","name","platform","publishedVersionId","target","updatedAt"]}},"required":["flow"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Validation error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Validation error","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}},"delete":{"summary":"Delete a DM automation","tags":["automations"],"description":"Archives a DM automation so its trigger stops listening and it no longer fires. Runs already in flight are unaffected.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"flow":{"type":"object","properties":{"accountId":{"type":"string"},"buttons":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"title":{"maxLength":20,"type":"string"},"type":{"type":"string","enum":["url"]},"url":{"type":"string"}},"required":["title","type"]}},"createdAt":{"type":"string"},"dmMessage":{"maxLength":640,"type":"string"},"emailGate":{"type":"object","properties":{"message":{"minLength":1,"maxLength":640,"type":"string"}},"required":["message"]},"followGate":{"type":"object","properties":{"buttonTitle":{"default":"I'm following","minLength":1,"maxLength":20,"type":"string"},"message":{"minLength":1,"maxLength":640,"type":"string"}},"required":["message"]},"id":{"type":"string"},"isActive":{"type":"boolean"},"name":{"minLength":1,"maxLength":60,"type":"string"},"platform":{"type":"string","enum":["facebook","instagram"]},"publishedVersionId":{"type":"string","nullable":true},"target":{"type":"object","discriminator":{"propertyName":"targetType"},"oneOf":[{"type":"object","properties":{"pageId":{"type":"string"},"targetType":{"type":"string","enum":["facebook"]}},"required":["pageId","targetType"]},{"type":"object","properties":{"targetType":{"type":"string","enum":["instagram"]}},"required":["targetType"]}]},"trigger":{"type":"object","discriminator":{"propertyName":"type"},"oneOf":[{"type":"object","properties":{"isActive":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"postId":{"type":"string","nullable":true},"type":{"type":"string","enum":["comment-received"]}},"required":["keywords","type"]},{"type":"object","properties":{"isActive":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"type":{"type":"string","enum":["message-received"]}},"required":["keywords","type"]}]},"updatedAt":{"type":"string"},"webhook":{"type":"object","properties":{"headers":{"type":"object","additionalProperties":{"type":"string"}},"method":{"type":"string","enum":["DELETE","GET","PATCH","POST","PUT"]},"url":{"minLength":1,"maxLength":2048,"type":"string"}},"required":["method","url"]}},"required":["accountId","buttons","createdAt","dmMessage","id","isActive","name","platform","publishedVersionId","target","updatedAt"]}},"required":["flow"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/dm-automations/{id}/runs":{"get":{"summary":"List DM automation runs","tags":["automations"],"description":"Lists the execution runs of a single DM automation, ordered by start time (most recent first). Supports cursor-based pagination.","parameters":[{"schema":{"minimum":1,"maximum":250,"default":50,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Maximum number of execution runs to return. Defaults to 50."},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Opaque cursor returned by a previous call. Pass it to fetch the next page."},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"description":"Execution runs for the DM automation, most recent first.","type":"array","items":{"type":"object","properties":{"contactId":{"type":"string"},"createdAt":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"}},"required":["message"]},"id":{"type":"string"},"platform":{"type":"string","enum":["facebook","instagram"]},"status":{"type":"string","enum":["completed","expired","failed","running","superseded","waiting"]},"updatedAt":{"type":"string"}},"required":["contactId","createdAt","id","platform","status","updatedAt"]}},"cursor":{"description":"Cursor for the next page. Absent when there are no more runs.","type":"string"}},"required":["items"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/dm-automations/{id}/logs":{"get":{"summary":"List DM automation logs","tags":["automations"],"description":"Lists the execution logs written as a DM automation's runs progress, ordered by creation time (most recent first). Pass flowRunId to narrow the logs to a single run. Supports cursor-based pagination.","parameters":[{"schema":{"type":"string"},"in":"query","name":"flowRunId","required":false,"description":"Only return logs belonging to this execution run. Omit to return logs across every run of the automation."},{"schema":{"minimum":1,"maximum":250,"default":50,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Maximum number of logs to return. Defaults to 50."},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Opaque cursor returned by a previous call. Pass it to fetch the next page."},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"description":"Execution logs for the DM automation, most recent first.","type":"array","items":{"type":"object","properties":{"context":{"type":"object","additionalProperties":{}},"createdAt":{"type":"string"},"flowRunId":{"type":"string"},"id":{"type":"string"},"level":{"type":"string","enum":["info","warning","error"]},"message":{"type":"string"},"nodeId":{"type":"string","nullable":true}},"required":["context","createdAt","flowRunId","id","level","message","nodeId"]}},"cursor":{"description":"Cursor for the next page. Absent when there are no more logs.","type":"string"}},"required":["items"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/dm-automations/{id}/analytics":{"get":{"summary":"Get DM automation analytics","tags":["automations"],"description":"Returns stats for a single DM automation.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"analytics":{"type":"object","properties":{"completed":{"type":"integer"},"failed":{"type":"integer"},"triggered":{"type":"integer"}},"required":["completed","failed","triggered"]}},"required":["analytics"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/comments":{"get":{"summary":"List comments","tags":["comments"],"description":"Lists the current user's comments across their connected social accounts, ordered by creation time (most recent first). Supports cursor-based pagination and filtering by platform, account, published post, and creation time window.","parameters":[{"schema":{"minimum":1,"maximum":250,"default":50,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Maximum number of comments to return. Defaults to 50."},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Opaque cursor returned by a previous call. Pass it to fetch the next page."},{"schema":{"type":"array","items":{"type":"string","enum":["facebook","instagram"]}},"example":["instagram","facebook"],"in":"query","name":"platform","required":false,"description":"Filter comments by platform. Pass multiple values to include any of them."},{"schema":{"type":"string"},"in":"query","name":"accountId","required":false,"description":"Filter to comments belonging to a single connected account."},{"schema":{"type":"string"},"in":"query","name":"parentCommentId","required":false,"description":"Filter to direct replies to a single comment."},{"schema":{"type":"string"},"in":"query","name":"postId","required":false,"description":"Filter to comments on a single Blotato-published post. Accepts either the published post ID or the post submission ID returned when the post was published."},{"schema":{"example":"2026-06-01T00:00:00.000Z","type":"string"},"in":"query","name":"since","required":false,"description":"Only include comments created on or after this ISO 8601 timestamp. Omit to apply no lower bound."},{"schema":{"example":"2026-06-30T23:59:59.000Z","type":"string"},"in":"query","name":"until","required":false,"description":"Only include comments created on or before this ISO 8601 timestamp. Omit to apply no upper bound."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"description":"List of comments.","type":"array","items":{"type":"object","properties":{"accountId":{"description":"ID of the social account this comment belongs to.","type":"string"},"authorId":{"description":"Platform-native id of the comment author.","type":"string","nullable":true},"createdAt":{"type":"string"},"errorCode":{"description":"Set only when status is `failed`.","type":"integer","nullable":true},"errorMessage":{"description":"Set only when status is `failed`.","type":"string","nullable":true},"id":{"type":"string"},"isAuthor":{"description":"`true` if the user's own connected account authored this comment.","type":"boolean"},"parentCommentId":{"description":"Blotato id of the parent comment when this comment is a reply. null for top-level comments.","type":"string","nullable":true},"platform":{"type":"string","enum":["facebook","instagram"]},"platformCommentId":{"description":"Platform-native id of the comment.","type":"string","nullable":true},"platformPostId":{"description":"Platform-native id of the parent post being commented on.","type":"string"},"postId":{"description":"Blotato ID of the post (if published through Blotato).","type":"string","nullable":true},"status":{"type":"string","enum":["deleted","failed","posted","processing","queued"]},"text":{"type":"string"}},"required":["accountId","authorId","createdAt","errorCode","errorMessage","id","isAuthor","parentCommentId","platform","platformCommentId","platformPostId","postId","status","text"]}},"cursor":{"description":"Cursor for the next page. Absent when there are no more comments.","type":"string"}},"required":["items"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Validation error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Validation error","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}},"post":{"summary":"Post a comment","tags":["comments"],"description":"Posts a comment on a published post, or a reply to an existing comment on that post when `parentCommentId` is provided.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"postId":{"description":"Blotato id of the published post to comment on.","type":"string"},"text":{"minLength":1,"maxLength":10000,"description":"Plain-text comment body.","type":"string"},"parentCommentId":{"description":"Blotato id of an existing top-level, posted comment on the same post to reply to. Replies to replies are not supported.","type":"string"}},"required":["postId","text"]}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"description":"ID of the social account this comment belongs to.","type":"string"},"authorId":{"description":"Platform-native id of the comment author.","type":"string","nullable":true},"createdAt":{"type":"string"},"errorCode":{"description":"Set only when status is `failed`.","type":"integer","nullable":true},"errorMessage":{"description":"Set only when status is `failed`.","type":"string","nullable":true},"id":{"type":"string"},"isAuthor":{"description":"`true` if the user's own connected account authored this comment.","type":"boolean"},"parentCommentId":{"description":"Blotato id of the parent comment when this comment is a reply. null for top-level comments.","type":"string","nullable":true},"platform":{"type":"string","enum":["facebook","instagram"]},"platformCommentId":{"description":"Platform-native id of the comment.","type":"string","nullable":true},"platformPostId":{"description":"Platform-native id of the parent post being commented on.","type":"string"},"postId":{"description":"Blotato ID of the post (if published through Blotato).","type":"string","nullable":true},"status":{"type":"string","enum":["deleted","failed","posted","processing","queued"]},"text":{"type":"string"}},"required":["accountId","authorId","createdAt","errorCode","errorMessage","id","isAuthor","parentCommentId","platform","platformCommentId","platformPostId","postId","status","text"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Validation error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Validation error","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Rate limit exceeded","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/comments/{commentId}":{"get":{"summary":"Get a comment","tags":["comments"],"description":"Fetches a single comment by its Blotato ID. The comment may be an inbound reply left by the user's audience on one of their posts, or an outbound comment the user posted through Blotato.","parameters":[{"schema":{"type":"string"},"in":"path","name":"commentId","required":true,"description":"Blotato id of the comment to fetch."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"description":"ID of the social account this comment belongs to.","type":"string"},"authorId":{"description":"Platform-native id of the comment author.","type":"string","nullable":true},"createdAt":{"type":"string"},"errorCode":{"description":"Set only when status is `failed`.","type":"integer","nullable":true},"errorMessage":{"description":"Set only when status is `failed`.","type":"string","nullable":true},"id":{"type":"string"},"isAuthor":{"description":"`true` if the user's own connected account authored this comment.","type":"boolean"},"parentCommentId":{"description":"Blotato id of the parent comment when this comment is a reply. null for top-level comments.","type":"string","nullable":true},"platform":{"type":"string","enum":["facebook","instagram"]},"platformCommentId":{"description":"Platform-native id of the comment.","type":"string","nullable":true},"platformPostId":{"description":"Platform-native id of the parent post being commented on.","type":"string"},"postId":{"description":"Blotato ID of the post (if published through Blotato).","type":"string","nullable":true},"status":{"type":"string","enum":["deleted","failed","posted","processing","queued"]},"text":{"type":"string"}},"required":["accountId","authorId","createdAt","errorCode","errorMessage","id","isAuthor","parentCommentId","platform","platformCommentId","platformPostId","postId","status","text"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/credits":{"get":{"summary":"Get credit balance and pricing","tags":["billing"],"description":"Fetches the authenticated account's remaining credits, the account email the credentials belong to, and current credit purchase pricing. Confirm the account email before purchasing credits, since credits are non-transferable between accounts.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Credit balance, the account email, and credit purchase pricing","content":{"application/json":{"schema":{"description":"Credit balance, the account email, and credit purchase pricing","example":{"creditsRemaining":54688,"accountEmail":"user@example.com","purchaseQuantityRange":{"min":1000,"max":10000},"pricePer1000CreditsUsd":6},"type":"object","properties":{"creditsRemaining":{"type":"integer"},"accountEmail":{"type":"string"},"purchaseQuantityRange":{"type":"object","properties":{"min":{"type":"integer"},"max":{"type":"integer"}},"required":["min","max"]},"pricePer1000CreditsUsd":{"type":"number"}},"required":["creditsRemaining","accountEmail","purchaseQuantityRange","pricePer1000CreditsUsd"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Unauthorized access","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}},"post":{"summary":"Buy credits","tags":["billing"],"description":"Creates a Stripe Checkout link the account owner opens in a browser to buy credits (quantity between 1000 and 10000). Creating a link never charges anything; payment happens only when a human completes checkout in the browser, and the purchased credits always land on this account.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"minimum":1000,"maximum":10000,"type":"integer"},"referral":{"type":"string","nullable":true}},"required":["quantity"]}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"A Stripe Checkout link to buy credits.","content":{"application/json":{"schema":{"description":"A Stripe Checkout link to buy credits.","example":{"checkoutUrl":"https://checkout.stripe.com/c/pay/cs_test_123"},"type":"object","properties":{"checkoutUrl":{"description":"Stripe Checkout URL. The account owner opens this in a browser to complete payment. No charge occurs until checkout is completed.","type":"string"}},"required":["checkoutUrl"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Unauthorized access","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Rate limit exceeded","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/media":{"post":{"summary":"Upload media from URL","tags":["publishing"],"description":"# General\n\nThis endpoint allows users to upload media by providing a URL. The uploaded media will be processed and stored, returning a new media URL that is used to publish a new post. Most of the platforms require validated URLs for posting images.\n\nYou can upload:\n\n- publicly accessible URLs\n\n- _base64_ encoded image data\n\nMedia uploads are limited to 1GB file size or smaller.\n\nMedia upload has a user-level rate limit of **10 requests / minute**.\n\n# Upload Google Drive\n\nIf you have a link in google drive like this:\n\n<https://drive.google.com/file/d/18-UgDEaKG7YR7AewIDd_Qi4QCLCX5Kop/view?usp=drivesdk>\n\nYou can use the following link for your Blotato \"upload media\" API call:\n\n<https://drive.google.com/uc?export=download&id=18-UgDEaKG7YR7AewIDd_Qi4QCLCX5Kop>\n\nNote how the IDs match: `18-UgDEaKG7YR7AewIDd_Qi4QCLCX5Kop`\n\nTo see examples of how to upload to Blotato from a Google Drive, you can also check out these tutorials and templates:\n\nn8n: <https://youtu.be/D9okDd_1tBI>\n\nmake: <https://youtu.be/f4Stdm4lDNM>\n\n# Seeing error \"Google Drive can't scan this file for viruses\"?\n\nThis is the **most common issue** when using Google Drive. When you try to access your file, you see this popup \"Google Drive can't scan this file for viruses\".\n\nThe issue is when you host a large video on google drive, it will show this popup, which prevents Blotato from accessing the video.\n\nRecommended workaround: if you're regularly posting large videos (100MB+), I recommend using frame.io, an AWS S3 bucket, or similar tool where there is no issue passing around large video files.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"description":"The URL of the media to upload.","example":"https://example.com/image.jpg","type":"string"}},"required":["url"]}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"description":"Uploaded and validated blotato media URL.","example":"https://database.blotato.io/media/12345.jpg","type":"string"},"id":{"description":"The internal ID of the uploaded media.","example":"media_12345","type":"string"}},"required":["url","id"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Validation error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Validation error","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Rate limit exceeded","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/media/uploads":{"post":{"summary":"Create presigned upload URL","tags":["publishing"],"description":"Creates a presigned URL for direct file upload. Use this when you have a local file to upload rather than a publicly accessible URL. The returned `presignedUrl` accepts a PUT request with the file body, and `publicUrl` is the final media URL to use when publishing a post.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"filename":{"description":"The filename including extension, used to determine content type.","example":"my-video.mp4","type":"string"}},"required":["filename"]}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"presignedUrl":{"description":"URL to PUT the file to. Expires after a short period.","type":"string"},"publicUrl":{"description":"The final public URL of the uploaded media, to be used when creating a post.","type":"string"}},"required":["presignedUrl","publicUrl"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/conversations":{"get":{"summary":"List conversations","tags":["messaging"],"description":"Lists the current user's direct-message conversations from their connected social accounts, ordered by last activity time (most recent first). Supports cursor-based pagination and filtering by platform and account.","parameters":[{"schema":{"minimum":1,"maximum":250,"default":50,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Maximum number of conversations to return. Defaults to 50."},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Opaque cursor returned by a previous call. Pass it to fetch the next page."},{"schema":{"type":"string","enum":["facebook","instagram"]},"in":"query","name":"platform","required":false},{"schema":{"type":"string"},"in":"query","name":"accountId","required":false,"description":"Filter to conversations belonging to a single connected account."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"description":"List of conversations.","type":"array","items":{"type":"object","properties":{"accountId":{"description":"ID of the social account this conversation belongs to.","type":"string"},"createdAt":{"type":"string"},"id":{"type":"string"},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"description":"Platform-native ID of the participant.","type":"string","nullable":true},"name":{"description":"Display name of the participant.","type":"string","nullable":true},"profileImageUrl":{"type":"string","nullable":true},"username":{"description":"Platform handle / @username of the participant.","type":"string","nullable":true}},"required":["id","name","profileImageUrl","username"]}},"platform":{"type":"string","enum":["facebook","instagram"]},"updatedAt":{"type":"string"}},"required":["accountId","createdAt","id","participants","platform","updatedAt"]}},"cursor":{"description":"Cursor for the next page. Absent when there are no more conversations.","type":"string"}},"required":["items"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Validation error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Validation error","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/conversations/{conversationId}":{"get":{"summary":"Get a conversation","tags":["messaging"],"description":"Fetches a single conversation by id, including participant metadata.","parameters":[{"schema":{"type":"string"},"in":"path","name":"conversationId","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"description":"ID of the social account this conversation belongs to.","type":"string"},"createdAt":{"type":"string"},"id":{"type":"string"},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"description":"Platform-native ID of the participant.","type":"string","nullable":true},"name":{"description":"Display name of the participant.","type":"string","nullable":true},"profileImageUrl":{"type":"string","nullable":true},"username":{"description":"Platform handle / @username of the participant.","type":"string","nullable":true}},"required":["id","name","profileImageUrl","username"]}},"platform":{"type":"string","enum":["facebook","instagram"]},"updatedAt":{"type":"string"}},"required":["accountId","createdAt","id","participants","platform","updatedAt"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/messages":{"get":{"summary":"List messages","tags":["messaging"],"description":"Lists the current user's messages from their connected social accounts, ordered by creation time (most recent first). Supports cursor-based pagination and filtering by platform and conversation.","parameters":[{"schema":{"minimum":1,"maximum":250,"default":50,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Maximum number of messages to return. Defaults to 50."},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Opaque cursor returned by a previous call. Pass it to fetch the next page."},{"schema":{"type":"string"},"in":"query","name":"conversationId","required":false,"description":"Filter to messages within a single conversation."},{"schema":{"type":"array","items":{"type":"string","enum":["facebook","instagram"]}},"example":["instagram","facebook"],"in":"query","name":"platform","required":false,"description":"Filter messages by platform. Pass multiple values to include any of them."},{"schema":{"type":"string"},"in":"query","name":"accountId","required":false,"description":"Filter to messages belonging to a single connected account."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"description":"List of messages.","type":"array","items":{"type":"object","properties":{"conversationId":{"description":"Parent Blotato conversation id.","type":"string","nullable":true},"createdAt":{"type":"string"},"direction":{"type":"string","enum":["incoming","outgoing"]},"errorCode":{"description":"Set only when status is `failed`.","type":"integer","nullable":true},"errorMessage":{"description":"Set only when status is `failed`.","type":"string","nullable":true},"id":{"type":"string"},"payload":{"type":"object","properties":{"attachment":{"type":"object","properties":{"type":{"type":"string","enum":["button"]},"buttons":{"minItems":1,"maxItems":3,"description":"Up to 3 call-to-action buttons attached to the message.","type":"array","items":{"type":"object","discriminator":{"propertyName":"type"},"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["web_url"]},"title":{"minLength":1,"maxLength":20,"description":"Button label shown to the recipient.","type":"string"},"url":{"pattern":"^https://","description":"https URL the button opens when tapped.","type":"string"}},"required":["type","title","url"]},{"type":"object","properties":{"type":{"type":"string","enum":["postback"]},"title":{"minLength":1,"maxLength":20,"description":"Button label shown to the recipient.","type":"string"},"payload":{"minLength":1,"maxLength":1000,"description":"Message posted back on tap.","type":"string"}},"required":["type","title","payload"]}]}}},"required":["type","buttons"]},"quickReplies":{"type":"array","items":{"type":"object","properties":{"title":{"minLength":1,"maxLength":20,"description":"Chip label shown to the recipient.","type":"string"},"payload":{"minLength":1,"maxLength":1000,"description":"Message replied with on chip selection.","type":"string"}},"required":["title","payload"]}},"selection":{"type":"object","properties":{"payload":{"type":"string","nullable":true},"type":{"type":"string","enum":["postback","quick-reply"]}},"required":["payload","type"]}},"nullable":true},"platform":{"type":"string","enum":["facebook","instagram"]},"recipientId":{"type":"string"},"senderId":{"type":"string","nullable":true},"status":{"type":"string","enum":["delivered","failed","processing","queued","sent"]},"text":{"type":"string"}},"required":["conversationId","createdAt","direction","errorCode","errorMessage","id","platform","recipientId","senderId","status","text"]}},"cursor":{"description":"Cursor for the next page. Absent when there are no more messages.","type":"string"}},"required":["items"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Validation error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Validation error","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}},"post":{"summary":"Send a message","tags":["messaging"],"description":"Sends a direct message to a single recipient on the specified platform.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"description":"Blotato id of the connected social account the message is sent from.","type":"string"},"target":{"type":"object","discriminator":{"propertyName":"targetType"},"oneOf":[{"type":"object","properties":{"targetType":{"description":"Send via Facebook.","example":"facebook","type":"string","enum":["facebook"]},"pageId":{"pattern":"^\\d+$","description":"ID of the Facebook Page to send from.","example":"123456789","type":"string"},"attachment":{"type":"object","properties":{"type":{"type":"string","enum":["button"]},"buttons":{"minItems":1,"maxItems":3,"description":"Up to 3 call-to-action buttons attached to the message.","type":"array","items":{"type":"object","discriminator":{"propertyName":"type"},"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["web_url"]},"title":{"minLength":1,"maxLength":20,"description":"Button label shown to the recipient.","type":"string"},"url":{"pattern":"^https://","description":"https URL the button opens when tapped.","type":"string"}},"required":["type","title","url"]},{"type":"object","properties":{"type":{"type":"string","enum":["postback"]},"title":{"minLength":1,"maxLength":20,"description":"Button label shown to the recipient.","type":"string"},"payload":{"minLength":1,"maxLength":1000,"description":"Message posted back on tap.","type":"string"}},"required":["type","title","payload"]}]}}},"required":["type","buttons"]},"commentId":{"description":"Blotato comment ID. When set, the message is delivered as a private reply to that comment instead of a direct message.","type":"string"},"quickReplies":{"minItems":1,"maxItems":13,"type":"array","items":{"type":"object","properties":{"title":{"minLength":1,"maxLength":20,"description":"Chip label shown to the recipient.","type":"string"},"payload":{"minLength":1,"maxLength":1000,"description":"Message replied with on chip selection.","type":"string"}},"required":["title","payload"]}},"responseType":{"type":"string","enum":["RESPONSE","UPDATE","MESSAGE_TAG"]},"tag":{"description":"Required when responseType is MESSAGE_TAG (e.g. HUMAN_AGENT).","type":"string"}},"required":["targetType","pageId"]},{"type":"object","properties":{"targetType":{"description":"Send via Instagram.","example":"instagram","type":"string","enum":["instagram"]},"attachment":{"type":"object","properties":{"type":{"type":"string","enum":["button"]},"buttons":{"minItems":1,"maxItems":3,"description":"Up to 3 call-to-action buttons attached to the message.","type":"array","items":{"type":"object","discriminator":{"propertyName":"type"},"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["web_url"]},"title":{"minLength":1,"maxLength":20,"description":"Button label shown to the recipient.","type":"string"},"url":{"pattern":"^https://","description":"https URL the button opens when tapped.","type":"string"}},"required":["type","title","url"]},{"type":"object","properties":{"type":{"type":"string","enum":["postback"]},"title":{"minLength":1,"maxLength":20,"description":"Button label shown to the recipient.","type":"string"},"payload":{"minLength":1,"maxLength":1000,"description":"Message posted back on tap.","type":"string"}},"required":["type","title","payload"]}]}}},"required":["type","buttons"]},"responseType":{"type":"string","enum":["RESPONSE","UPDATE","MESSAGE_TAG"]},"commentId":{"description":"Blotato comment ID. When set, the message is delivered as a private reply to that comment instead of a direct message.","type":"string"},"quickReplies":{"minItems":1,"maxItems":13,"type":"array","items":{"type":"object","properties":{"title":{"minLength":1,"maxLength":20,"description":"Chip label shown to the recipient.","type":"string"},"payload":{"minLength":1,"maxLength":1000,"description":"Message replied with on chip selection.","type":"string"}},"required":["title","payload"]}},"tag":{"description":"Required when responseType is MESSAGE_TAG (e.g. HUMAN_AGENT).","type":"string"}},"required":["targetType"]}]},"recipientId":{"description":"Platform-native id of the recipient (e.g. Instagram business-scoped user id).","type":"string"},"text":{"minLength":1,"maxLength":10000,"description":"Plain-text message body.","type":"string"}},"required":["accountId","target","recipientId","text"]}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"conversationId":{"description":"Parent Blotato conversation id.","type":"string","nullable":true},"createdAt":{"type":"string"},"direction":{"type":"string","enum":["incoming","outgoing"]},"errorCode":{"description":"Set only when status is `failed`.","type":"integer","nullable":true},"errorMessage":{"description":"Set only when status is `failed`.","type":"string","nullable":true},"id":{"type":"string"},"payload":{"type":"object","properties":{"attachment":{"type":"object","properties":{"type":{"type":"string","enum":["button"]},"buttons":{"minItems":1,"maxItems":3,"description":"Up to 3 call-to-action buttons attached to the message.","type":"array","items":{"type":"object","discriminator":{"propertyName":"type"},"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["web_url"]},"title":{"minLength":1,"maxLength":20,"description":"Button label shown to the recipient.","type":"string"},"url":{"pattern":"^https://","description":"https URL the button opens when tapped.","type":"string"}},"required":["type","title","url"]},{"type":"object","properties":{"type":{"type":"string","enum":["postback"]},"title":{"minLength":1,"maxLength":20,"description":"Button label shown to the recipient.","type":"string"},"payload":{"minLength":1,"maxLength":1000,"description":"Message posted back on tap.","type":"string"}},"required":["type","title","payload"]}]}}},"required":["type","buttons"]},"quickReplies":{"type":"array","items":{"type":"object","properties":{"title":{"minLength":1,"maxLength":20,"description":"Chip label shown to the recipient.","type":"string"},"payload":{"minLength":1,"maxLength":1000,"description":"Message replied with on chip selection.","type":"string"}},"required":["title","payload"]}},"selection":{"type":"object","properties":{"payload":{"type":"string","nullable":true},"type":{"type":"string","enum":["postback","quick-reply"]}},"required":["payload","type"]}},"nullable":true},"platform":{"type":"string","enum":["facebook","instagram"]},"recipientId":{"type":"string"},"senderId":{"type":"string","nullable":true},"status":{"type":"string","enum":["delivered","failed","processing","queued","sent"]},"text":{"type":"string"}},"required":["conversationId","createdAt","direction","errorCode","errorMessage","id","platform","recipientId","senderId","status","text"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Validation error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Validation error","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Rate limit exceeded","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/messages/{messageId}":{"get":{"summary":"Get a message","tags":["messaging"],"description":"Fetches a single direct message by its Blotato ID. The message may be an inbound message received from a contact, or an outbound message the user sent through Blotato.","parameters":[{"schema":{"type":"string"},"in":"path","name":"messageId","required":true,"description":"Blotato id of the message to fetch."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"conversationId":{"description":"Parent Blotato conversation id.","type":"string","nullable":true},"createdAt":{"type":"string"},"direction":{"type":"string","enum":["incoming","outgoing"]},"errorCode":{"description":"Set only when status is `failed`.","type":"integer","nullable":true},"errorMessage":{"description":"Set only when status is `failed`.","type":"string","nullable":true},"id":{"type":"string"},"payload":{"type":"object","properties":{"attachment":{"type":"object","properties":{"type":{"type":"string","enum":["button"]},"buttons":{"minItems":1,"maxItems":3,"description":"Up to 3 call-to-action buttons attached to the message.","type":"array","items":{"type":"object","discriminator":{"propertyName":"type"},"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["web_url"]},"title":{"minLength":1,"maxLength":20,"description":"Button label shown to the recipient.","type":"string"},"url":{"pattern":"^https://","description":"https URL the button opens when tapped.","type":"string"}},"required":["type","title","url"]},{"type":"object","properties":{"type":{"type":"string","enum":["postback"]},"title":{"minLength":1,"maxLength":20,"description":"Button label shown to the recipient.","type":"string"},"payload":{"minLength":1,"maxLength":1000,"description":"Message posted back on tap.","type":"string"}},"required":["type","title","payload"]}]}}},"required":["type","buttons"]},"quickReplies":{"type":"array","items":{"type":"object","properties":{"title":{"minLength":1,"maxLength":20,"description":"Chip label shown to the recipient.","type":"string"},"payload":{"minLength":1,"maxLength":1000,"description":"Message replied with on chip selection.","type":"string"}},"required":["title","payload"]}},"selection":{"type":"object","properties":{"payload":{"type":"string","nullable":true},"type":{"type":"string","enum":["postback","quick-reply"]}},"required":["payload","type"]}},"nullable":true},"platform":{"type":"string","enum":["facebook","instagram"]},"recipientId":{"type":"string"},"senderId":{"type":"string","nullable":true},"status":{"type":"string","enum":["delivered","failed","processing","queued","sent"]},"text":{"type":"string"}},"required":["conversationId","createdAt","direction","errorCode","errorMessage","id","platform","recipientId","senderId","status","text"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/integrations/oauth2/linkedin/pages":{"get":{"summary":"List LinkedIn pages","tags":["accounts"],"description":"Lists the organization pages the connected LinkedIn account can administer, so the user can choose which to add as posting targets.","parameters":[{"schema":{"type":"string"},"in":"query","name":"accountId","required":true,"description":"Blotato account id, returned from /users/me/accounts."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"description":"LinkedIn ID of the organization page.","type":"string"},"name":{"description":"Display name of the organization page.","type":"string"},"isActive":{"description":"Whether Blotato is already connected to this page.","type":"boolean"}},"required":["id","name","isActive"]}}},"required":["items"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Unauthorized access","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/social/pinterest/boards":{"get":{"summary":"List Pinterest boards","tags":["accounts"],"description":"Lists boards owned by a connected Pinterest account. Returns the id and name of each board so callers can pick the boardId required when creating a Pinterest pin via blotato_create_post.","parameters":[{"schema":{"type":"string"},"in":"query","name":"accountId","required":true,"description":"Blotato Pinterest account id, returned from /users/me/accounts."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"description":"Pinterest boards owned by the connected account. Capped at 250 (the Pinterest page_size limit).","type":"array","items":{"example":{"id":"1234567890123456789","name":"Summer Outfits"},"type":"object","properties":{"id":{"description":"Pinterest board id. Pass this as boardId when creating a pin.","type":"string"},"name":{"description":"Display name of the board on Pinterest.","type":"string"}},"required":["id","name"]}}},"required":["items"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Unauthorized access","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/posts":{"get":{"summary":"List posts","tags":["publishing"],"description":"Lists the current user's posts (scheduled, published, and failed) within a time window, ordered by post time (most recent first). Supports cursor-based pagination and filtering by status and platform. Post listing has a user-level rate limit of **60 requests / minute**.","parameters":[{"schema":{"example":"2026-08-22T23:38:47.407Z","type":"string"},"in":"query","name":"since","required":false,"description":"Only include posts whose post time is on or after this ISO 8601 timestamp. Defaults to 7 days ago."},{"schema":{"example":"2026-09-05T23:38:47.408Z","type":"string"},"in":"query","name":"until","required":false,"description":"Only include posts whose post time is on or before this ISO 8601 timestamp. Defaults to 7 days from now."},{"schema":{"minimum":1,"maximum":250,"default":50,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Maximum number of posts to return. Defaults to 50."},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Opaque cursor returned by a previous call. Pass it to fetch the next page."},{"schema":{"type":"array","items":{"type":"string","enum":["scheduled","published","failed"]}},"example":["scheduled","published"],"in":"query","name":"status","required":false,"description":"Filter posts by status. Pass multiple values to include any of them. Omit to include all statuses."},{"schema":{"type":"array","items":{"description":"Social media platform","example":"twitter","type":"string","enum":["twitter","instagram","linkedin","facebook","tiktok","pinterest","threads","bluesky","youtube","other"]}},"example":["twitter","instagram"],"in":"query","name":"platform","required":false,"description":"Filter posts by social media platform. Pass multiple values to include any of them. Omit to include all platforms."},{"schema":{"type":"string","enum":["blotato","all"]},"in":"query","name":"source","required":false,"description":"Which published posts to include: 'blotato' (default) returns only posts published through Blotato; 'all' also includes any externally-published posts that were brought into Blotato."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"description":"List of posts","type":"array","items":{"allOf":[{"type":"object","properties":{"id":{"type":"string"},"postTime":{"type":"string"},"state":{"type":"object","discriminator":{"propertyName":"type"},"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["scheduled"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["published"]},"postUrl":{"type":"string","nullable":true}},"required":["type","postUrl"]},{"type":"object","properties":{"type":{"type":"string","enum":["failed"]},"errorMessage":{"type":"string","nullable":true}},"required":["type","errorMessage"]}]}},"required":["id","postTime","state"]},{"type":"object","allOf":[{"type":"object","properties":{"text":{"description":"The text content of the post.","example":"My text","type":"string"},"mediaUrls":{"description":"List of media URLs to include in the post.","maxItems":20,"type":"array","items":{"description":"URLs of media files (images, videos) to include in the post. Must originate from the blotato domain. Use the media upload endpoint to upload media files before publishing.","example":"https://database.blotato.io/some-image-path.jpg","type":"string"}}},"required":["text","mediaUrls"]},{"type":"object","properties":{"platform":{"description":"Social media platform","example":"twitter","type":"string","enum":["twitter","instagram","linkedin","facebook","tiktok","pinterest","threads","bluesky","youtube","other"]}},"required":["platform"]}]}]}},"cursor":{"description":"Cursor for the next page. Absent when there are no more posts.","type":"string"}},"required":["items"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Validation error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Validation error","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}},"post":{"summary":"Create a new post","tags":["publishing"],"description":"# General\n\nCreates a new post with the provided content and optional scheduling. The post can be published immediately or scheduled for a later time.\n\nEvery post is scheduled on a queue. Failed posts are available at <https://my.blotato.com/failed>. The most common issue of failed post is incorrect JSON structure. Please make sure that JSON payload conforms to the structure described above. If you are still having trouble with identifying the issue, please contact support via Intercom and provide your `postSubmissionId`.\n\nPost creation has a user-level rate limit of **30 requests / minute** to prevent spamming / abusing social media endpoints\n\n\n# Examples\n\n## Post to a Platform Immediately\n\n```\nPOST https://backend.blotato.com/v2/posts HTTP/1.1\nContent-Type: application/json\nHeaders:\n\n{\n  \"post\": {\n    \"accountId\": \"acc_12345\",\n    \"content\": {\n      \"text\": \"Hello, world!\",\n      \"mediaUrls\": [],\n      \"platform\": \"twitter\"\n    },\n    \"target\": {\n      \"targetType\": \"twitter\"\n    }\n  }\n}\n```\n\n## Post at a Scheduled Time\n\n```\nPOST https://backend.blotato.com/v2/posts HTTP/1.1\nContent-Type: application/json\n\n{\n  \"post\": {\n    \"accountId\": \"acc_67890\",\n    \"content\": {\n      \"text\": \"Scheduled post example\",\n      \"mediaUrls\": [],\n      \"platform\": \"facebook\"\n    },\n    \"target\": {\n      \"targetType\": \"facebook\",\n      \"pageId\": \"987654321\"\n    }\n  },\n  \"scheduledTime\": \"2025-03-10T15:30:00Z\"\n}\n```\n\n## Post an Image or a Video\n\n```\nPOST https://backend.blotato.com/v2/posts HTTP/1.1\nContent-Type: application/json\n\n{\n  \"post\": {\n    \"accountId\": \"acc_24680\",\n    \"content\": {\n      \"text\": \"Check out this image!\",\n      \"mediaUrls\": [\n        \"https://example.com/image1.jpg\",\n        \"https://example.com/image2.jpg\"\n      ],\n      \"platform\": \"instagram\"\n    },\n    \"target\": {\n      \"targetType\": \"instagram\"\n    }\n  }\n}\n```\n\n## Post a Twitter-like Thread with Multiple Posts\n\n```\nPOST https://backend.blotato.com/v2/posts HTTP/1.1\nContent-Type: application/json\nHeaders:\n\nPOST https://backend.blotato.com/v2/posts HTTP/1.1\nContent-Type: application/json\n\n{\n  \"post\": {\n    \"accountId\": \"acc_13579\",\n    \"content\": {\n      \"text\": \"This is the first tweet in the thread.\",\n      \"mediaUrls\": [],\n      \"platform\": \"twitter\",\n      \"additionalPosts\": [\n        {\n          \"text\": \"Here's the second tweet, adding more info.\",\n          \"mediaUrls\": []\n        },\n        {\n          \"text\": \"And here's the third tweet to conclude!\",\n          \"mediaUrls\": []\n        }\n      ]\n    },\n    \"target\": {\n      \"targetType\": \"twitter\"\n    }\n  }\n}\n```","requestBody":{"required":true,"content":{"application/json":{"schema":{"example":{"post":{"target":{"targetType":"tiktok","isYourBrand":false,"autoAddMusic":false,"disabledDuet":false,"privacyLevel":"SELF_ONLY","isAiGenerated":false,"disabledStitch":false,"disabledComments":false,"isBrandedContent":false},"content":{"text":"Hello, blotato!","mediaUrls":["https://database.blotato.io/some-media-path.mp4"]}}},"type":"object","properties":{"post":{"type":"object","properties":{"accountId":{"description":"The ID of the social media account to publish the content to.","example":"1","type":"string"},"content":{"type":"object","allOf":[{"type":"object","properties":{"text":{"description":"The text content of the post.","example":"My text","type":"string"},"mediaUrls":{"description":"List of media URLs to include in the post.","maxItems":20,"type":"array","items":{"description":"URLs of media files (images, videos) to include in the post. Must originate from the blotato domain. Use the media upload endpoint to upload media files before publishing.","example":"https://database.blotato.io/some-image-path.jpg","type":"string"}}},"required":["text","mediaUrls"]},{"type":"object","properties":{"platform":{"description":"Social media platform","example":"twitter","type":"string","enum":["twitter","instagram","linkedin","facebook","tiktok","pinterest","threads","bluesky","youtube","other"]},"additionalPosts":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"text":{"description":"The text content of the post.","example":"My text","type":"string"},"mediaUrls":{"description":"List of media URLs to include in the post.","maxItems":20,"type":"array","items":{"description":"URLs of media files (images, videos) to include in the post. Must originate from the blotato domain. Use the media upload endpoint to upload media files before publishing.","example":"https://database.blotato.io/some-image-path.jpg","type":"string"}}},"required":["text","mediaUrls"]}}},"required":["platform"]}]},"target":{"type":"object","discriminator":{"propertyName":"targetType"},"oneOf":[{"type":"object","properties":{"targetType":{"description":"Publish to a custom webhook.","example":"webhook","type":"string","enum":["webhook"]},"url":{"minLength":1,"description":"The URL of the webhook to publish to.","example":"https://example.com/webhook","type":"string"}},"required":["targetType","url"]},{"type":"object","properties":{"targetType":{"description":"Publish to Twitter.","example":"twitter","type":"string","enum":["twitter"]}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to LinkedIn.","example":"linkedin","type":"string","enum":["linkedin"]},"pageId":{"minLength":1,"description":"The ID of the LinkedIn page to publish to.","example":"123456789","type":"string"}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to Facebook.","example":"facebook","type":"string","enum":["facebook"]},"pageId":{"pattern":"^\\d+$","description":"The ID of the Facebook page to publish to.","example":"123456789","type":"string"},"mediaType":{"description":"Whether the media is a reel or video.","example":"reel","type":"string","enum":["reel","story"]},"link":{"minLength":1,"description":"Link preview to attach to the Facebook post.","example":"https://blotato.com","type":"string"},"firstComment":{"minLength":1,"maxLength":8000,"description":"Auto-posted comment on posts and reels, immediately after publish. Not supported for stories.","example":"First comment!","type":"string"}},"required":["targetType","pageId"]},{"type":"object","properties":{"targetType":{"description":"Publish to Instagram.","example":"instagram","type":"string","enum":["instagram"]},"mediaType":{"description":"Whether the media is a reel or story.","example":"reel","type":"string","enum":["reel","story"]},"altText":{"minLength":1,"maxLength":1000,"description":"Alternative text, for accessibility purposes. Only supported on a single image or image media in a carousel.","example":"Describe the image here for accessibility","type":"string"},"shareToFeed":{"description":"Whether to also share the reel to the Instagram feed. Only applicable for reels.","example":false,"type":"boolean"},"audioName":{"minLength":1,"maxLength":2200,"description":"For Reels only. Name of the audio of your Reels media. You can only rename once, either while creating a reel or after from the audio page.","example":"My Custom Audio Name","type":"string"},"collaborators":{"description":"List of collaborators to add to the Instagram post.","minItems":1,"maxItems":3,"type":"array","items":{"minLength":1,"description":"The Instagram usernames of the collaborator to add to the post.","example":"instagram_username","type":"string"}},"coverImageUrl":{"minLength":1,"description":"URL of the cover image to use for the Instagram post. Use the media upload endpoint to upload media files before publishing. Maximum file size is 8MB. Only applicable to reels.","example":"https://database.blotato.io/some-image-path.jpg","type":"string"},"trial":{"description":"Settings for trial reels. Trial reels are shown only to non-followers.","type":"object","properties":{"graduationStrategy":{"description":"Strategy to use to determine when to graduate post from trial (convert the trial reel to a reel, sharing it to followers).","example":"SS_PERFORMANCE","type":"string","enum":["MANUAL","SS_PERFORMANCE"]}},"required":["graduationStrategy"]},"firstComment":{"minLength":1,"maxLength":2200,"description":"Auto-posted comment with feed posts and carousels, immediately after publish. Not supported for stories. Useful for links.","example":"Link in the first comment!","type":"string"}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to TikTok.","example":"tiktok","type":"string","enum":["tiktok"]},"privacyLevel":{"description":"The privacy level of the TikTok post.","example":"SELF_ONLY","type":"string","enum":["SELF_ONLY","PUBLIC_TO_EVERYONE","MUTUAL_FOLLOW_FRIENDS","FOLLOWER_OF_CREATOR"]},"disabledComments":{"description":"Whether to disable comments on the TikTok post.","example":false,"type":"boolean"},"disabledDuet":{"description":"Whether to disable duet on the TikTok post.","example":false,"type":"boolean"},"disabledStitch":{"description":"Whether to disable stitch on the TikTok post.","example":false,"type":"boolean"},"isBrandedContent":{"description":"Whether the TikTok post is branded content.","example":false,"type":"boolean"},"isYourBrand":{"description":"Whether the TikTok post is for your brand.","example":false,"type":"boolean"},"isAiGenerated":{"description":"Whether the TikTok post is AI-generated.","example":false,"type":"boolean"},"title":{"minLength":1,"maxLength":90,"description":"Title for the image posts. If notprovided, the first 90 characters of the post.content.text will be used.","example":"My TikTok Image Post Title","type":"string"},"autoAddMusic":{"description":"Whether to automatically add music to the TikTok image posts.","example":false,"type":"boolean"},"isDraft":{"description":"Don't publish the post immediately, save it as a draft instead. Default is false.","example":true,"type":"boolean"},"imageCoverIndex":{"minimum":0,"description":"Index of the image (starts from 0) to use as the cover for carousel posts. Only applicable for carousel image posts.","example":0,"type":"number"},"videoCoverTimestamp":{"minimum":0,"description":"Location in milliseconds of the video to use as the cover image. Only applicable for video posts. If not provided, the frame as 0 milliseconds will be used.","example":0,"type":"number"}},"required":["targetType","privacyLevel","disabledComments","disabledDuet","disabledStitch","isBrandedContent","isYourBrand","isAiGenerated"]},{"type":"object","properties":{"targetType":{"description":"Publish to Pinterest.","example":"pinterest","type":"string","enum":["pinterest"]},"boardId":{"minLength":1,"description":"The ID of the Pinterest board to publish to.","example":"123456789","type":"string"},"title":{"minLength":1,"maxLength":100,"description":"Title for the Pinterest post.","example":"My Pinterest Post Title","type":"string"},"link":{"maxLength":2048,"description":"Link for the Pinterest post.","example":"https://example.com/my-pinterest-post-link","type":"string"},"altText":{"maxLength":500,"description":"Alternative text for the Pinterest post, for accessibility purposes.","example":"Describe the image here for accessibility","type":"string"}},"required":["targetType","boardId"]},{"type":"object","properties":{"targetType":{"description":"Publish to Threads.","example":"threads","type":"string","enum":["threads"]},"replyControl":{"description":"Who can reply to the Threads post.","example":"everyone","type":"string","enum":["everyone","accounts_you_follow","mentioned_only"]}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to Bluesky.","example":"bluesky","type":"string","enum":["bluesky"]}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to YouTube.","example":"youtube","type":"string","enum":["youtube"]},"title":{"minLength":1,"maxLength":100,"pattern":"^[^<>]*$","description":"Title for the YouTube post. Must not contain any of the following characters: <>","errorMessage":{"pattern":"must not contain any of the following characters: <>"},"type":"string"},"privacyStatus":{"description":"The privacy status of the YouTube post.","example":"private","type":"string","enum":["private","public","unlisted"]},"shouldNotifySubscribers":{"description":"Whether to notify subscribers about the YouTube post.","example":false,"type":"boolean"},"isMadeForKids":{"description":"Whether the YouTube post is made for kids.","example":false,"type":"boolean"},"containsSyntheticMedia":{"description":"Whether the media contains synthetic content, such as AI-generated images or deepfake videos. Default is false.","example":false,"type":"boolean"},"thumbnailUrl":{"minLength":1,"description":"URL of the custom thumbnail image for the YouTube video. Use the media upload endpoint to upload media files before publishing. Maximum file size is 2MB. Accepted formats: JPEG, PNG. Recommended: 1280x720 (16:9).","example":"https://database.blotato.io/some-thumbnail.jpg","type":"string"},"playlistIds":{"description":"YouTube playlist IDs to add the video to after upload.","maxItems":5,"type":"array","items":{"type":"string"}}},"required":["targetType","title","privacyStatus","shouldNotifySubscribers"]}]}},"required":["accountId","content","target"]},"postDraftId":{"description":"The ID of the existing post draft to use for creating the post. Unused in the API call","example":"12345","type":"string"},"useNextFreeSlot":{"description":"If provided, indicates whether to use the next available free slot for scheduling the post. If set to true, the post will be scheduled at the next available slot time for the specified platform. If neither `scheduledTime` nor `slot` is provided, and this is set to true, the post will be scheduled at the next available slot time.","type":"boolean"},"slot":{"description":"The schedule slot to use for scheduling the post. If neither `scheduledTime` nor `slot` is provided, the post will be published immediately.","type":"object","properties":{"id":{"description":"The ID of the schedule slot to use for scheduling.","example":"123","type":"string"},"time":{"description":"The timestamp (ISO 8601) when the post should be published.","example":"2026-09-05T23:38:47.408Z","type":"string"}},"required":["id","time"]},"scheduledTime":{"description":"The timestamp (ISO 8601) when the post should be published.","example":"2026-09-05T23:38:47.408Z","type":"string"}},"required":["post"]}}}},"security":[{"apiKey":[]}],"responses":{"200":{"description":"Submitted","content":{"application/json":{"schema":{"description":"Submitted","type":"object","properties":{"postSubmissionId":{"description":"The ID of the post submission. Use this ID to track the status of the post. This status code is returned when the post is already scheduled.","example":"123e4567-e89b-12d3-a456-426614174000","type":"string"},"scheduledTime":{"description":"The resolved UTC time the post is scheduled to publish. Omitted when the post is published immediately.","example":"2025-03-10T15:30:00Z","type":"string"}},"required":["postSubmissionId"]}}}},"201":{"description":"Submitted","content":{"application/json":{"schema":{"description":"Submitted","type":"object","properties":{"postSubmissionId":{"description":"The ID of the post submission. Use this ID to track the status of the post.","example":"123e4567-e89b-12d3-a456-426614174000","type":"string"},"scheduledTime":{"description":"The resolved UTC time the post is scheduled to publish. Omitted when the post is published immediately.","example":"2025-03-10T15:30:00Z","type":"string"}},"required":["postSubmissionId"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Validation error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Validation error","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Rate limit exceeded","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/posts/{postSubmissionId}":{"get":{"summary":"Get post status","tags":["publishing"],"description":"Fetches the status of a post by its submission ID. This is useful for checking if a post was successfully published or if it failed. Post lookup has a user-level rate limit of **60 requests / minute** to prevent spamming / abusing social media endpoints","parameters":[{"schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"},"in":"path","name":"postSubmissionId","required":true,"description":"The ID of the post submission to check."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"postSubmissionId":{"description":"The ID of the post submission.","example":"123e4567-e89b-12d3-a456-426614174000","type":"string"},"status":{"description":"The current status of the post.","example":"published","type":"string","enum":["in-progress","failed","published","scheduled"]},"scheduledTime":{"description":"The scheduled time of the post if it is scheduled. Null if the post was published immediately.","example":"2025-03-11T15:30:00.000Z","type":"string"},"publicUrl":{"description":"The public URL of the post if it was published.","example":"https://x.com/post/12345","type":"string"},"errorMessage":{"description":"The error message if the post failed.","example":"Unsupported media type","type":"string"}},"required":["postSubmissionId","status"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Rate limit exceeded","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/posts/{id}/analytics":{"get":{"summary":"Get analytics for a published post","tags":["analytics"],"description":"Returns the latest known analytics and snapshot history for a published post. This endpoint does not trigger a re-fetch.","parameters":[{"schema":{"example":"12345","type":"string"},"in":"path","name":"id","required":true,"description":"The id of the published post."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"publishedPostId":{"description":"The id of the published post.","example":"12345","type":"string"},"platform":{"description":"Social media platform","example":"twitter","type":"string","enum":["twitter","instagram","linkedin","facebook","tiktok","pinterest","threads","bluesky","youtube","other"]},"lastFetchedAt":{"type":"string","nullable":true},"lastError":{"type":"string","nullable":true},"metrics":{"type":"object","properties":{"clicksCount":{"type":"string"},"commentsCount":{"type":"string"},"followsCount":{"type":"string"},"impressionsCount":{"type":"string"},"interactionsSum":{"type":"string"},"likesCount":{"type":"string"},"navigationsCount":{"type":"string"},"playsCount":{"type":"string"},"profileActivityCount":{"type":"string"},"profileVisitsCount":{"type":"string"},"reachCount":{"type":"string"},"repliesCount":{"type":"string"},"savesCount":{"type":"string"},"sharesCount":{"type":"string"},"viewTimeMsSum":{"type":"string"},"viewsCount":{"type":"string"},"watchTimeMsAvg":{"type":"string"},"twitterRetweetsCount":{"type":"string"},"twitterQuotesCount":{"type":"string"},"blueskyRepostsCount":{"type":"string"},"blueskyQuotesCount":{"type":"string"},"threadsRepostsCount":{"type":"string"},"threadsQuotesCount":{"type":"string"},"linkedinFirstLevelCommentsCount":{"type":"string"},"linkedinReactionsByType":{"type":"object","additionalProperties":{"type":"string"}},"pinterestPinClicksCount":{"type":"string"},"pinterestReactionsCount":{"type":"string"},"pinterestVideoP95ViewsCount":{"type":"string"},"pinterestVideo10sViewsCount":{"type":"string"},"pinterestVideoMrcViewsCount":{"type":"string"},"pinterestVideoV50WatchTimeMsSum":{"type":"string"},"pinterestSaveRate":{"type":"number"},"twitterPerMediaVideoViewsCount":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlaybackStartCount":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlayback25Count":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlayback50Count":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlayback75Count":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlaybackCompleteCount":{"type":"array","items":{"type":"string","nullable":true}},"facebookPostMediaViewsCount":{"type":"string"},"facebookPostMediaViewsUniqueCount":{"type":"string"},"facebookPostReactionsByType":{"type":"object","additionalProperties":{"type":"string"}},"facebookBlueReelsPlaysCount":{"type":"string"},"facebookFbReelsReplaysCount":{"type":"string"},"facebookFbReelsTotalPlaysCount":{"type":"string"},"facebookPostVideoWatchTimeMsAvg":{"type":"string"},"facebookPostVideoFollowersCount":{"type":"string"},"facebookPostVideoLikesByReactionType":{"type":"object","additionalProperties":{"type":"string"}},"facebookPostVideoSocialActionsByType":{"type":"object","additionalProperties":{"type":"string"}},"facebookPostVideoViewTimeMsSum":{"type":"string"},"facebookTotalVideoViewsCount":{"type":"string"},"facebookTotalVideoViewsUniqueCount":{"type":"string"},"facebookTotalVideoViewsAutoplayedCount":{"type":"string"},"facebookTotalVideoViewsClickedToPlayCount":{"type":"string"},"facebookTotalVideoViewsSoundOnCount":{"type":"string"},"facebookTotalVideoCompleteViewsCount":{"type":"string"},"facebookTotalVideoCompleteViewsUniqueCount":{"type":"string"},"facebookTotalVideoCompleteViewsAutoplayedCount":{"type":"string"},"facebookTotalVideoCompleteViewsClickedToPlayCount":{"type":"string"},"facebookTotalVideoCompleteViewsOrganicCount":{"type":"string"},"facebookTotalVideoCompleteViewsOrganicUniqueCount":{"type":"string"},"facebookTotalVideoCompleteViewsPaidCount":{"type":"string"},"facebookTotalVideoCompleteViewsPaidUniqueCount":{"type":"string"},"facebookTotalVideoViews10sCount":{"type":"string"},"facebookTotalVideoViews10sUniqueCount":{"type":"string"},"facebookTotalVideoViews10sAutoplayedCount":{"type":"string"},"facebookTotalVideoViews10sClickedToPlayCount":{"type":"string"},"facebookTotalVideoViews10sOrganicCount":{"type":"string"},"facebookTotalVideoViews10sPaidCount":{"type":"string"},"facebookTotalVideoViews10sSoundOnCount":{"type":"string"},"facebookTotalVideoViews15sCount":{"type":"string"},"facebookTotalVideoViews60sExcludesShorterCount":{"type":"string"},"facebookTotalVideoWatchTimeMsAvg":{"type":"string"},"facebookTotalVideoViewTimeMsSum":{"type":"string"},"facebookTotalVideoViewTimeOrganicMsSum":{"type":"string"},"facebookTotalVideoViewTimePaidMsSum":{"type":"string"},"facebookTotalVideoStoriesByActionType":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoReactionsByType":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoViewTimeMsByAgeBucketAndGender":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoViewTimeMsByRegionId":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoViewsByDistributionType":{"type":"object","additionalProperties":{"type":"string"}},"youtubeDislikesCount":{"type":"string"},"youtubeSubscribersLostCount":{"type":"string"},"youtubeVideosAddedToPlaylistsCount":{"type":"string"},"youtubeVideosRemovedFromPlaylistsCount":{"type":"string"},"youtubeRedViewsCount":{"type":"string"},"youtubeRedViewTimeMsSum":{"type":"string"},"youtubeEngagedViewsCount":{"type":"string"},"youtubeAverageViewPercentage":{"type":"number"},"youtubeCardClicksCount":{"type":"string"},"youtubeCardImpressionsCount":{"type":"string"},"youtubeCardClickRate":{"type":"number"},"youtubeCardTeaserClicksCount":{"type":"string"},"youtubeCardTeaserImpressionsCount":{"type":"string"},"youtubeCardTeaserClickRate":{"type":"number"},"youtubeAnnotationClicksCount":{"type":"string"},"youtubeAnnotationClickableImpressionsCount":{"type":"string"},"youtubeAnnotationClosesCount":{"type":"string"},"youtubeAnnotationClosableImpressionsCount":{"type":"string"},"youtubeAnnotationImpressionsCount":{"type":"string"},"youtubeAnnotationClickThroughRate":{"type":"number"},"youtubeAnnotationCloseRate":{"type":"number"}},"nullable":true},"history":{"type":"array","items":{"type":"object","properties":{"fetchedAt":{"description":"ISO 8601 timestamp when metrics were captured.","type":"string"},"metrics":{"type":"object","properties":{"clicksCount":{"type":"string"},"commentsCount":{"type":"string"},"followsCount":{"type":"string"},"impressionsCount":{"type":"string"},"interactionsSum":{"type":"string"},"likesCount":{"type":"string"},"navigationsCount":{"type":"string"},"playsCount":{"type":"string"},"profileActivityCount":{"type":"string"},"profileVisitsCount":{"type":"string"},"reachCount":{"type":"string"},"repliesCount":{"type":"string"},"savesCount":{"type":"string"},"sharesCount":{"type":"string"},"viewTimeMsSum":{"type":"string"},"viewsCount":{"type":"string"},"watchTimeMsAvg":{"type":"string"},"twitterRetweetsCount":{"type":"string"},"twitterQuotesCount":{"type":"string"},"blueskyRepostsCount":{"type":"string"},"blueskyQuotesCount":{"type":"string"},"threadsRepostsCount":{"type":"string"},"threadsQuotesCount":{"type":"string"},"linkedinFirstLevelCommentsCount":{"type":"string"},"linkedinReactionsByType":{"type":"object","additionalProperties":{"type":"string"}},"pinterestPinClicksCount":{"type":"string"},"pinterestReactionsCount":{"type":"string"},"pinterestVideoP95ViewsCount":{"type":"string"},"pinterestVideo10sViewsCount":{"type":"string"},"pinterestVideoMrcViewsCount":{"type":"string"},"pinterestVideoV50WatchTimeMsSum":{"type":"string"},"pinterestSaveRate":{"type":"number"},"twitterPerMediaVideoViewsCount":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlaybackStartCount":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlayback25Count":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlayback50Count":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlayback75Count":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlaybackCompleteCount":{"type":"array","items":{"type":"string","nullable":true}},"facebookPostMediaViewsCount":{"type":"string"},"facebookPostMediaViewsUniqueCount":{"type":"string"},"facebookPostReactionsByType":{"type":"object","additionalProperties":{"type":"string"}},"facebookBlueReelsPlaysCount":{"type":"string"},"facebookFbReelsReplaysCount":{"type":"string"},"facebookFbReelsTotalPlaysCount":{"type":"string"},"facebookPostVideoWatchTimeMsAvg":{"type":"string"},"facebookPostVideoFollowersCount":{"type":"string"},"facebookPostVideoLikesByReactionType":{"type":"object","additionalProperties":{"type":"string"}},"facebookPostVideoSocialActionsByType":{"type":"object","additionalProperties":{"type":"string"}},"facebookPostVideoViewTimeMsSum":{"type":"string"},"facebookTotalVideoViewsCount":{"type":"string"},"facebookTotalVideoViewsUniqueCount":{"type":"string"},"facebookTotalVideoViewsAutoplayedCount":{"type":"string"},"facebookTotalVideoViewsClickedToPlayCount":{"type":"string"},"facebookTotalVideoViewsSoundOnCount":{"type":"string"},"facebookTotalVideoCompleteViewsCount":{"type":"string"},"facebookTotalVideoCompleteViewsUniqueCount":{"type":"string"},"facebookTotalVideoCompleteViewsAutoplayedCount":{"type":"string"},"facebookTotalVideoCompleteViewsClickedToPlayCount":{"type":"string"},"facebookTotalVideoCompleteViewsOrganicCount":{"type":"string"},"facebookTotalVideoCompleteViewsOrganicUniqueCount":{"type":"string"},"facebookTotalVideoCompleteViewsPaidCount":{"type":"string"},"facebookTotalVideoCompleteViewsPaidUniqueCount":{"type":"string"},"facebookTotalVideoViews10sCount":{"type":"string"},"facebookTotalVideoViews10sUniqueCount":{"type":"string"},"facebookTotalVideoViews10sAutoplayedCount":{"type":"string"},"facebookTotalVideoViews10sClickedToPlayCount":{"type":"string"},"facebookTotalVideoViews10sOrganicCount":{"type":"string"},"facebookTotalVideoViews10sPaidCount":{"type":"string"},"facebookTotalVideoViews10sSoundOnCount":{"type":"string"},"facebookTotalVideoViews15sCount":{"type":"string"},"facebookTotalVideoViews60sExcludesShorterCount":{"type":"string"},"facebookTotalVideoWatchTimeMsAvg":{"type":"string"},"facebookTotalVideoViewTimeMsSum":{"type":"string"},"facebookTotalVideoViewTimeOrganicMsSum":{"type":"string"},"facebookTotalVideoViewTimePaidMsSum":{"type":"string"},"facebookTotalVideoStoriesByActionType":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoReactionsByType":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoViewTimeMsByAgeBucketAndGender":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoViewTimeMsByRegionId":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoViewsByDistributionType":{"type":"object","additionalProperties":{"type":"string"}},"youtubeDislikesCount":{"type":"string"},"youtubeSubscribersLostCount":{"type":"string"},"youtubeVideosAddedToPlaylistsCount":{"type":"string"},"youtubeVideosRemovedFromPlaylistsCount":{"type":"string"},"youtubeRedViewsCount":{"type":"string"},"youtubeRedViewTimeMsSum":{"type":"string"},"youtubeEngagedViewsCount":{"type":"string"},"youtubeAverageViewPercentage":{"type":"number"},"youtubeCardClicksCount":{"type":"string"},"youtubeCardImpressionsCount":{"type":"string"},"youtubeCardClickRate":{"type":"number"},"youtubeCardTeaserClicksCount":{"type":"string"},"youtubeCardTeaserImpressionsCount":{"type":"string"},"youtubeCardTeaserClickRate":{"type":"number"},"youtubeAnnotationClicksCount":{"type":"string"},"youtubeAnnotationClickableImpressionsCount":{"type":"string"},"youtubeAnnotationClosesCount":{"type":"string"},"youtubeAnnotationClosableImpressionsCount":{"type":"string"},"youtubeAnnotationImpressionsCount":{"type":"string"},"youtubeAnnotationClickThroughRate":{"type":"number"},"youtubeAnnotationCloseRate":{"type":"number"}}}},"required":["fetchedAt","metrics"]}}},"required":["publishedPostId","platform","lastFetchedAt","lastError","metrics","history"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/analytics":{"get":{"summary":"List top performing posts","tags":["analytics"],"description":"Returns the user's top performing published posts ordered by the requested metric over the given time range.","parameters":[{"schema":{"type":"string"},"in":"query","name":"since","required":false,"description":"Only include posts published on or after this ISO 8601 timestamp. Defaults to 30 days ago."},{"schema":{"type":"string"},"in":"query","name":"until","required":false,"description":"Only include posts published on or before this ISO 8601 timestamp. Defaults to now."},{"schema":{"type":"string"},"in":"query","name":"platform","required":false},{"schema":{"type":"string","enum":["likes_count","comments_count","views_count","reach_count"]},"in":"query","name":"sortBy","required":false},{"schema":{"minimum":1,"maximum":100,"default":20,"type":"integer"},"in":"query","name":"limit","required":false}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"content":{"type":"string"},"postUrl":{"type":"string","nullable":true},"platform":{"description":"Social media platform","example":"twitter","type":"string","enum":["twitter","instagram","linkedin","facebook","tiktok","pinterest","threads","bluesky","youtube","other"]},"createdAt":{"type":"string"},"mediaUrls":{"type":"array","items":{"type":"string"}},"latestMetrics":{"type":"object","properties":{"fetchedAt":{"description":"ISO 8601 timestamp when metrics were captured.","type":"string"},"metrics":{"type":"object","properties":{"clicksCount":{"type":"string"},"commentsCount":{"type":"string"},"followsCount":{"type":"string"},"impressionsCount":{"type":"string"},"interactionsSum":{"type":"string"},"likesCount":{"type":"string"},"navigationsCount":{"type":"string"},"playsCount":{"type":"string"},"profileActivityCount":{"type":"string"},"profileVisitsCount":{"type":"string"},"reachCount":{"type":"string"},"repliesCount":{"type":"string"},"savesCount":{"type":"string"},"sharesCount":{"type":"string"},"viewTimeMsSum":{"type":"string"},"viewsCount":{"type":"string"},"watchTimeMsAvg":{"type":"string"},"twitterRetweetsCount":{"type":"string"},"twitterQuotesCount":{"type":"string"},"blueskyRepostsCount":{"type":"string"},"blueskyQuotesCount":{"type":"string"},"threadsRepostsCount":{"type":"string"},"threadsQuotesCount":{"type":"string"},"linkedinFirstLevelCommentsCount":{"type":"string"},"linkedinReactionsByType":{"type":"object","additionalProperties":{"type":"string"}},"pinterestPinClicksCount":{"type":"string"},"pinterestReactionsCount":{"type":"string"},"pinterestVideoP95ViewsCount":{"type":"string"},"pinterestVideo10sViewsCount":{"type":"string"},"pinterestVideoMrcViewsCount":{"type":"string"},"pinterestVideoV50WatchTimeMsSum":{"type":"string"},"pinterestSaveRate":{"type":"number"},"twitterPerMediaVideoViewsCount":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlaybackStartCount":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlayback25Count":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlayback50Count":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlayback75Count":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlaybackCompleteCount":{"type":"array","items":{"type":"string","nullable":true}},"facebookPostMediaViewsCount":{"type":"string"},"facebookPostMediaViewsUniqueCount":{"type":"string"},"facebookPostReactionsByType":{"type":"object","additionalProperties":{"type":"string"}},"facebookBlueReelsPlaysCount":{"type":"string"},"facebookFbReelsReplaysCount":{"type":"string"},"facebookFbReelsTotalPlaysCount":{"type":"string"},"facebookPostVideoWatchTimeMsAvg":{"type":"string"},"facebookPostVideoFollowersCount":{"type":"string"},"facebookPostVideoLikesByReactionType":{"type":"object","additionalProperties":{"type":"string"}},"facebookPostVideoSocialActionsByType":{"type":"object","additionalProperties":{"type":"string"}},"facebookPostVideoViewTimeMsSum":{"type":"string"},"facebookTotalVideoViewsCount":{"type":"string"},"facebookTotalVideoViewsUniqueCount":{"type":"string"},"facebookTotalVideoViewsAutoplayedCount":{"type":"string"},"facebookTotalVideoViewsClickedToPlayCount":{"type":"string"},"facebookTotalVideoViewsSoundOnCount":{"type":"string"},"facebookTotalVideoCompleteViewsCount":{"type":"string"},"facebookTotalVideoCompleteViewsUniqueCount":{"type":"string"},"facebookTotalVideoCompleteViewsAutoplayedCount":{"type":"string"},"facebookTotalVideoCompleteViewsClickedToPlayCount":{"type":"string"},"facebookTotalVideoCompleteViewsOrganicCount":{"type":"string"},"facebookTotalVideoCompleteViewsOrganicUniqueCount":{"type":"string"},"facebookTotalVideoCompleteViewsPaidCount":{"type":"string"},"facebookTotalVideoCompleteViewsPaidUniqueCount":{"type":"string"},"facebookTotalVideoViews10sCount":{"type":"string"},"facebookTotalVideoViews10sUniqueCount":{"type":"string"},"facebookTotalVideoViews10sAutoplayedCount":{"type":"string"},"facebookTotalVideoViews10sClickedToPlayCount":{"type":"string"},"facebookTotalVideoViews10sOrganicCount":{"type":"string"},"facebookTotalVideoViews10sPaidCount":{"type":"string"},"facebookTotalVideoViews10sSoundOnCount":{"type":"string"},"facebookTotalVideoViews15sCount":{"type":"string"},"facebookTotalVideoViews60sExcludesShorterCount":{"type":"string"},"facebookTotalVideoWatchTimeMsAvg":{"type":"string"},"facebookTotalVideoViewTimeMsSum":{"type":"string"},"facebookTotalVideoViewTimeOrganicMsSum":{"type":"string"},"facebookTotalVideoViewTimePaidMsSum":{"type":"string"},"facebookTotalVideoStoriesByActionType":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoReactionsByType":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoViewTimeMsByAgeBucketAndGender":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoViewTimeMsByRegionId":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoViewsByDistributionType":{"type":"object","additionalProperties":{"type":"string"}},"youtubeDislikesCount":{"type":"string"},"youtubeSubscribersLostCount":{"type":"string"},"youtubeVideosAddedToPlaylistsCount":{"type":"string"},"youtubeVideosRemovedFromPlaylistsCount":{"type":"string"},"youtubeRedViewsCount":{"type":"string"},"youtubeRedViewTimeMsSum":{"type":"string"},"youtubeEngagedViewsCount":{"type":"string"},"youtubeAverageViewPercentage":{"type":"number"},"youtubeCardClicksCount":{"type":"string"},"youtubeCardImpressionsCount":{"type":"string"},"youtubeCardClickRate":{"type":"number"},"youtubeCardTeaserClicksCount":{"type":"string"},"youtubeCardTeaserImpressionsCount":{"type":"string"},"youtubeCardTeaserClickRate":{"type":"number"},"youtubeAnnotationClicksCount":{"type":"string"},"youtubeAnnotationClickableImpressionsCount":{"type":"string"},"youtubeAnnotationClosesCount":{"type":"string"},"youtubeAnnotationClosableImpressionsCount":{"type":"string"},"youtubeAnnotationImpressionsCount":{"type":"string"},"youtubeAnnotationClickThroughRate":{"type":"number"},"youtubeAnnotationCloseRate":{"type":"number"}}}},"required":["fetchedAt","metrics"]},"metricsHistory":{"type":"array","items":{"type":"object","properties":{"fetchedAt":{"description":"ISO 8601 timestamp when metrics were captured.","type":"string"},"metrics":{"type":"object","properties":{"clicksCount":{"type":"string"},"commentsCount":{"type":"string"},"followsCount":{"type":"string"},"impressionsCount":{"type":"string"},"interactionsSum":{"type":"string"},"likesCount":{"type":"string"},"navigationsCount":{"type":"string"},"playsCount":{"type":"string"},"profileActivityCount":{"type":"string"},"profileVisitsCount":{"type":"string"},"reachCount":{"type":"string"},"repliesCount":{"type":"string"},"savesCount":{"type":"string"},"sharesCount":{"type":"string"},"viewTimeMsSum":{"type":"string"},"viewsCount":{"type":"string"},"watchTimeMsAvg":{"type":"string"},"twitterRetweetsCount":{"type":"string"},"twitterQuotesCount":{"type":"string"},"blueskyRepostsCount":{"type":"string"},"blueskyQuotesCount":{"type":"string"},"threadsRepostsCount":{"type":"string"},"threadsQuotesCount":{"type":"string"},"linkedinFirstLevelCommentsCount":{"type":"string"},"linkedinReactionsByType":{"type":"object","additionalProperties":{"type":"string"}},"pinterestPinClicksCount":{"type":"string"},"pinterestReactionsCount":{"type":"string"},"pinterestVideoP95ViewsCount":{"type":"string"},"pinterestVideo10sViewsCount":{"type":"string"},"pinterestVideoMrcViewsCount":{"type":"string"},"pinterestVideoV50WatchTimeMsSum":{"type":"string"},"pinterestSaveRate":{"type":"number"},"twitterPerMediaVideoViewsCount":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlaybackStartCount":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlayback25Count":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlayback50Count":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlayback75Count":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlaybackCompleteCount":{"type":"array","items":{"type":"string","nullable":true}},"facebookPostMediaViewsCount":{"type":"string"},"facebookPostMediaViewsUniqueCount":{"type":"string"},"facebookPostReactionsByType":{"type":"object","additionalProperties":{"type":"string"}},"facebookBlueReelsPlaysCount":{"type":"string"},"facebookFbReelsReplaysCount":{"type":"string"},"facebookFbReelsTotalPlaysCount":{"type":"string"},"facebookPostVideoWatchTimeMsAvg":{"type":"string"},"facebookPostVideoFollowersCount":{"type":"string"},"facebookPostVideoLikesByReactionType":{"type":"object","additionalProperties":{"type":"string"}},"facebookPostVideoSocialActionsByType":{"type":"object","additionalProperties":{"type":"string"}},"facebookPostVideoViewTimeMsSum":{"type":"string"},"facebookTotalVideoViewsCount":{"type":"string"},"facebookTotalVideoViewsUniqueCount":{"type":"string"},"facebookTotalVideoViewsAutoplayedCount":{"type":"string"},"facebookTotalVideoViewsClickedToPlayCount":{"type":"string"},"facebookTotalVideoViewsSoundOnCount":{"type":"string"},"facebookTotalVideoCompleteViewsCount":{"type":"string"},"facebookTotalVideoCompleteViewsUniqueCount":{"type":"string"},"facebookTotalVideoCompleteViewsAutoplayedCount":{"type":"string"},"facebookTotalVideoCompleteViewsClickedToPlayCount":{"type":"string"},"facebookTotalVideoCompleteViewsOrganicCount":{"type":"string"},"facebookTotalVideoCompleteViewsOrganicUniqueCount":{"type":"string"},"facebookTotalVideoCompleteViewsPaidCount":{"type":"string"},"facebookTotalVideoCompleteViewsPaidUniqueCount":{"type":"string"},"facebookTotalVideoViews10sCount":{"type":"string"},"facebookTotalVideoViews10sUniqueCount":{"type":"string"},"facebookTotalVideoViews10sAutoplayedCount":{"type":"string"},"facebookTotalVideoViews10sClickedToPlayCount":{"type":"string"},"facebookTotalVideoViews10sOrganicCount":{"type":"string"},"facebookTotalVideoViews10sPaidCount":{"type":"string"},"facebookTotalVideoViews10sSoundOnCount":{"type":"string"},"facebookTotalVideoViews15sCount":{"type":"string"},"facebookTotalVideoViews60sExcludesShorterCount":{"type":"string"},"facebookTotalVideoWatchTimeMsAvg":{"type":"string"},"facebookTotalVideoViewTimeMsSum":{"type":"string"},"facebookTotalVideoViewTimeOrganicMsSum":{"type":"string"},"facebookTotalVideoViewTimePaidMsSum":{"type":"string"},"facebookTotalVideoStoriesByActionType":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoReactionsByType":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoViewTimeMsByAgeBucketAndGender":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoViewTimeMsByRegionId":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoViewsByDistributionType":{"type":"object","additionalProperties":{"type":"string"}},"youtubeDislikesCount":{"type":"string"},"youtubeSubscribersLostCount":{"type":"string"},"youtubeVideosAddedToPlaylistsCount":{"type":"string"},"youtubeVideosRemovedFromPlaylistsCount":{"type":"string"},"youtubeRedViewsCount":{"type":"string"},"youtubeRedViewTimeMsSum":{"type":"string"},"youtubeEngagedViewsCount":{"type":"string"},"youtubeAverageViewPercentage":{"type":"number"},"youtubeCardClicksCount":{"type":"string"},"youtubeCardImpressionsCount":{"type":"string"},"youtubeCardClickRate":{"type":"number"},"youtubeCardTeaserClicksCount":{"type":"string"},"youtubeCardTeaserImpressionsCount":{"type":"string"},"youtubeCardTeaserClickRate":{"type":"number"},"youtubeAnnotationClicksCount":{"type":"string"},"youtubeAnnotationClickableImpressionsCount":{"type":"string"},"youtubeAnnotationClosesCount":{"type":"string"},"youtubeAnnotationClosableImpressionsCount":{"type":"string"},"youtubeAnnotationImpressionsCount":{"type":"string"},"youtubeAnnotationClickThroughRate":{"type":"number"},"youtubeAnnotationCloseRate":{"type":"number"}}}},"required":["fetchedAt","metrics"]}}},"required":["id","content","postUrl","platform","createdAt","mediaUrls","metricsHistory"]}}},"required":["items"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Validation error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Validation error","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/published-posts":{"get":{"summary":"Search published posts","tags":["publishing"],"description":"Paginated search over a user's published posts, optionally filtered by platform and full-text query, with the latest analytics snapshot attached when available.","parameters":[{"schema":{"type":"string"},"in":"query","name":"query","required":false},{"schema":{"type":"string"},"in":"query","name":"platform","required":false},{"schema":{"type":"string"},"in":"query","name":"accountId","required":false},{"schema":{"type":"string","enum":["newest","oldest"]},"in":"query","name":"sortBy","required":false},{"schema":{"minimum":0,"default":0,"type":"integer"},"in":"query","name":"offset","required":false},{"schema":{"minimum":1,"maximum":100,"default":20,"type":"integer"},"in":"query","name":"limit","required":false}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"content":{"type":"string"},"postUrl":{"type":"string","nullable":true},"platform":{"description":"Social media platform","example":"twitter","type":"string","enum":["twitter","instagram","linkedin","facebook","tiktok","pinterest","threads","bluesky","youtube","other"]},"createdAt":{"type":"string"},"mediaUrls":{"type":"array","items":{"type":"string"}},"latestMetrics":{"type":"object","properties":{"fetchedAt":{"description":"ISO 8601 timestamp when metrics were captured.","type":"string"},"metrics":{"type":"object","properties":{"clicksCount":{"type":"string"},"commentsCount":{"type":"string"},"followsCount":{"type":"string"},"impressionsCount":{"type":"string"},"interactionsSum":{"type":"string"},"likesCount":{"type":"string"},"navigationsCount":{"type":"string"},"playsCount":{"type":"string"},"profileActivityCount":{"type":"string"},"profileVisitsCount":{"type":"string"},"reachCount":{"type":"string"},"repliesCount":{"type":"string"},"savesCount":{"type":"string"},"sharesCount":{"type":"string"},"viewTimeMsSum":{"type":"string"},"viewsCount":{"type":"string"},"watchTimeMsAvg":{"type":"string"},"twitterRetweetsCount":{"type":"string"},"twitterQuotesCount":{"type":"string"},"blueskyRepostsCount":{"type":"string"},"blueskyQuotesCount":{"type":"string"},"threadsRepostsCount":{"type":"string"},"threadsQuotesCount":{"type":"string"},"linkedinFirstLevelCommentsCount":{"type":"string"},"linkedinReactionsByType":{"type":"object","additionalProperties":{"type":"string"}},"pinterestPinClicksCount":{"type":"string"},"pinterestReactionsCount":{"type":"string"},"pinterestVideoP95ViewsCount":{"type":"string"},"pinterestVideo10sViewsCount":{"type":"string"},"pinterestVideoMrcViewsCount":{"type":"string"},"pinterestVideoV50WatchTimeMsSum":{"type":"string"},"pinterestSaveRate":{"type":"number"},"twitterPerMediaVideoViewsCount":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlaybackStartCount":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlayback25Count":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlayback50Count":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlayback75Count":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlaybackCompleteCount":{"type":"array","items":{"type":"string","nullable":true}},"facebookPostMediaViewsCount":{"type":"string"},"facebookPostMediaViewsUniqueCount":{"type":"string"},"facebookPostReactionsByType":{"type":"object","additionalProperties":{"type":"string"}},"facebookBlueReelsPlaysCount":{"type":"string"},"facebookFbReelsReplaysCount":{"type":"string"},"facebookFbReelsTotalPlaysCount":{"type":"string"},"facebookPostVideoWatchTimeMsAvg":{"type":"string"},"facebookPostVideoFollowersCount":{"type":"string"},"facebookPostVideoLikesByReactionType":{"type":"object","additionalProperties":{"type":"string"}},"facebookPostVideoSocialActionsByType":{"type":"object","additionalProperties":{"type":"string"}},"facebookPostVideoViewTimeMsSum":{"type":"string"},"facebookTotalVideoViewsCount":{"type":"string"},"facebookTotalVideoViewsUniqueCount":{"type":"string"},"facebookTotalVideoViewsAutoplayedCount":{"type":"string"},"facebookTotalVideoViewsClickedToPlayCount":{"type":"string"},"facebookTotalVideoViewsSoundOnCount":{"type":"string"},"facebookTotalVideoCompleteViewsCount":{"type":"string"},"facebookTotalVideoCompleteViewsUniqueCount":{"type":"string"},"facebookTotalVideoCompleteViewsAutoplayedCount":{"type":"string"},"facebookTotalVideoCompleteViewsClickedToPlayCount":{"type":"string"},"facebookTotalVideoCompleteViewsOrganicCount":{"type":"string"},"facebookTotalVideoCompleteViewsOrganicUniqueCount":{"type":"string"},"facebookTotalVideoCompleteViewsPaidCount":{"type":"string"},"facebookTotalVideoCompleteViewsPaidUniqueCount":{"type":"string"},"facebookTotalVideoViews10sCount":{"type":"string"},"facebookTotalVideoViews10sUniqueCount":{"type":"string"},"facebookTotalVideoViews10sAutoplayedCount":{"type":"string"},"facebookTotalVideoViews10sClickedToPlayCount":{"type":"string"},"facebookTotalVideoViews10sOrganicCount":{"type":"string"},"facebookTotalVideoViews10sPaidCount":{"type":"string"},"facebookTotalVideoViews10sSoundOnCount":{"type":"string"},"facebookTotalVideoViews15sCount":{"type":"string"},"facebookTotalVideoViews60sExcludesShorterCount":{"type":"string"},"facebookTotalVideoWatchTimeMsAvg":{"type":"string"},"facebookTotalVideoViewTimeMsSum":{"type":"string"},"facebookTotalVideoViewTimeOrganicMsSum":{"type":"string"},"facebookTotalVideoViewTimePaidMsSum":{"type":"string"},"facebookTotalVideoStoriesByActionType":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoReactionsByType":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoViewTimeMsByAgeBucketAndGender":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoViewTimeMsByRegionId":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoViewsByDistributionType":{"type":"object","additionalProperties":{"type":"string"}},"youtubeDislikesCount":{"type":"string"},"youtubeSubscribersLostCount":{"type":"string"},"youtubeVideosAddedToPlaylistsCount":{"type":"string"},"youtubeVideosRemovedFromPlaylistsCount":{"type":"string"},"youtubeRedViewsCount":{"type":"string"},"youtubeRedViewTimeMsSum":{"type":"string"},"youtubeEngagedViewsCount":{"type":"string"},"youtubeAverageViewPercentage":{"type":"number"},"youtubeCardClicksCount":{"type":"string"},"youtubeCardImpressionsCount":{"type":"string"},"youtubeCardClickRate":{"type":"number"},"youtubeCardTeaserClicksCount":{"type":"string"},"youtubeCardTeaserImpressionsCount":{"type":"string"},"youtubeCardTeaserClickRate":{"type":"number"},"youtubeAnnotationClicksCount":{"type":"string"},"youtubeAnnotationClickableImpressionsCount":{"type":"string"},"youtubeAnnotationClosesCount":{"type":"string"},"youtubeAnnotationClosableImpressionsCount":{"type":"string"},"youtubeAnnotationImpressionsCount":{"type":"string"},"youtubeAnnotationClickThroughRate":{"type":"number"},"youtubeAnnotationCloseRate":{"type":"number"}}}},"required":["fetchedAt","metrics"]},"metricsHistory":{"type":"array","items":{"type":"object","properties":{"fetchedAt":{"description":"ISO 8601 timestamp when metrics were captured.","type":"string"},"metrics":{"type":"object","properties":{"clicksCount":{"type":"string"},"commentsCount":{"type":"string"},"followsCount":{"type":"string"},"impressionsCount":{"type":"string"},"interactionsSum":{"type":"string"},"likesCount":{"type":"string"},"navigationsCount":{"type":"string"},"playsCount":{"type":"string"},"profileActivityCount":{"type":"string"},"profileVisitsCount":{"type":"string"},"reachCount":{"type":"string"},"repliesCount":{"type":"string"},"savesCount":{"type":"string"},"sharesCount":{"type":"string"},"viewTimeMsSum":{"type":"string"},"viewsCount":{"type":"string"},"watchTimeMsAvg":{"type":"string"},"twitterRetweetsCount":{"type":"string"},"twitterQuotesCount":{"type":"string"},"blueskyRepostsCount":{"type":"string"},"blueskyQuotesCount":{"type":"string"},"threadsRepostsCount":{"type":"string"},"threadsQuotesCount":{"type":"string"},"linkedinFirstLevelCommentsCount":{"type":"string"},"linkedinReactionsByType":{"type":"object","additionalProperties":{"type":"string"}},"pinterestPinClicksCount":{"type":"string"},"pinterestReactionsCount":{"type":"string"},"pinterestVideoP95ViewsCount":{"type":"string"},"pinterestVideo10sViewsCount":{"type":"string"},"pinterestVideoMrcViewsCount":{"type":"string"},"pinterestVideoV50WatchTimeMsSum":{"type":"string"},"pinterestSaveRate":{"type":"number"},"twitterPerMediaVideoViewsCount":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlaybackStartCount":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlayback25Count":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlayback50Count":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlayback75Count":{"type":"array","items":{"type":"string","nullable":true}},"twitterPerMediaVideoPlaybackCompleteCount":{"type":"array","items":{"type":"string","nullable":true}},"facebookPostMediaViewsCount":{"type":"string"},"facebookPostMediaViewsUniqueCount":{"type":"string"},"facebookPostReactionsByType":{"type":"object","additionalProperties":{"type":"string"}},"facebookBlueReelsPlaysCount":{"type":"string"},"facebookFbReelsReplaysCount":{"type":"string"},"facebookFbReelsTotalPlaysCount":{"type":"string"},"facebookPostVideoWatchTimeMsAvg":{"type":"string"},"facebookPostVideoFollowersCount":{"type":"string"},"facebookPostVideoLikesByReactionType":{"type":"object","additionalProperties":{"type":"string"}},"facebookPostVideoSocialActionsByType":{"type":"object","additionalProperties":{"type":"string"}},"facebookPostVideoViewTimeMsSum":{"type":"string"},"facebookTotalVideoViewsCount":{"type":"string"},"facebookTotalVideoViewsUniqueCount":{"type":"string"},"facebookTotalVideoViewsAutoplayedCount":{"type":"string"},"facebookTotalVideoViewsClickedToPlayCount":{"type":"string"},"facebookTotalVideoViewsSoundOnCount":{"type":"string"},"facebookTotalVideoCompleteViewsCount":{"type":"string"},"facebookTotalVideoCompleteViewsUniqueCount":{"type":"string"},"facebookTotalVideoCompleteViewsAutoplayedCount":{"type":"string"},"facebookTotalVideoCompleteViewsClickedToPlayCount":{"type":"string"},"facebookTotalVideoCompleteViewsOrganicCount":{"type":"string"},"facebookTotalVideoCompleteViewsOrganicUniqueCount":{"type":"string"},"facebookTotalVideoCompleteViewsPaidCount":{"type":"string"},"facebookTotalVideoCompleteViewsPaidUniqueCount":{"type":"string"},"facebookTotalVideoViews10sCount":{"type":"string"},"facebookTotalVideoViews10sUniqueCount":{"type":"string"},"facebookTotalVideoViews10sAutoplayedCount":{"type":"string"},"facebookTotalVideoViews10sClickedToPlayCount":{"type":"string"},"facebookTotalVideoViews10sOrganicCount":{"type":"string"},"facebookTotalVideoViews10sPaidCount":{"type":"string"},"facebookTotalVideoViews10sSoundOnCount":{"type":"string"},"facebookTotalVideoViews15sCount":{"type":"string"},"facebookTotalVideoViews60sExcludesShorterCount":{"type":"string"},"facebookTotalVideoWatchTimeMsAvg":{"type":"string"},"facebookTotalVideoViewTimeMsSum":{"type":"string"},"facebookTotalVideoViewTimeOrganicMsSum":{"type":"string"},"facebookTotalVideoViewTimePaidMsSum":{"type":"string"},"facebookTotalVideoStoriesByActionType":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoReactionsByType":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoViewTimeMsByAgeBucketAndGender":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoViewTimeMsByRegionId":{"type":"object","additionalProperties":{"type":"string"}},"facebookTotalVideoViewsByDistributionType":{"type":"object","additionalProperties":{"type":"string"}},"youtubeDislikesCount":{"type":"string"},"youtubeSubscribersLostCount":{"type":"string"},"youtubeVideosAddedToPlaylistsCount":{"type":"string"},"youtubeVideosRemovedFromPlaylistsCount":{"type":"string"},"youtubeRedViewsCount":{"type":"string"},"youtubeRedViewTimeMsSum":{"type":"string"},"youtubeEngagedViewsCount":{"type":"string"},"youtubeAverageViewPercentage":{"type":"number"},"youtubeCardClicksCount":{"type":"string"},"youtubeCardImpressionsCount":{"type":"string"},"youtubeCardClickRate":{"type":"number"},"youtubeCardTeaserClicksCount":{"type":"string"},"youtubeCardTeaserImpressionsCount":{"type":"string"},"youtubeCardTeaserClickRate":{"type":"number"},"youtubeAnnotationClicksCount":{"type":"string"},"youtubeAnnotationClickableImpressionsCount":{"type":"string"},"youtubeAnnotationClosesCount":{"type":"string"},"youtubeAnnotationClosableImpressionsCount":{"type":"string"},"youtubeAnnotationImpressionsCount":{"type":"string"},"youtubeAnnotationClickThroughRate":{"type":"number"},"youtubeAnnotationCloseRate":{"type":"number"}}}},"required":["fetchedAt","metrics"]}}},"required":["id","content","postUrl","platform","createdAt","mediaUrls","metricsHistory"]}},"count":{"type":"integer"}},"required":["items","count"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Validation error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Validation error","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/schedules":{"get":{"summary":"List scheduled posts","tags":["publishing"],"description":"Fetches the current user's scheduled posts, ordered by scheduled time (ascending). Supports cursor-based pagination. Only returns posts scheduled in the future.","parameters":[{"schema":{"type":"integer"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"account":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"username":{"type":"string"},"profileImageUrl":{"type":"string","nullable":true},"subaccountId":{"type":"string","nullable":true},"subId":{"type":"string","nullable":true},"subaccountName":{"type":"string","nullable":true}},"required":["id","name","username","profileImageUrl","subaccountId","subId","subaccountName"],"nullable":true},"draft":{"type":"object","properties":{"accountId":{"description":"The ID of the social media account to publish the content to.","example":"1","type":"string"},"content":{"type":"object","allOf":[{"type":"object","properties":{"text":{"description":"The text content of the post.","example":"My text","type":"string"},"mediaUrls":{"description":"List of media URLs to include in the post.","maxItems":20,"type":"array","items":{"description":"URLs of media files (images, videos) to include in the post. Must originate from the blotato domain. Use the media upload endpoint to upload media files before publishing.","example":"https://database.blotato.io/some-image-path.jpg","type":"string"}}},"required":["text","mediaUrls"]},{"type":"object","properties":{"platform":{"description":"Social media platform","example":"twitter","type":"string","enum":["twitter","instagram","linkedin","facebook","tiktok","pinterest","threads","bluesky","youtube","other"]},"additionalPosts":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"text":{"description":"The text content of the post.","example":"My text","type":"string"},"mediaUrls":{"description":"List of media URLs to include in the post.","maxItems":20,"type":"array","items":{"description":"URLs of media files (images, videos) to include in the post. Must originate from the blotato domain. Use the media upload endpoint to upload media files before publishing.","example":"https://database.blotato.io/some-image-path.jpg","type":"string"}}},"required":["text","mediaUrls"]}}},"required":["platform"]}]},"target":{"type":"object","discriminator":{"propertyName":"targetType"},"oneOf":[{"type":"object","properties":{"targetType":{"description":"Publish to a custom webhook.","example":"webhook","type":"string","enum":["webhook"]},"url":{"minLength":1,"description":"The URL of the webhook to publish to.","example":"https://example.com/webhook","type":"string"}},"required":["targetType","url"]},{"type":"object","properties":{"targetType":{"description":"Publish to Twitter.","example":"twitter","type":"string","enum":["twitter"]}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to LinkedIn.","example":"linkedin","type":"string","enum":["linkedin"]},"pageId":{"minLength":1,"description":"The ID of the LinkedIn page to publish to.","example":"123456789","type":"string"}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to Facebook.","example":"facebook","type":"string","enum":["facebook"]},"pageId":{"pattern":"^\\d+$","description":"The ID of the Facebook page to publish to.","example":"123456789","type":"string"},"mediaType":{"description":"Whether the media is a reel or video.","example":"reel","type":"string","enum":["reel","story"]},"link":{"minLength":1,"description":"Link preview to attach to the Facebook post.","example":"https://blotato.com","type":"string"},"firstComment":{"minLength":1,"maxLength":8000,"description":"Auto-posted comment on posts and reels, immediately after publish. Not supported for stories.","example":"First comment!","type":"string"}},"required":["targetType","pageId"]},{"type":"object","properties":{"targetType":{"description":"Publish to Instagram.","example":"instagram","type":"string","enum":["instagram"]},"mediaType":{"description":"Whether the media is a reel or story.","example":"reel","type":"string","enum":["reel","story"]},"altText":{"minLength":1,"maxLength":1000,"description":"Alternative text, for accessibility purposes. Only supported on a single image or image media in a carousel.","example":"Describe the image here for accessibility","type":"string"},"shareToFeed":{"description":"Whether to also share the reel to the Instagram feed. Only applicable for reels.","example":false,"type":"boolean"},"audioName":{"minLength":1,"maxLength":2200,"description":"For Reels only. Name of the audio of your Reels media. You can only rename once, either while creating a reel or after from the audio page.","example":"My Custom Audio Name","type":"string"},"collaborators":{"description":"List of collaborators to add to the Instagram post.","minItems":1,"maxItems":3,"type":"array","items":{"minLength":1,"description":"The Instagram usernames of the collaborator to add to the post.","example":"instagram_username","type":"string"}},"coverImageUrl":{"minLength":1,"description":"URL of the cover image to use for the Instagram post. Use the media upload endpoint to upload media files before publishing. Maximum file size is 8MB. Only applicable to reels.","example":"https://database.blotato.io/some-image-path.jpg","type":"string"},"trial":{"description":"Settings for trial reels. Trial reels are shown only to non-followers.","type":"object","properties":{"graduationStrategy":{"description":"Strategy to use to determine when to graduate post from trial (convert the trial reel to a reel, sharing it to followers).","example":"SS_PERFORMANCE","type":"string","enum":["MANUAL","SS_PERFORMANCE"]}},"required":["graduationStrategy"]},"firstComment":{"minLength":1,"maxLength":2200,"description":"Auto-posted comment with feed posts and carousels, immediately after publish. Not supported for stories. Useful for links.","example":"Link in the first comment!","type":"string"}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to TikTok.","example":"tiktok","type":"string","enum":["tiktok"]},"privacyLevel":{"description":"The privacy level of the TikTok post.","example":"SELF_ONLY","type":"string","enum":["SELF_ONLY","PUBLIC_TO_EVERYONE","MUTUAL_FOLLOW_FRIENDS","FOLLOWER_OF_CREATOR"]},"disabledComments":{"description":"Whether to disable comments on the TikTok post.","example":false,"type":"boolean"},"disabledDuet":{"description":"Whether to disable duet on the TikTok post.","example":false,"type":"boolean"},"disabledStitch":{"description":"Whether to disable stitch on the TikTok post.","example":false,"type":"boolean"},"isBrandedContent":{"description":"Whether the TikTok post is branded content.","example":false,"type":"boolean"},"isYourBrand":{"description":"Whether the TikTok post is for your brand.","example":false,"type":"boolean"},"isAiGenerated":{"description":"Whether the TikTok post is AI-generated.","example":false,"type":"boolean"},"title":{"minLength":1,"maxLength":90,"description":"Title for the image posts. If notprovided, the first 90 characters of the post.content.text will be used.","example":"My TikTok Image Post Title","type":"string"},"autoAddMusic":{"description":"Whether to automatically add music to the TikTok image posts.","example":false,"type":"boolean"},"isDraft":{"description":"Don't publish the post immediately, save it as a draft instead. Default is false.","example":true,"type":"boolean"},"imageCoverIndex":{"minimum":0,"description":"Index of the image (starts from 0) to use as the cover for carousel posts. Only applicable for carousel image posts.","example":0,"type":"number"},"videoCoverTimestamp":{"minimum":0,"description":"Location in milliseconds of the video to use as the cover image. Only applicable for video posts. If not provided, the frame as 0 milliseconds will be used.","example":0,"type":"number"}},"required":["targetType","privacyLevel","disabledComments","disabledDuet","disabledStitch","isBrandedContent","isYourBrand","isAiGenerated"]},{"type":"object","properties":{"targetType":{"description":"Publish to Pinterest.","example":"pinterest","type":"string","enum":["pinterest"]},"boardId":{"minLength":1,"description":"The ID of the Pinterest board to publish to.","example":"123456789","type":"string"},"title":{"minLength":1,"maxLength":100,"description":"Title for the Pinterest post.","example":"My Pinterest Post Title","type":"string"},"link":{"maxLength":2048,"description":"Link for the Pinterest post.","example":"https://example.com/my-pinterest-post-link","type":"string"},"altText":{"maxLength":500,"description":"Alternative text for the Pinterest post, for accessibility purposes.","example":"Describe the image here for accessibility","type":"string"}},"required":["targetType","boardId"]},{"type":"object","properties":{"targetType":{"description":"Publish to Threads.","example":"threads","type":"string","enum":["threads"]},"replyControl":{"description":"Who can reply to the Threads post.","example":"everyone","type":"string","enum":["everyone","accounts_you_follow","mentioned_only"]}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to Bluesky.","example":"bluesky","type":"string","enum":["bluesky"]}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to YouTube.","example":"youtube","type":"string","enum":["youtube"]},"title":{"minLength":1,"maxLength":100,"pattern":"^[^<>]*$","description":"Title for the YouTube post. Must not contain any of the following characters: <>","errorMessage":{"pattern":"must not contain any of the following characters: <>"},"type":"string"},"privacyStatus":{"description":"The privacy status of the YouTube post.","example":"private","type":"string","enum":["private","public","unlisted"]},"shouldNotifySubscribers":{"description":"Whether to notify subscribers about the YouTube post.","example":false,"type":"boolean"},"isMadeForKids":{"description":"Whether the YouTube post is made for kids.","example":false,"type":"boolean"},"containsSyntheticMedia":{"description":"Whether the media contains synthetic content, such as AI-generated images or deepfake videos. Default is false.","example":false,"type":"boolean"},"thumbnailUrl":{"minLength":1,"description":"URL of the custom thumbnail image for the YouTube video. Use the media upload endpoint to upload media files before publishing. Maximum file size is 2MB. Accepted formats: JPEG, PNG. Recommended: 1280x720 (16:9).","example":"https://database.blotato.io/some-thumbnail.jpg","type":"string"},"playlistIds":{"description":"YouTube playlist IDs to add the video to after upload.","maxItems":5,"type":"array","items":{"type":"string"}}},"required":["targetType","title","privacyStatus","shouldNotifySubscribers"]}]}},"required":["accountId","content","target"]},"scheduledAt":{"type":"string"}},"required":["id","account","draft","scheduledAt"]}},"count":{"type":"string"},"cursor":{"type":"string"}},"required":["items","count"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/schedules/{id}":{"get":{"summary":"Get a scheduled post by ID","tags":["publishing"],"description":"Fetches a single scheduled post by its ID. Returns the schedule details including the draft content and account information.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"schedule":{"type":"object","properties":{"id":{"type":"string"},"account":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"username":{"type":"string"},"profileImageUrl":{"type":"string","nullable":true},"subaccountId":{"type":"string","nullable":true},"subId":{"type":"string","nullable":true},"subaccountName":{"type":"string","nullable":true}},"required":["id","name","username","profileImageUrl","subaccountId","subId","subaccountName"],"nullable":true},"draft":{"type":"object","properties":{"accountId":{"description":"The ID of the social media account to publish the content to.","example":"1","type":"string"},"content":{"type":"object","allOf":[{"type":"object","properties":{"text":{"description":"The text content of the post.","example":"My text","type":"string"},"mediaUrls":{"description":"List of media URLs to include in the post.","maxItems":20,"type":"array","items":{"description":"URLs of media files (images, videos) to include in the post. Must originate from the blotato domain. Use the media upload endpoint to upload media files before publishing.","example":"https://database.blotato.io/some-image-path.jpg","type":"string"}}},"required":["text","mediaUrls"]},{"type":"object","properties":{"platform":{"description":"Social media platform","example":"twitter","type":"string","enum":["twitter","instagram","linkedin","facebook","tiktok","pinterest","threads","bluesky","youtube","other"]},"additionalPosts":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"text":{"description":"The text content of the post.","example":"My text","type":"string"},"mediaUrls":{"description":"List of media URLs to include in the post.","maxItems":20,"type":"array","items":{"description":"URLs of media files (images, videos) to include in the post. Must originate from the blotato domain. Use the media upload endpoint to upload media files before publishing.","example":"https://database.blotato.io/some-image-path.jpg","type":"string"}}},"required":["text","mediaUrls"]}}},"required":["platform"]}]},"target":{"type":"object","discriminator":{"propertyName":"targetType"},"oneOf":[{"type":"object","properties":{"targetType":{"description":"Publish to a custom webhook.","example":"webhook","type":"string","enum":["webhook"]},"url":{"minLength":1,"description":"The URL of the webhook to publish to.","example":"https://example.com/webhook","type":"string"}},"required":["targetType","url"]},{"type":"object","properties":{"targetType":{"description":"Publish to Twitter.","example":"twitter","type":"string","enum":["twitter"]}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to LinkedIn.","example":"linkedin","type":"string","enum":["linkedin"]},"pageId":{"minLength":1,"description":"The ID of the LinkedIn page to publish to.","example":"123456789","type":"string"}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to Facebook.","example":"facebook","type":"string","enum":["facebook"]},"pageId":{"pattern":"^\\d+$","description":"The ID of the Facebook page to publish to.","example":"123456789","type":"string"},"mediaType":{"description":"Whether the media is a reel or video.","example":"reel","type":"string","enum":["reel","story"]},"link":{"minLength":1,"description":"Link preview to attach to the Facebook post.","example":"https://blotato.com","type":"string"},"firstComment":{"minLength":1,"maxLength":8000,"description":"Auto-posted comment on posts and reels, immediately after publish. Not supported for stories.","example":"First comment!","type":"string"}},"required":["targetType","pageId"]},{"type":"object","properties":{"targetType":{"description":"Publish to Instagram.","example":"instagram","type":"string","enum":["instagram"]},"mediaType":{"description":"Whether the media is a reel or story.","example":"reel","type":"string","enum":["reel","story"]},"altText":{"minLength":1,"maxLength":1000,"description":"Alternative text, for accessibility purposes. Only supported on a single image or image media in a carousel.","example":"Describe the image here for accessibility","type":"string"},"shareToFeed":{"description":"Whether to also share the reel to the Instagram feed. Only applicable for reels.","example":false,"type":"boolean"},"audioName":{"minLength":1,"maxLength":2200,"description":"For Reels only. Name of the audio of your Reels media. You can only rename once, either while creating a reel or after from the audio page.","example":"My Custom Audio Name","type":"string"},"collaborators":{"description":"List of collaborators to add to the Instagram post.","minItems":1,"maxItems":3,"type":"array","items":{"minLength":1,"description":"The Instagram usernames of the collaborator to add to the post.","example":"instagram_username","type":"string"}},"coverImageUrl":{"minLength":1,"description":"URL of the cover image to use for the Instagram post. Use the media upload endpoint to upload media files before publishing. Maximum file size is 8MB. Only applicable to reels.","example":"https://database.blotato.io/some-image-path.jpg","type":"string"},"trial":{"description":"Settings for trial reels. Trial reels are shown only to non-followers.","type":"object","properties":{"graduationStrategy":{"description":"Strategy to use to determine when to graduate post from trial (convert the trial reel to a reel, sharing it to followers).","example":"SS_PERFORMANCE","type":"string","enum":["MANUAL","SS_PERFORMANCE"]}},"required":["graduationStrategy"]},"firstComment":{"minLength":1,"maxLength":2200,"description":"Auto-posted comment with feed posts and carousels, immediately after publish. Not supported for stories. Useful for links.","example":"Link in the first comment!","type":"string"}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to TikTok.","example":"tiktok","type":"string","enum":["tiktok"]},"privacyLevel":{"description":"The privacy level of the TikTok post.","example":"SELF_ONLY","type":"string","enum":["SELF_ONLY","PUBLIC_TO_EVERYONE","MUTUAL_FOLLOW_FRIENDS","FOLLOWER_OF_CREATOR"]},"disabledComments":{"description":"Whether to disable comments on the TikTok post.","example":false,"type":"boolean"},"disabledDuet":{"description":"Whether to disable duet on the TikTok post.","example":false,"type":"boolean"},"disabledStitch":{"description":"Whether to disable stitch on the TikTok post.","example":false,"type":"boolean"},"isBrandedContent":{"description":"Whether the TikTok post is branded content.","example":false,"type":"boolean"},"isYourBrand":{"description":"Whether the TikTok post is for your brand.","example":false,"type":"boolean"},"isAiGenerated":{"description":"Whether the TikTok post is AI-generated.","example":false,"type":"boolean"},"title":{"minLength":1,"maxLength":90,"description":"Title for the image posts. If notprovided, the first 90 characters of the post.content.text will be used.","example":"My TikTok Image Post Title","type":"string"},"autoAddMusic":{"description":"Whether to automatically add music to the TikTok image posts.","example":false,"type":"boolean"},"isDraft":{"description":"Don't publish the post immediately, save it as a draft instead. Default is false.","example":true,"type":"boolean"},"imageCoverIndex":{"minimum":0,"description":"Index of the image (starts from 0) to use as the cover for carousel posts. Only applicable for carousel image posts.","example":0,"type":"number"},"videoCoverTimestamp":{"minimum":0,"description":"Location in milliseconds of the video to use as the cover image. Only applicable for video posts. If not provided, the frame as 0 milliseconds will be used.","example":0,"type":"number"}},"required":["targetType","privacyLevel","disabledComments","disabledDuet","disabledStitch","isBrandedContent","isYourBrand","isAiGenerated"]},{"type":"object","properties":{"targetType":{"description":"Publish to Pinterest.","example":"pinterest","type":"string","enum":["pinterest"]},"boardId":{"minLength":1,"description":"The ID of the Pinterest board to publish to.","example":"123456789","type":"string"},"title":{"minLength":1,"maxLength":100,"description":"Title for the Pinterest post.","example":"My Pinterest Post Title","type":"string"},"link":{"maxLength":2048,"description":"Link for the Pinterest post.","example":"https://example.com/my-pinterest-post-link","type":"string"},"altText":{"maxLength":500,"description":"Alternative text for the Pinterest post, for accessibility purposes.","example":"Describe the image here for accessibility","type":"string"}},"required":["targetType","boardId"]},{"type":"object","properties":{"targetType":{"description":"Publish to Threads.","example":"threads","type":"string","enum":["threads"]},"replyControl":{"description":"Who can reply to the Threads post.","example":"everyone","type":"string","enum":["everyone","accounts_you_follow","mentioned_only"]}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to Bluesky.","example":"bluesky","type":"string","enum":["bluesky"]}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to YouTube.","example":"youtube","type":"string","enum":["youtube"]},"title":{"minLength":1,"maxLength":100,"pattern":"^[^<>]*$","description":"Title for the YouTube post. Must not contain any of the following characters: <>","errorMessage":{"pattern":"must not contain any of the following characters: <>"},"type":"string"},"privacyStatus":{"description":"The privacy status of the YouTube post.","example":"private","type":"string","enum":["private","public","unlisted"]},"shouldNotifySubscribers":{"description":"Whether to notify subscribers about the YouTube post.","example":false,"type":"boolean"},"isMadeForKids":{"description":"Whether the YouTube post is made for kids.","example":false,"type":"boolean"},"containsSyntheticMedia":{"description":"Whether the media contains synthetic content, such as AI-generated images or deepfake videos. Default is false.","example":false,"type":"boolean"},"thumbnailUrl":{"minLength":1,"description":"URL of the custom thumbnail image for the YouTube video. Use the media upload endpoint to upload media files before publishing. Maximum file size is 2MB. Accepted formats: JPEG, PNG. Recommended: 1280x720 (16:9).","example":"https://database.blotato.io/some-thumbnail.jpg","type":"string"},"playlistIds":{"description":"YouTube playlist IDs to add the video to after upload.","maxItems":5,"type":"array","items":{"type":"string"}}},"required":["targetType","title","privacyStatus","shouldNotifySubscribers"]}]}},"required":["accountId","content","target"]},"scheduledAt":{"type":"string"}},"required":["id","account","draft","scheduledAt"]}},"required":["schedule"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}},"patch":{"summary":"Updates a scheduled post. The post must be in scheduled state to be updated. You can update the scheduled time or change the post contents.","tags":["publishing"],"description":"Updates a scheduled post by ID. You can update the draft content, the scheduled time, or both. The scheduled time must be a valid ISO 8601 date in the future. When the scheduled time is changed, the post is re-queued for publishing at the new time.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"patch":{"description":"The fields to update in the schedule.","type":"object","properties":{"draft":{"type":"object","properties":{"accountId":{"description":"The ID of the social media account to publish the content to.","example":"1","type":"string"},"content":{"type":"object","allOf":[{"type":"object","properties":{"text":{"description":"The text content of the post.","example":"My text","type":"string"},"mediaUrls":{"description":"List of media URLs to include in the post.","maxItems":20,"type":"array","items":{"description":"URLs of media files (images, videos) to include in the post. Must originate from the blotato domain. Use the media upload endpoint to upload media files before publishing.","example":"https://database.blotato.io/some-image-path.jpg","type":"string"}}},"required":["text","mediaUrls"]},{"type":"object","properties":{"platform":{"description":"Social media platform","example":"twitter","type":"string","enum":["twitter","instagram","linkedin","facebook","tiktok","pinterest","threads","bluesky","youtube","other"]},"additionalPosts":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"text":{"description":"The text content of the post.","example":"My text","type":"string"},"mediaUrls":{"description":"List of media URLs to include in the post.","maxItems":20,"type":"array","items":{"description":"URLs of media files (images, videos) to include in the post. Must originate from the blotato domain. Use the media upload endpoint to upload media files before publishing.","example":"https://database.blotato.io/some-image-path.jpg","type":"string"}}},"required":["text","mediaUrls"]}}},"required":["platform"]}]},"target":{"type":"object","discriminator":{"propertyName":"targetType"},"oneOf":[{"type":"object","properties":{"targetType":{"description":"Publish to a custom webhook.","example":"webhook","type":"string","enum":["webhook"]},"url":{"minLength":1,"description":"The URL of the webhook to publish to.","example":"https://example.com/webhook","type":"string"}},"required":["targetType","url"]},{"type":"object","properties":{"targetType":{"description":"Publish to Twitter.","example":"twitter","type":"string","enum":["twitter"]}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to LinkedIn.","example":"linkedin","type":"string","enum":["linkedin"]},"pageId":{"minLength":1,"description":"The ID of the LinkedIn page to publish to.","example":"123456789","type":"string"}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to Facebook.","example":"facebook","type":"string","enum":["facebook"]},"pageId":{"pattern":"^\\d+$","description":"The ID of the Facebook page to publish to.","example":"123456789","type":"string"},"mediaType":{"description":"Whether the media is a reel or video.","example":"reel","type":"string","enum":["reel","story"]},"link":{"minLength":1,"description":"Link preview to attach to the Facebook post.","example":"https://blotato.com","type":"string"},"firstComment":{"minLength":1,"maxLength":8000,"description":"Auto-posted comment on posts and reels, immediately after publish. Not supported for stories.","example":"First comment!","type":"string"}},"required":["targetType","pageId"]},{"type":"object","properties":{"targetType":{"description":"Publish to Instagram.","example":"instagram","type":"string","enum":["instagram"]},"mediaType":{"description":"Whether the media is a reel or story.","example":"reel","type":"string","enum":["reel","story"]},"altText":{"minLength":1,"maxLength":1000,"description":"Alternative text, for accessibility purposes. Only supported on a single image or image media in a carousel.","example":"Describe the image here for accessibility","type":"string"},"shareToFeed":{"description":"Whether to also share the reel to the Instagram feed. Only applicable for reels.","example":false,"type":"boolean"},"audioName":{"minLength":1,"maxLength":2200,"description":"For Reels only. Name of the audio of your Reels media. You can only rename once, either while creating a reel or after from the audio page.","example":"My Custom Audio Name","type":"string"},"collaborators":{"description":"List of collaborators to add to the Instagram post.","minItems":1,"maxItems":3,"type":"array","items":{"minLength":1,"description":"The Instagram usernames of the collaborator to add to the post.","example":"instagram_username","type":"string"}},"coverImageUrl":{"minLength":1,"description":"URL of the cover image to use for the Instagram post. Use the media upload endpoint to upload media files before publishing. Maximum file size is 8MB. Only applicable to reels.","example":"https://database.blotato.io/some-image-path.jpg","type":"string"},"trial":{"description":"Settings for trial reels. Trial reels are shown only to non-followers.","type":"object","properties":{"graduationStrategy":{"description":"Strategy to use to determine when to graduate post from trial (convert the trial reel to a reel, sharing it to followers).","example":"SS_PERFORMANCE","type":"string","enum":["MANUAL","SS_PERFORMANCE"]}},"required":["graduationStrategy"]},"firstComment":{"minLength":1,"maxLength":2200,"description":"Auto-posted comment with feed posts and carousels, immediately after publish. Not supported for stories. Useful for links.","example":"Link in the first comment!","type":"string"}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to TikTok.","example":"tiktok","type":"string","enum":["tiktok"]},"privacyLevel":{"description":"The privacy level of the TikTok post.","example":"SELF_ONLY","type":"string","enum":["SELF_ONLY","PUBLIC_TO_EVERYONE","MUTUAL_FOLLOW_FRIENDS","FOLLOWER_OF_CREATOR"]},"disabledComments":{"description":"Whether to disable comments on the TikTok post.","example":false,"type":"boolean"},"disabledDuet":{"description":"Whether to disable duet on the TikTok post.","example":false,"type":"boolean"},"disabledStitch":{"description":"Whether to disable stitch on the TikTok post.","example":false,"type":"boolean"},"isBrandedContent":{"description":"Whether the TikTok post is branded content.","example":false,"type":"boolean"},"isYourBrand":{"description":"Whether the TikTok post is for your brand.","example":false,"type":"boolean"},"isAiGenerated":{"description":"Whether the TikTok post is AI-generated.","example":false,"type":"boolean"},"title":{"minLength":1,"maxLength":90,"description":"Title for the image posts. If notprovided, the first 90 characters of the post.content.text will be used.","example":"My TikTok Image Post Title","type":"string"},"autoAddMusic":{"description":"Whether to automatically add music to the TikTok image posts.","example":false,"type":"boolean"},"isDraft":{"description":"Don't publish the post immediately, save it as a draft instead. Default is false.","example":true,"type":"boolean"},"imageCoverIndex":{"minimum":0,"description":"Index of the image (starts from 0) to use as the cover for carousel posts. Only applicable for carousel image posts.","example":0,"type":"number"},"videoCoverTimestamp":{"minimum":0,"description":"Location in milliseconds of the video to use as the cover image. Only applicable for video posts. If not provided, the frame as 0 milliseconds will be used.","example":0,"type":"number"}},"required":["targetType","privacyLevel","disabledComments","disabledDuet","disabledStitch","isBrandedContent","isYourBrand","isAiGenerated"]},{"type":"object","properties":{"targetType":{"description":"Publish to Pinterest.","example":"pinterest","type":"string","enum":["pinterest"]},"boardId":{"minLength":1,"description":"The ID of the Pinterest board to publish to.","example":"123456789","type":"string"},"title":{"minLength":1,"maxLength":100,"description":"Title for the Pinterest post.","example":"My Pinterest Post Title","type":"string"},"link":{"maxLength":2048,"description":"Link for the Pinterest post.","example":"https://example.com/my-pinterest-post-link","type":"string"},"altText":{"maxLength":500,"description":"Alternative text for the Pinterest post, for accessibility purposes.","example":"Describe the image here for accessibility","type":"string"}},"required":["targetType","boardId"]},{"type":"object","properties":{"targetType":{"description":"Publish to Threads.","example":"threads","type":"string","enum":["threads"]},"replyControl":{"description":"Who can reply to the Threads post.","example":"everyone","type":"string","enum":["everyone","accounts_you_follow","mentioned_only"]}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to Bluesky.","example":"bluesky","type":"string","enum":["bluesky"]}},"required":["targetType"]},{"type":"object","properties":{"targetType":{"description":"Publish to YouTube.","example":"youtube","type":"string","enum":["youtube"]},"title":{"minLength":1,"maxLength":100,"pattern":"^[^<>]*$","description":"Title for the YouTube post. Must not contain any of the following characters: <>","errorMessage":{"pattern":"must not contain any of the following characters: <>"},"type":"string"},"privacyStatus":{"description":"The privacy status of the YouTube post.","example":"private","type":"string","enum":["private","public","unlisted"]},"shouldNotifySubscribers":{"description":"Whether to notify subscribers about the YouTube post.","example":false,"type":"boolean"},"isMadeForKids":{"description":"Whether the YouTube post is made for kids.","example":false,"type":"boolean"},"containsSyntheticMedia":{"description":"Whether the media contains synthetic content, such as AI-generated images or deepfake videos. Default is false.","example":false,"type":"boolean"},"thumbnailUrl":{"minLength":1,"description":"URL of the custom thumbnail image for the YouTube video. Use the media upload endpoint to upload media files before publishing. Maximum file size is 2MB. Accepted formats: JPEG, PNG. Recommended: 1280x720 (16:9).","example":"https://database.blotato.io/some-thumbnail.jpg","type":"string"},"playlistIds":{"description":"YouTube playlist IDs to add the video to after upload.","maxItems":5,"type":"array","items":{"type":"string"}}},"required":["targetType","title","privacyStatus","shouldNotifySubscribers"]}]}},"required":["accountId","content","target"]},"scheduledTime":{"description":"The new scheduled time for the post (ISO 8601 format).","type":"string"}}}},"required":["patch"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"The ID of the schedule to update."}],"security":[{"apiKey":[]}],"responses":{"204":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Validation error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Validation error","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}},"delete":{"summary":"Delete a scheduled post","tags":["publishing"],"description":"Deletes a scheduled post by its ID. The associated publishing job is also cancelled.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"The ID of the schedule to delete."}],"security":[{"apiKey":[]}],"responses":{"204":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/source-resolutions-v3":{"post":{"summary":"Resolves a source asynchronously","tags":["publishing"],"description":"Submits a source for asynchronous resolution. The response contains a source resolution ID that can be used to check the status of the resolution. A source can be any text content, URL, or other data that needs to be processed to generate a title and content. Source resolution has a user-level rate limit of **30 requests / minute**.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"object","discriminator":{"propertyName":"sourceType"},"oneOf":[{"type":"object","properties":{"sourceType":{"type":"string","enum":["text"]},"text":{"type":"string"}},"required":["sourceType","text"]},{"type":"object","properties":{"sourceType":{"type":"string","enum":["article"]},"url":{"type":"string"}},"required":["sourceType","url"]},{"type":"object","properties":{"sourceType":{"type":"string","enum":["youtube"]},"url":{"type":"string"}},"required":["sourceType","url"]},{"type":"object","properties":{"sourceType":{"type":"string","enum":["twitter"]},"url":{"type":"string"}},"required":["sourceType","url"]},{"type":"object","properties":{"sourceType":{"type":"string","enum":["tiktok"]},"url":{"type":"string"}},"required":["sourceType","url"]},{"type":"object","properties":{"sourceType":{"type":"string","enum":["perplexity-query"]},"text":{"type":"string"}},"required":["sourceType","text"]},{"type":"object","properties":{"sourceType":{"type":"string","enum":["audio"]},"url":{"type":"string"}},"required":["sourceType","url"]},{"type":"object","properties":{"sourceType":{"type":"string","enum":["pdf"]},"url":{"type":"string"}},"required":["sourceType","url"]}]},"customInstructions":{"type":"string"}},"required":["source"]}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"description":"Validation error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Validation error","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/source-resolutions-v3/{id}":{"get":{"summary":"Get source resolution status","tags":["publishing"],"description":"Fetches the status of a source resolution by its ID. This endpoint allows users to check whether the source has been resolved or is still in the queue. Source resolution lookup has a user-level rate limit of **60 requests / minute**.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","discriminator":{"propertyName":"status"},"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["completed"]},"title":{"type":"string"},"content":{"type":"string"},"referenceUrl":{"type":"string"}},"required":["id","status","title","content"]},{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued"]}},"required":["id","status"]},{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["processing"]}},"required":["id","status"]},{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["failed"]},"message":{"type":"string"}},"required":["id","status","message"]}]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/users/me":{"get":{"summary":"Get current user information","tags":["accounts"],"description":"Fetches the current user's information, including subscription status and API key if available.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Current user information","content":{"application/json":{"schema":{"description":"Current user information","example":{"id":"user_12345","subscriptionStatus":"active","apiKey":"your-api-key","subscriptionPlan":"creator"},"type":"object","properties":{"id":{"type":"string"},"subscriptionStatus":{"type":"string","nullable":true},"apiKey":{"type":"string","nullable":true},"subscriptionPlan":{"type":"string","enum":["starter","creator","agency"]}},"required":["id","subscriptionStatus","apiKey","subscriptionPlan"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Unauthorized access","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/users/me/accounts":{"get":{"summary":"Get current user accounts","tags":["accounts"],"description":"Fetches the current user's social media accounts. Optionally filter by platform.","parameters":[{"schema":{"example":"twitter","type":"string","enum":["twitter","instagram","linkedin","facebook","tiktok","pinterest","threads","bluesky","youtube","other"]},"in":"query","name":"platform","required":false,"description":"Social media platform"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"description":"List of social media accounts","type":"array","items":{"example":[{"id":"12345","platform":"twitter","fullname":"John Doe","username":"@johndoe"}],"type":"object","properties":{"id":{"type":"string"},"platform":{"description":"Social media platform","example":"twitter","type":"string","enum":["twitter","instagram","linkedin","facebook","tiktok","pinterest","threads","bluesky","youtube","other"]},"fullname":{"type":"string"},"username":{"type":"string"}},"required":["id","platform","fullname","username"]}}},"required":["items"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Unauthorized access","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/users/me/accounts/{accountId}/subaccounts":{"get":{"summary":"Get current user subaccounts","tags":["accounts"],"description":"Fetches the current user's subaccounts for a specific account. Subaccounts are typically used for platforms like Facebook where a user can have multiple pages.","parameters":[{"schema":{"type":"string"},"in":"path","name":"accountId","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"example":{"id":"facebook_page_12345","accountId":"account_67890","name":"My Facebook Page"},"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"}},"required":["id","accountId","name"]}}},"required":["items"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Unauthorized access","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/videos/{id}":{"delete":{"summary":"Remove a video by ID","tags":["video"],"description":"Deletes a video by its ID. This is used to remove videos that are no longer needed or were created in error.","parameters":[{"schema":{"format":"uuid","type":"string"},"example":"123e4567-e89b-12d3-a456-426614174000","in":"path","name":"id","required":true,"description":"Video ID"}],"security":[{"apiKey":[]}],"responses":{"204":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"format":"uuid","description":"Video ID","type":"string","example":"123e4567-e89b-12d3-a456-426614174000"}},"required":["id"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/videos/creations/{id}":{"get":{"summary":"Get a single video","tags":["video"],"description":"Retrieves the video by its ID. This is useful for polling after creating a video programmatically.","parameters":[{"schema":{"format":"uuid","type":"string"},"example":"123e4567-e89b-12d3-a456-426614174000","in":"path","name":"id","required":true,"description":"Video ID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"description":"Video details","example":{"id":"123e4567-e89b-12d3-a456-426614174000","status":"completed","createdAt":"2026-08-29T23:38:47.411Z","mediaUrl":"https://database.blotato.io/media/12345.mp4"},"type":"object","properties":{"id":{"format":"uuid","description":"Video ID","type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"status":{"description":"Current status of the video generation process","type":"string","enum":["queueing","generating-script","script-ready","generating-media","media-ready","exporting","done","creation-from-template-failed","insufficient-credits","draft"]},"error":{"description":"Optional error message if the video failed to generate.","type":"string"},"errorMetadata":{"type":"object","properties":{"creditsRequired":{"type":"number"},"creditsRemaining":{"type":"number"}},"required":["creditsRequired","creditsRemaining"]},"createdAt":{"description":"Creation timestamp of the video","format":"date-time","type":"string","example":"2023-10-01T12:00:00Z"},"mediaUrl":{"description":"Public URL of the final exported video media","type":"string","nullable":true},"imageUrls":{"description":"For slideshow exports, this will contain the images used in the video.","type":"array","items":{"type":"string"},"nullable":true}},"required":["id","status","createdAt","imageUrls"]}},"required":["item"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"description":"Server error","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"An error occurred","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/videos/from-templates":{"post":{"summary":"Create a video from the new template system","tags":["video"],"description":"Creates a new video using a template. The template takes an ID and input parameters. You can also provide an optional prompt to fill out the input parameters automatically.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"templateId":{"type":"string"},"inputs":{},"prompt":{"type":"string"},"isDraft":{"default":false,"type":"boolean"},"render":{"default":true,"type":"boolean"},"title":{"minLength":1,"type":"string"},"useBrandKit":{"default":false,"type":"boolean"},"brandId":{"type":"string","nullable":true}},"required":["templateId","inputs","render"]}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"type":"object","properties":{"id":{"format":"uuid","description":"Video ID","type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"status":{"description":"Current status of the video generation process","type":"string","enum":["queueing","generating-script","script-ready","generating-media","media-ready","exporting","done","creation-from-template-failed","insufficient-credits","draft"]}},"required":["id","status"]}},"required":["item"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Resource not found","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}},"/v2/videos/templates":{"get":{"summary":"List all templates","tags":["video"],"description":"List all available video templates along with the specification of their input parameters.","parameters":[{"schema":{"example":"id,title,description,inputs","default":"id,title,description","type":"string"},"in":"query","name":"fields","required":false,"description":"Comma separated list of fields to include. If provided, only these fields will be included in the response for each template. If omitted, only id, title, and description are included. Id is always included in the response."},{"schema":{"example":"real estate","type":"string"},"in":"query","name":"search","required":false,"description":"Search regex term to filter templates by title or description. Has no effect if \"id\" is also provided."},{"schema":{"example":"/base/v2/tweet-card/9714ae5c-7e6b-4878-be4a-4b1ba5d0cd66/v1","type":"string"},"in":"query","name":"id","required":false,"description":"If provided, only the template with this ID will be returned."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{}}},"required":["items"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"description":"Forbidden","type":"object","properties":{"code":{"type":"number"},"reqId":{"description":"Request ID for tracking","type":"string"},"message":{"description":"Forbidden access","type":"string"},"subscriptionStatus":{"description":"Current subscription plan status","type":"string"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"action":{"description":"Action to take to resolve the error","type":"string"},"details":{"description":"Additional structured details about the error","type":"object","additionalProperties":{}}},"required":["message"]}}}}}}}},"servers":[{"url":"https://backend.blotato.com","description":"Blotato API Server"}],"tags":[{"name":"publishing","description":"Endpoints related to publishing content, such as posts and drafts."},{"name":"accounts","description":"Endpoints related to user accounts and social media accounts."},{"name":"billing","description":"Endpoints related to credits, credit balance, and credit purchases."},{"name":"video","description":"Endpoints related to video creation and management."},{"name":"analytics","description":"Endpoints related to social media analytics for published posts."},{"name":"messaging","description":"Endpoints related to reading and sending direct messages on connected social media accounts."},{"name":"comments","description":"Endpoints related to reading and posting comments on social posts."},{"name":"automations","description":"Endpoints related to DM automations, which send a direct message in response to a comment or message on a connected social account."}],"externalDocs":{"url":"https://help.blotato.com","description":"Find more info here"}}