AiVideoEditor
ابدأ مجانًا
القائمة

مرجع API

إصدار API 2026-11-09 · تنزيل OpenAPI 3.1 YAML

تستخدم المصادقة مفتاح منتج محددًا بنطاق مساحة العمل: Authorization: Bearer pk_v1_…. تحمل المفاتيح نطاقات صريحة وقائمة سماح اختيارية للحسابات؛ ولا يمكنها أبدًا إنشاء مفاتيح أخرى أو تغيير الفوترة. تتطلب كل عمليات التغيير ترويسة Idempotency-Key؛ وتتطلب التحريرات والجدولة أيضًا expectedVersion. يعيد النشر والجدولة 202 Accepted مع معرّف تسليم واحد لكل وجهة: 202 ليست أبدًا ادعاءً بنشر أي شيء. تحقق من النتائج عبر GET /posts/{id} أو خطافات الويب للعملاء أو استقصاء محدود مع تراجع. تستخدم الأخطاء الغلاف الموحد من العقد v1: code وmessage الآمنة وfieldErrors وdestinationErrors وretryable وretryAfterSeconds وrequestId. لا يوجد عمدًا رمز خطأ لرصيد نشر أو حصة.

المصادقة

أرسل مفتاح منتج مساحة عمل بالصيغة "Authorization: Bearer pk_v1_…". تدرج كل عملية نطاقاتها المطلوبة. راجع المصادقة والأذونات.

GET /capabilities

التنسيقات والخيارات المؤهلة للوجهات المسموح بها

يتطلب النطاق accounts:read.

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "accounts"
  ],
  "summary": "التنسيقات والخيارات المؤهلة للوجهات المسموح بها",
  "description": "يتطلب النطاق `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

عرض حسابات الوجهات المرئية لهذا المفتاح

يحترم قائمة سماح الحسابات للمفتاح. يتطلب النطاق accounts:read.

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "accounts"
  ],
  "summary": "عرض حسابات الوجهات المرئية لهذا المفتاح",
  "description": "يحترم قائمة سماح الحسابات للمفتاح. يتطلب النطاق `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

قراءة إعدادات منشئ TikTok المتحقق منها لحساب مرتبط مسموح به

يتطلب accounts:read وقائمة سماح الحسابات للمفتاح. هذه القراءة لا توفر أبدًا موافقة النشر البشرية.

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "accounts"
  ],
  "summary": "قراءة إعدادات منشئ TikTok المتحقق منها لحساب مرتبط مسموح به",
  "description": "يتطلب accounts:read وقائمة سماح الحسابات للمفتاح. هذه القراءة لا توفر أبدًا موافقة النشر البشرية.",
  "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

حجز البايتات وإرجاع تعليمات التحميل المباشر

يتطلب النطاق media:write بالإضافة إلى مفتاح Idempotency-Key. تُرفع البايتات مباشرةً إلى تخزين كائنات خاص باستخدام التعليمات المُعادة؛ ولا تمر أبدًا عبر هذه الواجهة. لا يوجد عنوان URL عام دائم للوسائط.

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "media"
  ],
  "summary": "حجز البايتات وإرجاع تعليمات التحميل المباشر",
  "description": "يتطلب النطاق `media:write` بالإضافة إلى مفتاح Idempotency-Key. تُرفع البايتات مباشرةً إلى تخزين كائنات خاص باستخدام التعليمات المُعادة؛ ولا تمر أبدًا عبر هذه الواجهة. لا يوجد عنوان URL عام دائم للوسائط.\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}

حالة الوسائط وانتهاء صلاحيتها (لا عنوان URL عام دائم)

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "media"
  ],
  "summary": "حالة الوسائط وانتهاء صلاحيتها (لا عنوان URL عام دائم)",
  "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

تحديث من واحد إلى 64 عنوان PUT متعدد الأجزاء في جلسة تحميل موجودة

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "media"
  ],
  "summary": "تحديث من واحد إلى 64 عنوان PUT متعدد الأجزاء في جلسة تحميل موجودة",
  "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

التخلي عن تحميل غير مكتمل وتحرير حجزته في التخزين

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "media"
  ],
  "summary": "التخلي عن تحميل غير مكتمل وتحرير حجزته في التخزين",
  "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

التحقق من الكائن المرفوع وجعله قابلًا للاستخدام

يتطلب النطاق media:write بالإضافة إلى مفتاح Idempotency-Key. يتحقق الخادم من الحجم/MIME والتوقيعات المحدودة مقابل النسخة النهائية غير القابلة للتغيير؛ وتستقر حجوزات البايتات مرة واحدة بالضبط. أرسل هوية الجلسة فقط (مع إيصالات أجزاء multipart عند الانطباق): يراقب الخادم كل البيانات الوصفية بنفسه.

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "media"
  ],
  "summary": "التحقق من الكائن المرفوع وجعله قابلًا للاستخدام",
  "description": "يتطلب النطاق `media:write` بالإضافة إلى مفتاح Idempotency-Key. يتحقق الخادم من الحجم/MIME والتوقيعات المحدودة مقابل النسخة النهائية غير القابلة للتغيير؛ وتستقر حجوزات البايتات مرة واحدة بالضبط. أرسل هوية الجلسة فقط (مع إيصالات أجزاء multipart عند الانطباق): يراقب الخادم كل البيانات الوصفية بنفسه.\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

إنشاء مسودة

يتطلب النطاق posts:write بالإضافة إلى مفتاح Idempotency-Key. تُحلَّل الأجسام بمخطط DraftInputSchema الصارم للعقد v1؛ وتُرفض حسابات الوجهات المكررة. الحفظ متسامح: تحقق قبل النشر.

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "posts"
  ],
  "summary": "إنشاء مسودة",
  "description": "يتطلب النطاق `posts:write` بالإضافة إلى مفتاح Idempotency-Key. تُحلَّل الأجسام بمخطط DraftInputSchema الصارم للعقد v1؛ وتُرفض حسابات الوجهات المكررة. الحفظ متسامح: تحقق قبل النشر.\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

عرض المنشورات

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "posts"
  ],
  "summary": "عرض المنشورات",
  "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}

حالة المنشور الإجمالية ولكل وجهة

"المقبول من المزود" ليس "منشورًا". تظهر الروابط الأصلية فقط بعد إيصال مؤكد؛ وغياب الرابط الدائم ليس إثباتًا للفشل.

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "posts"
  ],
  "summary": "حالة المنشور الإجمالية ولكل وجهة",
  "description": "\"المقبول من المزود\" ليس \"منشورًا\". تظهر الروابط الأصلية فقط بعد إيصال مؤكد؛ وغياب الرابط الدائم ليس إثباتًا للفشل.\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}

تحرير مسودة (مع فحص الإصدار)

يتطلب Idempotency-Key وexpectedVersion. يعيد الإصدار القديم 409 revision_conflict مع الإصدار الحالي في error.details.currentVersion.

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "posts"
  ],
  "summary": "تحرير مسودة (مع فحص الإصدار)",
  "description": "يتطلب Idempotency-Key وexpectedVersion. يعيد الإصدار القديم 409 revision_conflict مع الإصدار الحالي في `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

تحقق مهيكل لكل وجهة (غير مُغيِّر)

يعيد 200 مع validation.valid=false عندما تكون لدى الوجهات مشكلات (أبدًا حالة خطأ لمشكلات المحتوى).

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "posts"
  ],
  "summary": "تحقق مهيكل لكل وجهة (غير مُغيِّر)",
  "description": "يعيد 200 مع `validation.valid=false` عندما تكون لدى الوجهات مشكلات (أبدًا حالة خطأ لمشكلات المحتوى).\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

النشر الآن (202)

يتطلب النطاق posts:publish بالإضافة إلى مفتاح Idempotency-Key. تطبق expectedVersion الاختيارية ضمان التزامن التفاؤلي نفسه المطبق في التحرير. يعيد معرّف تسليم واحد لكل وجهة؛ ولا يدّعي النشر أبدًا.

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "posts"
  ],
  "summary": "النشر الآن (202)",
  "description": "يتطلب النطاق `posts:publish` بالإضافة إلى مفتاح Idempotency-Key. تطبق `expectedVersion` الاختيارية ضمان التزامن التفاؤلي نفسه المطبق في التحرير. يعيد معرّف تسليم واحد لكل وجهة؛ ولا يدّعي النشر أبدًا.\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

جدولة الإصدار المجمّد (202)

يتطلب النطاق posts:publish بالإضافة إلى Idempotency-Key وexpectedVersion. لحظة واحدة للدفعة كاملة؛ يجب أن تكون مستقبلية وضمن أفق 90 يومًا (يفرضها الخدمة المشتركة). يجب أن يكون revisionId بقيمة null في V1: اختيار إصدار اعتباطي غير مدعوم ويُرفض.

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "posts"
  ],
  "summary": "جدولة الإصدار المجمّد (202)",
  "description": "يتطلب النطاق `posts:publish` بالإضافة إلى Idempotency-Key وexpectedVersion. لحظة واحدة للدفعة كاملة؛ يجب أن تكون مستقبلية وضمن أفق 90 يومًا (يفرضها الخدمة المشتركة). يجب أن يكون `revisionId` بقيمة null في V1: اختيار إصدار اعتباطي غير مدعوم ويُرفض.\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

إلغاء مهمة وجهة واحدة ما دامت غير مطالب به بأمان

يتطلب النطاق posts:publish بالإضافة إلى Idempotency-Key. تعيد عمليات التسليم المرسلة سابقًا 409 too_late_to_cancel مع الحالة الحقيقية.

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "deliveries"
  ],
  "summary": "إلغاء مهمة وجهة واحدة ما دامت غير مطالب به بأمان",
  "description": "يتطلب النطاق `posts:publish` بالإضافة إلى Idempotency-Key. تعيد عمليات التسليم المرسلة سابقًا 409 too_late_to_cancel مع الحالة الحقيقية.\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

إعادة محاولة وجهة فاشلة معروفة واحدة

يتطلب النطاق posts:publish بالإضافة إلى Idempotency-Key. تُرفض النتائج المجهولة أو عمليات التسليم الناجحة: إعادة المحاولة قد تكرر المنشور.

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "deliveries"
  ],
  "summary": "إعادة محاولة وجهة فاشلة معروفة واحدة",
  "description": "يتطلب النطاق `posts:publish` بالإضافة إلى Idempotency-Key. تُرفض النتائج المجهولة أو عمليات التسليم الناجحة: إعادة المحاولة قد تكرر المنشور.\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

الخطة واستخدام الحسابات/المقاعد/التخزين والنشاط ومعلومات المعدل

يتطلب النطاق usage:read. لا يحتوي على أي عدّاد منشورات متبقية من أي نوع: النشر غير محدود في كل خطة مدفوعة.

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "usage"
  ],
  "summary": "الخطة واستخدام الحسابات/المقاعد/التخزين والنشاط ومعلومات المعدل",
  "description": "يتطلب النطاق `usage:read`. لا يحتوي على أي عدّاد منشورات متبقية من أي نوع: النشر غير محدود في كل خطة مدفوعة.\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

تسجيل وجهة أحداث للعميل

يتطلب النطاق webhooks:manage بالإضافة إلى مفتاح Idempotency-Key. بروتوكول HTTPS فقط؛ يجري تحقق SSRF (المخطط، بيانات الاعتماد، العنوان المُحلول عبر DNS ضمن حدود) قبل التخزين. يُعاد سر التوقيع في أول استجابة إنشاء فقط: تعيد إعادة التشغيل الاصطناعية نقطة النهاية دون السر. يدرج الإنشاء أيضًا حدث تحقق موجّهًا.

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "webhooks"
  ],
  "summary": "تسجيل وجهة أحداث للعميل",
  "description": "يتطلب النطاق `webhooks:manage` بالإضافة إلى مفتاح Idempotency-Key. بروتوكول HTTPS فقط؛ يجري تحقق SSRF (المخطط، بيانات الاعتماد، العنوان المُحلول عبر DNS ضمن حدود) قبل التخزين. يُعاد سر التوقيع في أول استجابة إنشاء فقط: تعيد إعادة التشغيل الاصطناعية نقطة النهاية دون السر. يدرج الإنشاء أيضًا حدث تحقق موجّهًا.\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

عرض وجهات الأحداث (بلا أسرار)

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "webhooks"
  ],
  "summary": "عرض وجهات الأحداث (بلا أسرار)",
  "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}

إزالة وجهة أحداث

يتطلب النطاق webhooks:manage ومفتاح Idempotency-Key (التكرار آمن).

تشمل تفاصيل العمليات المعلمات وأجسام الطلبات والاستجابات ومراجع المكونات. تظهر التعريفات المشار إليها أدناه.

{
  "tags": [
    "webhooks"
  ],
  "summary": "إزالة وجهة أحداث",
  "description": "يتطلب النطاق `webhooks:manage` ومفتاح Idempotency-Key (التكرار آمن).",
  "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"
    }
  }
}

تعريفات مشتركة

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": "المفتاح نفسه + الجسم الموحد نفسه يعيد تشغيل النتيجة المسجلة؛ والمفتاح نفسه + جسم مختلف يعيد 409 idempotency_conflict.\n"
}

headers

requestId
{
  "description": "معرّف ارتباط لكل طلب، يُعاد إظهاره أيضًا في أغلفة الأخطاء.",
  "schema": {
    "type": "string"
  }
}
retryAfter
{
  "description": "الثواني حتى نافذة حد المعدل التالية.",
  "schema": {
    "type": "integer"
  }
}

responses

Unauthorized
{
  "description": "مفتاح منتج غائب أو مشوَّه أو مجهول أو منتهي الصلاحية أو مُلغى.",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
Forbidden
{
  "description": "يفتقر المفتاح إلى النطاق المطلوب، أو ينتمي المورد إلى مساحة عمل أخرى.",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
PaymentRequired
{
  "description": "مشكلة استحقاق (اشتراك غير نشط، تجربة منتهية، حد حساب/مقاعد/تخزين).",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
NotFound
{
  "description": "المورد غير موجود في مساحة عمل المستدعي.",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
Conflict
{
  "description": "تعارض إصدار/idempotency/إلغاء/موافقة/حالة تسليم.",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
Validation
{
  "description": "فشل جسم الطلب أو محتوى الوجهة في التحقق.",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
RateLimited
{
  "description": "حد معدل تقني لكل مساحة عمل. تحكم بالسرعة فقط: أبدًا حصة نشر.",
  "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 آمن (المزود غير متاح أو خطأ داخلي غير متوقع). لا يحتوي أبدًا على تشخيصات خام.",
  "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": "تعيد الملفات الأصغر من 50 MB `method: presigned_put` مع `uploadUrl` قصير العمر و`headers` المطلوبة. تعيد الملفات بحجم 50 MB أو أكثر `method: multipart_initiated` مع `partSizeBytes` ومصفوفة `parts` من عناوين URL للأجزاء المسبقة التوقيع؛ ارفع كل جزء، ثم أنهِ بإيصال ETag لكل جزء.\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": "لا تُقبل الحقائق الملاحَظة الموثوقة من المستدعي (البايتات/MIME/المجموع الاختباري): يفحص الخادم النسخة النهائية غير القابلة للتغيير بنفسه. يجب أن تتضمن تحميلات multipart إيصال ETag لكل جزء.\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": "لا يوجد عدّاد منشورات متبقية في أي مكان في هذا المخطط: النشر غير محدود في كل خطة مدفوعة. أرقام النشاط مقاييس تشغيلية.\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"
    }
  }
}