Tài liệu tham khảo API
Phiên bản API 2026-11-09 · Tải OpenAPI 3.1 YAML
Xác thực dùng một khóa sản phẩm thuộc phạm vi không gian làm việc: Authorization: Bearer pk_v1_…. Khóa mang các phạm vi rõ ràng và một danh sách cho phép tài khoản tùy chọn; chúng không bao giờ có thể tạo khóa khác hay thay đổi thanh toán.
Mọi thao tác thay đổi đều cần một header Idempotency-Key; chỉnh sửa và lên lịch cũng cần expectedVersion. Đăng và lên lịch trả về 202 Accepted với một ID gửi đi cho mỗi điểm đến: 202 không bao giờ là lời khẳng định rằng có gì đó đã được đăng. Xác minh kết quả qua GET /posts/{id}, webhook của khách hàng, hoặc polling có giới hạn kèm backoff.
Lỗi dùng phong bì chuẩn hóa từ hợp đồng v1: code, message an toàn, fieldErrors, destinationErrors, retryable, retryAfterSeconds và requestId. Một cách chủ đích không có mã lỗi tín dụng hay hạn mức đăng bài.
Xác thực
Gửi khóa không gian dạng "Authorization: Bearer pk_v1_…". Mỗi thao tác liệt kê phạm vi cần thiết. Xem xác thực và quyền.
GET /capabilities
Các định dạng và lựa chọn đủ điều kiện cho những điểm đến được phép
Yêu cầu phạm vi accounts:read.
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"accounts"
],
"summary": "Các định dạng và lựa chọn đủ điều kiện cho những điểm đến được phép",
"description": "Yêu cầu phạm vi `accounts:read`.",
"responses": {
"200": {
"description": "Capability list",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"capabilities",
"requestId"
],
"properties": {
"capabilities": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Capability"
}
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}GET /accounts
Liệt kê các tài khoản điểm đến mà khóa này có thể thấy
Tuân theo danh sách cho phép tài khoản của khóa. Yêu cầu phạm vi accounts:read.
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"accounts"
],
"summary": "Liệt kê các tài khoản điểm đến mà khóa này có thể thấy",
"description": "Tuân theo danh sách cho phép tài khoản của khóa. Yêu cầu phạm vi `accounts:read`.",
"parameters": [
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/limit"
}
],
"responses": {
"200": {
"description": "Account page",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"accounts",
"requestId"
],
"properties": {
"accounts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Account"
}
},
"nextCursor": {
"type": [
"string",
"null"
]
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}GET /accounts/{id}/tiktok/settings
Đọc cài đặt creator TikTok đã được xác minh cho một tài khoản đã kết nối được phép
Yêu cầu accounts:read và danh sách cho phép tài khoản của khóa. Lần đọc này không bao giờ cung cấp sự đồng ý đăng của con người.
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"accounts"
],
"summary": "Đọc cài đặt creator TikTok đã được xác minh cho một tài khoản đã kết nối được phép",
"description": "Yêu cầu accounts:read và danh sách cho phép tài khoản của khóa. Lần đọc này không bao giờ cung cấp sự đồng ý đăng của con người.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Current typed creator settings; a person must confirm choices in the composer",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"settings",
"humanConfirmationRequired",
"requestId"
],
"properties": {
"settings": {
"$ref": "#/components/schemas/TikTokCreatorSettings"
},
"humanConfirmationRequired": {
"type": "boolean",
"const": true
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /media/upload-intents
Đặt chỗ byte và trả về hướng dẫn tải lên trực tiếp
Yêu cầu phạm vi media:write cùng một Idempotency-Key. Byte được tải lên TRỰC TIẾP vào nơi lưu trữ đối tượng riêng tư bằng các hướng dẫn được trả về; chúng không bao giờ đi qua API này. Không tồn tại URL media công khai vĩnh viễn.
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"media"
],
"summary": "Đặt chỗ byte và trả về hướng dẫn tải lên trực tiếp",
"description": "Yêu cầu phạm vi `media:write` cùng một Idempotency-Key. Byte được tải lên TRỰC TIẾP vào nơi lưu trữ đối tượng riêng tư bằng các hướng dẫn được trả về; chúng không bao giờ đi qua API này. Không tồn tại URL media công khai vĩnh viễn.\n",
"parameters": [
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadIntentRequest"
}
}
}
},
"responses": {
"201": {
"description": "Upload instructions created",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadIntentResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/Validation"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}GET /media/{id}
Trạng thái và thời hạn của media (không có URL công khai vĩnh viễn)
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"media"
],
"summary": "Trạng thái và thời hạn của media (không có URL công khai vĩnh viễn)",
"parameters": [
{
"$ref": "#/components/parameters/id"
}
],
"responses": {
"200": {
"description": "Media status",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"media",
"requestId"
],
"properties": {
"media": {
"$ref": "#/components/schemas/MediaStatus"
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /media/{id}/upload-parts
Làm mới từ một đến 64 URL PUT multipart trong một phiên tải lên hiện có
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"media"
],
"summary": "Làm mới từ một đến 64 URL PUT multipart trong một phiên tải lên hiện có",
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"fromPart",
"toPart"
],
"properties": {
"fromPart": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"toPart": {
"type": "integer",
"minimum": 1,
"maximum": 10000
}
}
}
}
}
},
"responses": {
"200": {
"description": "Fresh upload URLs; toPart must be at least fromPart and at most fromPart + 63",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"sessionId",
"parts",
"requestId"
],
"properties": {
"sessionId": {
"type": "string",
"format": "uuid"
},
"requestId": {
"type": "string"
},
"parts": {
"type": "array",
"items": {
"type": "object",
"required": [
"partNumber",
"url",
"expiresAt"
],
"properties": {
"partNumber": {
"type": "integer"
},
"url": {
"type": "string",
"format": "uri"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/Validation"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /media/{id}/abandon
Từ bỏ một lần tải chưa hoàn thành và giải phóng phần đặt chỗ lưu trữ của nó
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"media"
],
"summary": "Từ bỏ một lần tải chưa hoàn thành và giải phóng phần đặt chỗ lưu trữ của nó",
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Abandoned; failed external cleanup remains durably queued",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"abandoned",
"requestId"
],
"properties": {
"abandoned": {
"type": "boolean",
"const": true
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /media/{id}/finalize
Xác minh đối tượng đã tải lên và làm cho nó dùng được
Yêu cầu phạm vi media:write cùng một Idempotency-Key. Máy chủ xác minh kích thước/MIME và các chữ ký có giới hạn với bản sao FINAL bất biến; các phần đặt chỗ byte được tất toán đúng một lần. Chỉ gửi định danh phiên (kèm biên nhận phần multipart khi áp dụng): máy chủ tự quan sát toàn bộ siêu dữ liệu.
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"media"
],
"summary": "Xác minh đối tượng đã tải lên và làm cho nó dùng được",
"description": "Yêu cầu phạm vi `media:write` cùng một Idempotency-Key. Máy chủ xác minh kích thước/MIME và các chữ ký có giới hạn với bản sao FINAL bất biến; các phần đặt chỗ byte được tất toán đúng một lần. Chỉ gửi định danh phiên (kèm biên nhận phần multipart khi áp dụng): máy chủ tự quan sát toàn bộ siêu dữ liệu.\n",
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FinalizeRequest"
}
}
}
},
"responses": {
"200": {
"description": "Finalized",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"media",
"requestId"
],
"properties": {
"media": {
"$ref": "#/components/schemas/FinalizeResult"
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/Validation"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /posts
Tạo bản nháp
Yêu cầu phạm vi posts:write cùng một Idempotency-Key. Phần thân được phân tích bằng DraftInputSchema nghiêm ngặt của hợp đồng v1; các tài khoản điểm đến trùng lặp bị từ chối. Việc lưu nới lỏng: hãy xác thực trước khi đăng.
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"posts"
],
"summary": "Tạo bản nháp",
"description": "Yêu cầu phạm vi `posts:write` cùng một Idempotency-Key. Phần thân được phân tích bằng DraftInputSchema nghiêm ngặt của hợp đồng v1; các tài khoản điểm đến trùng lặp bị từ chối. Việc lưu nới lỏng: hãy xác thực trước khi đăng.\n",
"parameters": [
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DraftInput"
}
}
}
},
"responses": {
"201": {
"description": "Draft created",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"post",
"requestId"
],
"properties": {
"post": {
"$ref": "#/components/schemas/DraftSaveResult"
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/Validation"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}GET /posts
Liệt kê bài đăng
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"posts"
],
"summary": "Liệt kê bài đăng",
"parameters": [
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/limit"
},
{
"name": "state",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Post page",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"posts",
"requestId"
],
"properties": {
"posts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PostListItem"
}
},
"nextCursor": {
"type": [
"string",
"null"
]
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}GET /posts/{id}
Trạng thái tổng hợp của bài đăng và theo từng điểm đến
"Được nhà cung cấp chấp nhận" không phải là "Đã đăng". Liên kết gốc chỉ xuất hiện sau một biên nhận được xác nhận; thiếu permalink không phải bằng chứng thất bại.
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"posts"
],
"summary": "Trạng thái tổng hợp của bài đăng và theo từng điểm đến",
"description": "\"Được nhà cung cấp chấp nhận\" không phải là \"Đã đăng\". Liên kết gốc chỉ xuất hiện sau một biên nhận được xác nhận; thiếu permalink không phải bằng chứng thất bại.\n",
"parameters": [
{
"$ref": "#/components/parameters/id"
}
],
"responses": {
"200": {
"description": "Post status",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"post",
"requestId"
],
"properties": {
"post": {
"$ref": "#/components/schemas/PostStatus"
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}PATCH /posts/{id}
Chỉnh sửa bản nháp (có kiểm tra phiên bản)
Yêu cầu Idempotency-Key và expectedVersion. Phiên bản cũ trả về 409 revision_conflict với phiên bản hiện tại trong error.details.currentVersion.
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"posts"
],
"summary": "Chỉnh sửa bản nháp (có kiểm tra phiên bản)",
"description": "Yêu cầu Idempotency-Key và expectedVersion. Phiên bản cũ trả về 409 revision_conflict với phiên bản hiện tại trong `error.details.currentVersion`.\n",
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DraftUpdateInput"
}
}
}
},
"responses": {
"200": {
"description": "Updated draft",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"post",
"requestId"
],
"properties": {
"post": {
"$ref": "#/components/schemas/DraftSaveResult"
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/Validation"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /posts/{id}/validate
Xác thực có cấu trúc theo điểm đến (không thay đổi dữ liệu)
Trả về 200 với validation.valid=false khi các điểm đến có vấn đề (không bao giờ là trạng thái lỗi cho các vấn đề nội dung).
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"posts"
],
"summary": "Xác thực có cấu trúc theo điểm đến (không thay đổi dữ liệu)",
"description": "Trả về 200 với `validation.valid=false` khi các điểm đến có vấn đề (không bao giờ là trạng thái lỗi cho các vấn đề nội dung).\n",
"parameters": [
{
"$ref": "#/components/parameters/id"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedVersion": {
"type": "integer",
"minimum": 1
}
}
}
}
}
},
"responses": {
"200": {
"description": "Validation result",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"validation",
"requestId"
],
"properties": {
"validation": {
"$ref": "#/components/schemas/ValidationResult"
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /posts/{id}/publish
Đăng ngay (202)
Yêu cầu phạm vi posts:publish cùng một Idempotency-Key. expectedVersion tùy chọn áp dụng bảo đảm đồng thời lạc quan giống như khi chỉnh sửa. Trả về một ID gửi đi cho mỗi điểm đến; không bao giờ tuyên bố đã đăng.
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"posts"
],
"summary": "Đăng ngay (202)",
"description": "Yêu cầu phạm vi `posts:publish` cùng một Idempotency-Key. `expectedVersion` tùy chọn áp dụng bảo đảm đồng thời lạc quan giống như khi chỉnh sửa. Trả về một ID gửi đi cho mỗi điểm đến; không bao giờ tuyên bố đã đăng.\n",
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"expectedVersion": {
"type": "integer",
"minimum": 1
}
}
}
}
}
},
"responses": {
"202": {
"description": "Accepted for dispatch",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AcceptedOperation"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/Validation"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /posts/{id}/schedule
Lên lịch cho phiên bản đã đóng băng (202)
Yêu cầu phạm vi posts:publish cùng Idempotency-Key và expectedVersion. Một thời điểm cho toàn bộ lô; phải ở trong tương lai và trong phạm vi 90 ngày (do dịch vụ dùng chung thực thi). revisionId phải là null trong V1: việc chọn một phiên bản tùy ý không được hỗ trợ và bị từ chối.
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"posts"
],
"summary": "Lên lịch cho phiên bản đã đóng băng (202)",
"description": "Yêu cầu phạm vi `posts:publish` cùng Idempotency-Key và expectedVersion. Một thời điểm cho toàn bộ lô; phải ở trong tương lai và trong phạm vi 90 ngày (do dịch vụ dùng chung thực thi). `revisionId` phải là null trong V1: việc chọn một phiên bản tùy ý không được hỗ trợ và bị từ chối.\n",
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleRequest"
}
}
}
},
"responses": {
"202": {
"description": "Scheduled",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AcceptedOperation"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/Validation"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /deliveries/{id}/cancel
Hủy một công việc điểm đến nếu vẫn chưa được nhận an toàn
Yêu cầu phạm vi posts:publish cùng Idempotency-Key. Các lượt gửi đã gửi đi trả về 409 too_late_to_cancel với trạng thái thực tế.
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"deliveries"
],
"summary": "Hủy một công việc điểm đến nếu vẫn chưa được nhận an toàn",
"description": "Yêu cầu phạm vi `posts:publish` cùng Idempotency-Key. Các lượt gửi đã gửi đi trả về 409 too_late_to_cancel với trạng thái thực tế.\n",
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"responses": {
"200": {
"description": "Cancellation result",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"delivery",
"requestId"
],
"properties": {
"delivery": {
"type": "object",
"required": [
"deliveryId",
"canceled",
"state"
],
"properties": {
"deliveryId": {
"type": "string"
},
"canceled": {
"type": "boolean"
},
"state": {
"type": "string"
}
}
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /deliveries/{id}/retry
Thử lại một điểm đến đã biết là thất bại
Yêu cầu phạm vi posts:publish cùng Idempotency-Key. Các kết quả không rõ hay lượt gửi thành công bị từ chối: thử lại có thể làm trùng lặp bài đăng.
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"deliveries"
],
"summary": "Thử lại một điểm đến đã biết là thất bại",
"description": "Yêu cầu phạm vi `posts:publish` cùng Idempotency-Key. Các kết quả không rõ hay lượt gửi thành công bị từ chối: thử lại có thể làm trùng lặp bài đăng.\n",
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"responses": {
"200": {
"description": "Retry accepted",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"delivery",
"requestId"
],
"properties": {
"delivery": {
"type": "object",
"required": [
"deliveryId",
"state"
],
"properties": {
"deliveryId": {
"type": "string"
},
"state": {
"type": "string"
}
}
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}GET /usage
Gói, mức sử dụng tài khoản/chỗ/lưu trữ, hoạt động và thông tin tốc độ
Yêu cầu phạm vi usage:read. KHÔNG chứa bộ đếm bài đăng còn lại dưới bất kỳ hình thức nào: đăng bài không giới hạn trên mọi gói trả phí.
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"usage"
],
"summary": "Gói, mức sử dụng tài khoản/chỗ/lưu trữ, hoạt động và thông tin tốc độ",
"description": "Yêu cầu phạm vi `usage:read`. KHÔNG chứa bộ đếm bài đăng còn lại dưới bất kỳ hình thức nào: đăng bài không giới hạn trên mọi gói trả phí.\n",
"responses": {
"200": {
"description": "Usage snapshot",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"usage",
"requestId"
],
"properties": {
"usage": {
"$ref": "#/components/schemas/Usage"
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /webhooks
Đăng ký một điểm đến sự kiện của khách hàng
Yêu cầu phạm vi webhooks:manage cùng Idempotency-Key. Chỉ HTTPS; xác thực SSRF (scheme, thông tin xác thực, địa chỉ phân giải DNS có giới hạn) chạy trước khi lưu. Bí mật ký chỉ được trả về trong phản hồi tạo ĐẦU TIÊN: một lần phát lại idempotent trả về endpoint mà không có bí mật. Việc tạo cũng đưa một sự kiện xác minh có đích đến vào hàng đợi.
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"webhooks"
],
"summary": "Đăng ký một điểm đến sự kiện của khách hàng",
"description": "Yêu cầu phạm vi `webhooks:manage` cùng Idempotency-Key. Chỉ HTTPS; xác thực SSRF (scheme, thông tin xác thực, địa chỉ phân giải DNS có giới hạn) chạy trước khi lưu. Bí mật ký chỉ được trả về trong phản hồi tạo ĐẦU TIÊN: một lần phát lại idempotent trả về endpoint mà không có bí mật. Việc tạo cũng đưa một sự kiện xác minh có đích đến vào hàng đợi.\n",
"parameters": [
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWebhookRequest"
}
}
}
},
"responses": {
"201": {
"description": "Endpoint created (secret shown once)",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"webhook",
"requestId"
],
"properties": {
"webhook": {
"allOf": [
{
"$ref": "#/components/schemas/WebhookEndpoint"
},
{
"type": "object",
"properties": {
"secret": {
"type": [
"string",
"null"
],
"description": "Present only on the first successful creation; null on replay."
}
}
}
]
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/Validation"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}GET /webhooks
Liệt kê các điểm đến sự kiện (không có bí mật)
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"webhooks"
],
"summary": "Liệt kê các điểm đến sự kiện (không có bí mật)",
"responses": {
"200": {
"description": "Endpoint list",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"webhooks",
"requestId"
],
"properties": {
"webhooks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookEndpoint"
}
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}DELETE /webhooks/{id}
Xóa một điểm đến sự kiện
Yêu cầu phạm vi webhooks:manage và Idempotency-Key (lặp lại là an toàn).
Chi tiết gồm tham số, nội dung yêu cầu, phản hồi và tham chiếu thành phần. Định nghĩa tham chiếu ở dưới.
{
"tags": [
"webhooks"
],
"summary": "Xóa một điểm đến sự kiện",
"description": "Yêu cầu phạm vi `webhooks:manage` và Idempotency-Key (lặp lại là an toàn).",
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"responses": {
"204": {
"description": "Deleted",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}Định nghĩa chung
securitySchemes
productKey
{
"type": "http",
"scheme": "bearer",
"bearerFormat": "pk_v1_… (product key; NOT a Supabase key)"
}parameters
id
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}cursor
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string"
}
}limit
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
}idempotencyKey
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": "Cùng khóa + cùng phần thân đã chuẩn hóa phát lại kết quả đã ghi nhận; cùng khóa + phần thân khác trả về 409 idempotency_conflict.\n"
}headers
requestId
{
"description": "ID tương quan cho mỗi yêu cầu, cũng được phát lại trong các phong bì lỗi.",
"schema": {
"type": "string"
}
}retryAfter
{
"description": "Số giây cho đến cửa sổ giới hạn tốc độ tiếp theo.",
"schema": {
"type": "integer"
}
}responses
Forbidden
{
"description": "Khóa thiếu phạm vi bắt buộc, hoặc tài nguyên thuộc về không gian làm việc khác.",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}PaymentRequired
{
"description": "Vấn đề quyền lợi (đăng ký không hoạt động, dùng thử hết hạn, giới hạn tài khoản/chỗ/lưu trữ).",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}NotFound
{
"description": "Tài nguyên không tồn tại trong không gian làm việc của bên gọi.",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}Conflict
{
"description": "Xung đột phiên bản/idempotency/hủy/đồng ý/trạng thái gửi.",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}Validation
{
"description": "Phần thân yêu cầu hoặc nội dung điểm đến thất bại khi xác thực.",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}RateLimited
{
"description": "Giới hạn tốc độ kỹ thuật theo không gian làm việc. Chỉ kiểm soát tốc độ: không bao giờ là hạn mức đăng bài.",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
},
"Retry-After": {
"$ref": "#/components/headers/retryAfter"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}ServerError
{
"description": "5XX an toàn (nhà cung cấp không khả dụng hoặc lỗi nội bộ bất ngờ). Không bao giờ chứa chẩn đoán thô.",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}schemas
Error
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"requestId"
],
"properties": {
"code": {
"type": "string",
"enum": [
"unauthenticated",
"forbidden_scope",
"account_not_allowed",
"account_limit",
"seat_limit",
"storage_limit",
"subscription_inactive",
"trial_expired",
"validation_failed",
"unsupported_format",
"consent_required",
"reconnect_required",
"destination_identity_changed",
"revision_conflict",
"idempotency_conflict",
"too_late_to_cancel",
"media_expired",
"media_deleting",
"rate_limited",
"provider_unavailable",
"submission_unknown",
"destination_conflict",
"not_found",
"internal_error"
]
},
"message": {
"type": "string"
},
"fieldErrors": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"code",
"message"
],
"properties": {
"field": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
},
"destinationErrors": {
"type": "array",
"items": {
"type": "object",
"required": [
"accountId",
"code",
"message"
],
"properties": {
"accountId": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
},
"retryable": {
"type": "boolean"
},
"retryAfterSeconds": {
"type": "integer"
},
"details": {
"type": "object",
"additionalProperties": true,
"description": "Machine-readable extras, e.g. currentVersion for revision_conflict."
},
"requestId": {
"type": "string"
},
"requiresAction": {
"type": "object",
"description": "Session UI handoff for human consent; never contains credentials or grants access.",
"required": [
"type",
"url",
"accountIds"
],
"properties": {
"type": {
"type": "string",
"const": "human_consent"
},
"url": {
"type": "string",
"format": "uri-reference"
},
"accountIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Verified key workspace; the browser must verify membership before switching its selected workspace."
}
}
}
}
}
}
}Account
{
"type": "object",
"required": [
"id",
"network",
"destinationType",
"displayName",
"connectionState"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"network": {
"type": "string",
"example": "instagram"
},
"destinationType": {
"type": "string",
"example": "professional_account"
},
"displayName": {
"type": "string"
},
"connectionState": {
"type": "string",
"example": "connected"
},
"capabilityVersion": {
"type": [
"string",
"null"
]
}
}
}Capability
{
"type": "object",
"required": [
"accountId",
"network"
],
"properties": {
"accountId": {
"type": "string"
},
"network": {
"type": "string"
},
"networkEnabled": {
"type": "boolean"
},
"accountConnected": {
"type": "boolean"
},
"capabilityVersion": {
"type": [
"string",
"null"
]
},
"formats": {
"type": "array",
"items": {
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"text",
"single_image",
"image_set",
"video"
]
},
"maxMediaCount": {
"type": "integer"
},
"maxBytes": {
"type": [
"integer",
"null"
]
},
"requiredFields": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"eligibleVisibility": {
"type": "array",
"items": {
"type": "string"
}
},
"requiresActionReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"verifiedAt": {
"type": "string"
}
}
}UploadIntentRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"filename",
"declaredMime",
"declaredBytes"
],
"properties": {
"filename": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"declaredMime": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "image/jpeg"
},
"declaredBytes": {
"type": "integer",
"minimum": 1,
"maximum": 524288000
},
"width": {
"type": "number",
"minimum": 0
},
"height": {
"type": "number",
"minimum": 0
},
"durationMs": {
"type": "number",
"minimum": 0
}
}
}UploadIntent
{
"type": "object",
"required": [
"assetId",
"sessionId",
"objectKey",
"method",
"expiresAt",
"maxBytes"
],
"description": "Tệp dưới 50 MB trả về `method: presigned_put` với `uploadUrl` tồn tại ngắn hạn và các `headers` bắt buộc. Tệp từ 50 MB trở lên trả về `method: multipart_initiated` với `partSizeBytes` và một mảng `parts` các URL phần đã pre-sign; tải lên từng phần, sau đó hoàn tất với biên nhận ETag cho mọi phần.\n",
"properties": {
"assetId": {
"type": "string",
"format": "uuid"
},
"sessionId": {
"type": "string"
},
"objectKey": {
"type": "string",
"description": "Opaque storage key; never a public URL"
},
"method": {
"type": "string",
"enum": [
"presigned_put",
"multipart_initiated"
]
},
"uploadUrl": {
"type": "string",
"description": "Short-lived; upload bytes directly with the documented method"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Required request headers for the presigned PUT (e.g. content-type)"
},
"partSizeBytes": {
"type": "integer",
"description": "Required part size for multipart uploads"
},
"parts": {
"type": "array",
"description": "Presigned part URLs (multipart_initiated only); request fresh pages when they expire",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"partNumber",
"url",
"expiresAt"
],
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"expiresAt": {
"type": "string"
}
}
}
},
"expiresAt": {
"type": "string"
},
"maxBytes": {
"type": "integer"
}
}
}UploadIntentResponse
{
"allOf": [
{
"$ref": "#/components/schemas/UploadIntent"
},
{
"type": "object",
"required": [
"requestId"
],
"properties": {
"requestId": {
"type": "string"
}
}
}
]
}TikTokCreatorSettings
{
"type": "object",
"additionalProperties": false,
"required": [
"privacyLevels",
"maxDurationSeconds",
"allowComments",
"allowDuet",
"allowStitch",
"directPublishingAllowed",
"inboxAllowed",
"nativeAccountId"
],
"properties": {
"privacyLevels": {
"type": "array",
"items": {
"type": "string",
"enum": [
"PUBLIC_TO_EVERYONE",
"MUTUAL_FOLLOW_FRIENDS",
"FOLLOWER_OF_CREATOR",
"SELF_ONLY"
]
}
},
"maxDurationSeconds": {
"type": "number",
"exclusiveMinimum": 0
},
"allowComments": {
"type": "boolean"
},
"allowDuet": {
"type": "boolean"
},
"allowStitch": {
"type": "boolean"
},
"directPublishingAllowed": {
"type": "boolean"
},
"inboxAllowed": {
"type": "boolean"
},
"nativeAccountId": {
"type": "string"
},
"creatorName": {
"type": "string"
},
"creatorAvatarUrl": {
"type": "string",
"format": "uri"
}
}
}MediaStatus
{
"type": "object",
"required": [
"id",
"originalName",
"mimeType",
"bytes",
"uploadState",
"createdAt",
"deletionState"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"originalName": {
"type": "string"
},
"mimeType": {
"type": "string"
},
"bytes": {
"type": "integer"
},
"uploadState": {
"type": "string",
"enum": [
"pending",
"uploading",
"finalized",
"rejected"
]
},
"createdAt": {
"type": "string"
},
"deleteAfter": {
"type": [
"string",
"null"
],
"description": "Dynamic deletion date, or null while kept for scheduled posts."
},
"deletionState": {
"type": "string",
"enum": [
"active",
"deleting",
"deleted"
]
}
}
}FinalizeRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"sessionId"
],
"description": "Các sự thật quan sát do bên gọi khẳng định (byte/MIME/checksum) KHÔNG được chấp nhận: máy chủ tự kiểm tra bản sao FINAL bất biến. Các lần tải lên multipart phải bao gồm biên nhận ETag cho mọi phần.\n",
"properties": {
"sessionId": {
"type": "string",
"format": "uuid"
},
"multipart": {
"type": "object",
"additionalProperties": false,
"required": [
"parts"
],
"properties": {
"parts": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"partNumber",
"etag"
],
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"etag": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
}
}
}
}
}
}
}FinalizeResult
{
"type": "object",
"required": [
"assetId",
"finalizeOperationId",
"bytes"
],
"properties": {
"assetId": {
"type": "string",
"format": "uuid"
},
"finalizeOperationId": {
"type": "string"
},
"bytes": {
"type": "integer"
},
"expiresAt": {
"type": [
"string",
"null"
]
}
}
}DraftInput
{
"type": "object",
"additionalProperties": false,
"required": [
"caption",
"destinations"
],
"properties": {
"caption": {
"type": "string",
"maxLength": 70000
},
"mediaIds": {
"type": "array",
"maxItems": 10,
"items": {
"type": "string",
"format": "uuid"
},
"default": []
},
"brandFolderId": {
"type": [
"string",
"null"
],
"format": "uuid",
"default": null
},
"destinations": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"$ref": "#/components/schemas/DraftDestination"
}
}
}
}DraftDestination
{
"type": "object",
"additionalProperties": false,
"required": [
"accountId",
"format"
],
"properties": {
"accountId": {
"type": "string",
"format": "uuid"
},
"format": {
"type": "string",
"enum": [
"text",
"single_image",
"image_set",
"video"
]
},
"overrides": {
"type": "object",
"additionalProperties": false,
"properties": {
"caption": {
"type": "string"
},
"mediaIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"title": {
"type": "string"
},
"options": {
"type": "object",
"additionalProperties": true,
"description": "Validated against an allowlisted per-network schema; never a raw vendor bag."
}
}
}
}
}DraftUpdateInput
{
"allOf": [
{
"$ref": "#/components/schemas/DraftInput"
},
{
"type": "object",
"required": [
"expectedVersion"
],
"properties": {
"expectedVersion": {
"type": "integer",
"minimum": 1
}
}
}
]
}DraftSaveResult
{
"type": "object",
"required": [
"postId",
"version",
"createdAt",
"updatedAt"
],
"properties": {
"postId": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "integer"
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
}
}
}PostListItem
{
"type": "object",
"required": [
"postId",
"version",
"status",
"updatedAt"
],
"properties": {
"postId": {
"type": "string"
},
"version": {
"type": "integer"
},
"status": {
"type": "string"
},
"updatedAt": {
"type": "string"
}
}
}ValidationResult
{
"type": "object",
"required": [
"valid",
"revisionVersion",
"destinationResults"
],
"properties": {
"valid": {
"type": "boolean"
},
"revisionVersion": {
"type": "integer"
},
"destinationResults": {
"type": "array",
"items": {
"type": "object",
"required": [
"accountId",
"valid",
"requiresAction"
],
"properties": {
"accountId": {
"type": "string"
},
"valid": {
"type": "boolean"
},
"requiresAction": {
"type": "boolean",
"description": "True when the network requires an explicit human/consent step."
},
"errors": {
"type": "array",
"items": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"field": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
}
}
}
}AcceptedOperation
{
"type": "object",
"required": [
"revisionId",
"version",
"operationId",
"deliveryIds",
"scheduledAt",
"timezone",
"requestId"
],
"properties": {
"revisionId": {
"type": "string"
},
"version": {
"type": "integer"
},
"operationId": {
"type": "string"
},
"deliveryIds": {
"type": "array",
"items": {
"type": "string"
}
},
"scheduledAt": {
"type": "string"
},
"timezone": {
"type": "string"
},
"requestId": {
"type": "string"
},
"warnings": {
"type": "array",
"description": "Non-blocking notices preserved on replay, including key_expires_before_schedule when a key expires at or before dispatch.",
"items": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"field": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
}ScheduleRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"scheduledAt",
"timezone",
"expectedVersion"
],
"properties": {
"scheduledAt": {
"type": "string",
"format": "date-time",
"example": "2027-01-12T15:00:00Z"
},
"timezone": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"example": "America/Indiana/Indianapolis"
},
"expectedVersion": {
"type": "integer",
"minimum": 1
},
"revisionId": {
"type": [
"string",
"null"
],
"description": "Must be null in V1 (schedules the current revision); non-null is rejected."
}
}
}PostStatus
{
"type": "object",
"required": [
"postId",
"version",
"status",
"deliveries"
],
"properties": {
"postId": {
"type": "string"
},
"version": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"draft",
"scheduled",
"in_progress",
"published",
"partially_published",
"needs_attention",
"canceled"
]
},
"deliveries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"accountId": {
"type": "string"
},
"network": {
"type": "string"
},
"state": {
"type": "string"
},
"dueAt": {
"type": "string"
},
"nativePostUrl": {
"type": [
"string",
"null"
],
"description": "Only after a confirmed result."
},
"unresolvedExternalOutcome": {
"type": "boolean"
},
"cancelRequestedAt": {
"type": [
"string",
"null"
]
},
"retryCount": {
"type": "integer"
},
"publishedAt": {
"type": [
"string",
"null"
]
}
}
}
}
}
}Usage
{
"type": "object",
"description": "Không có bộ đếm bài đăng còn lại ở bất kỳ đâu trong schema này: đăng bài không giới hạn trên mọi gói trả phí. Các con số hoạt động là chỉ số vận hành.\n",
"required": [
"plan",
"accounts",
"members",
"storage",
"scheduling",
"rateLimit",
"activity"
],
"properties": {
"plan": {
"type": "object",
"required": [
"id",
"label",
"status"
],
"properties": {
"id": {
"type": "string",
"enum": [
"trial",
"creator",
"studio",
"operator"
]
},
"label": {
"type": "string"
},
"version": {
"type": "integer"
},
"interval": {
"type": [
"string",
"null"
],
"enum": [
"month",
"year",
null
]
},
"status": {
"type": "string"
},
"paidThrough": {
"type": [
"string",
"null"
]
},
"trialEndsAt": {
"type": [
"string",
"null"
]
}
}
},
"accounts": {
"type": "object",
"required": [
"connected",
"reserved",
"maxConnected"
],
"properties": {
"connected": {
"type": "integer"
},
"reserved": {
"type": "integer"
},
"maxConnected": {
"type": "integer"
}
}
},
"members": {
"type": "object",
"required": [
"active",
"max"
],
"properties": {
"active": {
"type": "integer"
},
"max": {
"type": "integer"
}
}
},
"storage": {
"type": "object",
"required": [
"activeBytes",
"reservedBytes",
"maxActiveBytes"
],
"properties": {
"activeBytes": {
"type": "integer"
},
"reservedBytes": {
"type": "integer"
},
"maxActiveBytes": {
"type": "integer"
}
}
},
"scheduling": {
"type": "object",
"required": [
"horizonDays"
],
"properties": {
"horizonDays": {
"type": "integer",
"example": 90
}
}
},
"rateLimit": {
"type": "object",
"required": [
"requestsPerMinute",
"note"
],
"properties": {
"requestsPerMinute": {
"type": "integer",
"example": 120
},
"note": {
"type": "string",
"example": "Technical speed limit: not a posting allowance."
}
}
},
"activity": {
"type": "object",
"description": "Operational metrics only; never an allowance or balance.",
"required": [
"deliveriesAttemptedLast30Days",
"deliveriesPublishedLast30Days"
],
"properties": {
"deliveriesAttemptedLast30Days": {
"type": "integer"
},
"deliveriesPublishedLast30Days": {
"type": "integer"
}
}
}
}
}CreateWebhookRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"example": "https://example.com/hooks/autoposted"
},
"eventTypes": {
"oneOf": [
{
"type": "string",
"const": "all"
},
{
"type": "array",
"minItems": 1,
"items": {
"type": "string"
}
}
],
"description": "Omit or \"all\" for every event; an array filters by event type."
},
"description": {
"type": "string"
}
}
}WebhookEndpoint
{
"type": "object",
"required": [
"id",
"url",
"eventTypes",
"enabled",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"url": {
"type": "string",
"format": "uri"
},
"eventTypes": {
"oneOf": [
{
"type": "string",
"const": "all"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"enabled": {
"type": "boolean"
},
"verifiedAt": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string"
}
}
}