{"openapi":"3.1.0","info":{"title":"UttaPost API","version":"1.0.0","description":"API عمومی یوتاپست برای n8n و ابزارهای دیگر. احراز هویت با کلید Bearer (up_live_…). ساختار پاسخ: {data, message}؛ خطا: {message, code}. مبلغ‌ها همه تومان‌اند. نسخهٔ v1 پایدار است؛ تغییر ناسازگار فقط با /api/v2."},"servers":[{"url":"https://uttapost.ir/api/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"پایه"},{"name":"کتابخانه"},{"name":"پیش‌نویس"},{"name":"هزینه"},{"name":"پست"},{"name":"پول"},{"name":"زمان‌بندی"},{"name":"وب‌هوک"},{"name":"مستندات"}],"paths":{"/openapi.json":{"get":{"summary":"این سند (OpenAPI 3.1)","operationId":"openapi","tags":["مستندات"],"security":[],"responses":{"200":{"description":"سند OpenAPI","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/me":{"get":{"summary":"برند و کلید جاری","operationId":"me","tags":["پایه"],"x-required-scope":"read","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"برند، scopeها، سقف‌ها و خرج امروز","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Me"},"message":{"type":["string","null"]}}}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/items":{"get":{"summary":"فهرست آیتم‌های کتابخانه","operationId":"items.index","tags":["کتابخانه"],"x-required-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"state","in":"query","schema":{"enum":["active","archived","pinned","excluded"]}}],"responses":{"200":{"description":"آیتم‌ها و صفحه‌بندی","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ItemPage"},"message":{"type":["string","null"]}}}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"افزودن آیتم","operationId":"items.store","tags":["کتابخانه"],"x-required-scope":"draft","security":[{"bearerAuth":[]}],"description":"نیاز به scope «draft» و پلن یا اعتبار.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemInput"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ItemInput"}}}},"responses":{"201":{"description":"آیتم ساخته شد","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Item"},"message":{"type":["string","null"]}}}}}},"422":{"description":"داده نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/items/{id}":{"get":{"summary":"یک آیتم","operationId":"items.show","tags":["کتابخانه"],"x-required-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"آیتم","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Item"},"message":{"type":["string","null"]}}}}}},"404":{"description":"پیدا نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/kb":{"get":{"summary":"دانش برند","operationId":"kb","tags":["کتابخانه"],"x-required-scope":"read","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"آنچه هوش مصنوعی دربارهٔ کسب‌وکار می‌داند","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"message":{"type":["string","null"]}}}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/drafts":{"get":{"summary":"فهرست پیش‌نویس‌ها","operationId":"drafts.index","tags":["پیش‌نویس"],"x-required-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"tab","in":"query","schema":{"enum":["review","scheduled","rejected"]}}],"responses":{"200":{"description":"پیش‌نویس‌ها و شمارش تب‌ها","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tab":{"type":"string"},"counts":{"type":"object"},"drafts":{"type":"array","items":{"$ref":"#/components/schemas/Draft"}}}},"message":{"type":["string","null"]}}}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/drafts/generate":{"post":{"summary":"پیش‌نمایش ساخت پیش‌نویس (بدون هزینه)","operationId":"drafts.generate","tags":["پیش‌نویس"],"x-required-scope":"draft","security":[{"bearerAuth":[]}],"description":"هیچ هزینه‌ای کم نمی‌شود؛ هزینه با POST /confirm و confirm_token گرفته می‌شود.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"item_ids":{"type":"array","items":{"type":"integer"},"minItems":1,"maxItems":10},"format":{"enum":["post","carousel"]},"aspect":{"enum":["1:1","4:5"]}},"required":["item_ids"]}}}},"responses":{"202":{"description":"پیش‌نمایش و confirm_token","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Preview"},"message":{"type":["string","null"]}}}}}},"422":{"description":"آیتم نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/drafts/{id}":{"get":{"summary":"یک پیش‌نویس","operationId":"drafts.show","tags":["پیش‌نویس"],"x-required-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"پیش‌نویس","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Draft"},"message":{"type":["string","null"]}}}}}},"404":{"description":"پیدا نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/drafts/{id}/approve":{"post":{"summary":"تأیید و انتشار","operationId":"drafts.approve","tags":["پیش‌نویس"],"x-required-scope":"publish","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel_ids":{"type":"array","items":{"type":"integer"}},"caption":{"type":"string","maxLength":2200}},"required":["channel_ids"]}}}},"responses":{"200":{"description":"تأیید شد","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Draft"},"message":{"type":["string","null"]}}}}}},"422":{"description":"قابل تأیید نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/drafts/{id}/schedule":{"post":{"summary":"تأیید و زمان‌بندی","operationId":"drafts.schedule","tags":["پیش‌نویس"],"x-required-scope":"publish","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel_ids":{"type":"array","items":{"type":"integer"}},"scheduled_at":{"type":"string","format":"date-time"},"caption":{"type":"string","maxLength":2200}},"required":["channel_ids","scheduled_at"]}}}},"responses":{"200":{"description":"زمان‌بندی شد","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Draft"},"message":{"type":["string","null"]}}}}}},"422":{"description":"قابل زمان‌بندی نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/drafts/{id}/reject":{"post":{"summary":"رد پیش‌نویس","operationId":"drafts.reject","tags":["پیش‌نویس"],"x-required-scope":"draft","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"رد شد","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Draft"},"message":{"type":["string","null"]}}}}}},"422":{"description":"قابل رد نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/confirm":{"post":{"summary":"تأیید یک هزینه (یک‌بار مصرف)","operationId":"confirm","tags":["هزینه"],"x-required-scope":"draft","security":[{"bearerAuth":[]}],"description":"token باید از همان کلیدی باشد که پیش‌نمایش را گرفته.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm_token":{"type":"string"}},"required":["confirm_token"]}}}},"responses":{"200":{"description":"انجام شد","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConfirmResult"},"message":{"type":["string","null"]}}}}}},"402":{"description":"سقف روزانهٔ کلید یا اعتبار کیف پول","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"کارت پیدا نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"قبلاً استفاده شده یا کلید مشغول است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"مهلت ۳۰ دقیقه‌ای تمام شده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/posts":{"get":{"summary":"پست‌های منتشرشده و در جریان","operationId":"posts.index","tags":["پست"],"x-required-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"پست‌ها","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"message":{"type":["string","null"]}}}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/posts/stats":{"get":{"summary":"آمار پست‌ها","operationId":"posts.stats","tags":["پست"],"x-required-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":90}}],"responses":{"200":{"description":"شمارش وضعیت‌ها و شبکه‌ها","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PostStats"},"message":{"type":["string","null"]}}}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/wallet":{"get":{"summary":"اعتبار کیف پول","operationId":"wallet","tags":["پول"],"x-required-scope":"read","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"موجودی (تومان)، سه سطل اعتبار و تعرفه","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"message":{"type":["string","null"]}}}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/channels":{"get":{"summary":"کانال‌های وصل‌شده","operationId":"channels","tags":["برند"],"x-required-scope":"read","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"فهرست کانال‌ها (id، network، title، active)؛ id را به‌عنوان channel_ids در approve و schedule بدهید","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"message":{"type":["string","null"]}}}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rules":{"get":{"summary":"قانون‌های خودکار","operationId":"rules.index","tags":["زمان‌بندی"],"x-required-scope":"read","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"قانون‌ها","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"message":{"type":["string","null"]}}}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"get":{"summary":"وب‌هوک‌ها","operationId":"webhooks.index","tags":["وب‌هوک"],"x-required-scope":"read","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"فهرست و رویدادهای ممکن","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"events":{"type":"object"}}},"message":{"type":["string","null"]}}}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"ساخت وب‌هوک","operationId":"webhooks.store","tags":["وب‌هوک"],"x-required-scope":"publish","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"$ref":"#/components/schemas/EventName"}},"name":{"type":"string"}},"required":["url","events"]}}}},"responses":{"201":{"description":"ساخته شد؛ secret فقط همین‌جا","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"},"message":{"type":["string","null"]}}}}}},"422":{"description":"آدرس یا رویداد نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}":{"patch":{"summary":"ویرایش وب‌هوک","operationId":"webhooks.update","tags":["وب‌هوک"],"x-required-scope":"publish","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/EventName"}},"name":{"type":"string"},"active":{"type":"boolean"}},"required":[]}}}},"responses":{"200":{"description":"ذخیره شد","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"},"message":{"type":["string","null"]}}}}}},"404":{"description":"پیدا نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"حذف وب‌هوک","operationId":"webhooks.destroy","tags":["وب‌هوک"],"x-required-scope":"publish","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"حذف شد","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"message":{"type":["string","null"]}}}}}},"404":{"description":"پیدا نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/test":{"post":{"summary":"ping آزمایشی امضاشده","operationId":"webhooks.test","tags":["وب‌هوک"],"x-required-scope":"publish","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"نتیجهٔ ارسال","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"delivered":{"type":"boolean"},"response_code":{"type":["integer","null"]},"response_excerpt":{"type":["string","null"]}}},"message":{"type":["string","null"]}}}}}},"404":{"description":"پیدا نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/topics":{"get":{"summary":"موضوع‌های محتوای برند","operationId":"topics.index","tags":["پایه"],"x-required-scope":"read","security":[{"bearerAuth":[]}],"description":"موضوع‌هایی که پست‌های «مرتبط با کسب‌وکار» و ترکیب هفتگی از آن‌ها می‌سازند. فقط خواندنی.","parameters":[{"name":"status","in":"query","required":false,"schema":{"enum":["suggested","approved","rejected"]}}],"responses":{"200":{"description":"موضوع‌ها","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"topics":{"type":"array","items":{"type":"object"}},"counts":{"type":"object"},"niche":[]}},"message":{"type":["string","null"]}}}}}},"422":{"description":"وضعیت نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rules/mix":{"post":{"summary":"پیشنهاد ترکیب هفتگی محتوا (بدون ساخت)","operationId":"rules.mix","tags":["زمان‌بندی"],"x-required-scope":"publish","security":[{"bearerAuth":[]}],"description":"چیزی ساخته یا کم نمی‌شود؛ با POST /confirm و confirm_token ترکیب ساخته می‌شود. ریلز و ویدیو در ترکیب نیست.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"lines":{"type":"array","items":{"type":"object","properties":{"source":{"enum":["type","topic","general","auto","folder"]},"source_ref":{"type":"string"},"format":{"enum":["post","carousel","story"]},"per_week":{"type":"integer","minimum":1,"maximum":14}},"required":["source","per_week"]},"minItems":1,"maxItems":10},"weekdays":{"type":"array","items":{"type":"integer","minimum":1,"maximum":7}},"hour":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}},"required":["lines"]}}}},"responses":{"202":{"description":"پیش‌نمایش و confirm_token","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Preview"},"message":{"type":["string","null"]}}}}}},"422":{"description":"خط‌های نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/assistant/ask":{"post":{"summary":"یک پرسش از دستیار برند","operationId":"assistant.ask","tags":["پایه"],"x-required-scope":"draft","security":[{"bearerAuth":[]}],"description":"دستیار به‌جای سازندهٔ کلید و در برند همان کلید پاسخ می‌دهد و از سقف روزانهٔ دستیار کم می‌کند. اگر کاری پیشنهاد کند، card.confirm_token می‌آید و تا POST /confirm چیزی اجرا نمی‌شود.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","maxLength":2000},"new_thread":{"type":"boolean"}},"required":["text"]}}}},"responses":{"200":{"description":"پاسخ دستیار","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"kind":{"type":"string"},"text":{"type":"string"},"card":{"type":["object","null"]}}},"message":{"type":["string","null"]}}}}}},"422":{"description":"پیام نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"دستیار در دسترس نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید نامعتبر، باطل یا منقضی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"دسترسی کافی نیست (scope یا پلن)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"از سقف نرخ کلید بیشتر شد؛ هدر Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"draft.created":{"post":{"summary":"پیش‌نویس ساخته شد","description":"هدرها: X-UttaPost-Event، X-UttaPost-Delivery، X-UttaPost-Signature (t=…,v1=…). امضا روی t + «.» + بایت‌های خام بدنه است.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","event","created_at","brand","data"],"properties":{"id":{"type":"string"},"event":{"const":"draft.created"},"created_at":{"type":"string","format":"date-time"},"brand":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":["string","null"]}}},"data":{"type":"object","properties":{"draft":{"$ref":"#/components/schemas/WebhookDraft"},"via":{"type":"string"}}}}}}}},"responses":{"2XX":{"description":"هر پاسخ ۲xx یعنی دریافت شد"}}}},"approval.requested":{"post":{"summary":"پیش‌نویس منتظر تأیید است","description":"هدرها: X-UttaPost-Event، X-UttaPost-Delivery، X-UttaPost-Signature (t=…,v1=…). امضا روی t + «.» + بایت‌های خام بدنه است.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","event","created_at","brand","data"],"properties":{"id":{"type":"string"},"event":{"const":"approval.requested"},"created_at":{"type":"string","format":"date-time"},"brand":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":["string","null"]}}},"data":{"type":"object","properties":{"draft":{"$ref":"#/components/schemas/WebhookDraft"}}}}}}}},"responses":{"2XX":{"description":"هر پاسخ ۲xx یعنی دریافت شد"}}}},"post.published":{"post":{"summary":"پست منتشر شد","description":"هدرها: X-UttaPost-Event، X-UttaPost-Delivery، X-UttaPost-Signature (t=…,v1=…). امضا روی t + «.» + بایت‌های خام بدنه است.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","event","created_at","brand","data"],"properties":{"id":{"type":"string"},"event":{"const":"post.published"},"created_at":{"type":"string","format":"date-time"},"brand":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":["string","null"]}}},"data":{"type":"object","properties":{"post":{"$ref":"#/components/schemas/PostTarget"}}}}}}}},"responses":{"2XX":{"description":"هر پاسخ ۲xx یعنی دریافت شد"}}}},"post.failed":{"post":{"summary":"انتشار پست شکست خورد","description":"هدرها: X-UttaPost-Event، X-UttaPost-Delivery، X-UttaPost-Signature (t=…,v1=…). امضا روی t + «.» + بایت‌های خام بدنه است.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","event","created_at","brand","data"],"properties":{"id":{"type":"string"},"event":{"const":"post.failed"},"created_at":{"type":"string","format":"date-time"},"brand":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":["string","null"]}}},"data":{"type":"object","properties":{"post":{"allOf":[{"$ref":"#/components/schemas/PostTarget"},{"type":"object","properties":{"reason_code":{"type":"string"},"reason":{"type":"string"},"retryable":{"type":"boolean"}}}]}}}}}}}},"responses":{"2XX":{"description":"هر پاسخ ۲xx یعنی دریافت شد"}}}},"handoff.opened":{"post":{"summary":"گفتگو به شما سپرده شد","description":"هدرها: X-UttaPost-Event، X-UttaPost-Delivery، X-UttaPost-Signature (t=…,v1=…). امضا روی t + «.» + بایت‌های خام بدنه است.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","event","created_at","brand","data"],"properties":{"id":{"type":"string"},"event":{"const":"handoff.opened"},"created_at":{"type":"string","format":"date-time"},"brand":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":["string","null"]}}},"data":{"type":"object","properties":{"handoff":{"type":"object","properties":{"id":{"type":"integer"},"source":{"type":"string"},"reason":{"type":"string"},"reason_label":{"type":"string"},"customer_name":{"type":["string","null"]},"customer_username":{"type":["string","null"]},"summary":{"type":["string","null"]},"created_at":{"type":"string"},"panel_url":{"type":"string"}}}}}}}}}},"responses":{"2XX":{"description":"هر پاسخ ۲xx یعنی دریافت شد"}}}},"credit.low":{"post":{"summary":"اعتبار رو به اتمام است","description":"هدرها: X-UttaPost-Event، X-UttaPost-Delivery، X-UttaPost-Signature (t=…,v1=…). امضا روی t + «.» + بایت‌های خام بدنه است.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","event","created_at","brand","data"],"properties":{"id":{"type":"string"},"event":{"const":"credit.low"},"created_at":{"type":"string","format":"date-time"},"brand":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":["string","null"]}}},"data":{"type":"object","properties":{"credit":{"type":"object","properties":{"balance":{"type":"integer"},"unit":{"const":"toman"}}}}}}}}}},"responses":{"2XX":{"description":"هر پاسخ ۲xx یعنی دریافت شد"}}}},"rule.paused":{"post":{"summary":"یک قانون خودکار متوقف شد","description":"هدرها: X-UttaPost-Event، X-UttaPost-Delivery، X-UttaPost-Signature (t=…,v1=…). امضا روی t + «.» + بایت‌های خام بدنه است.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","event","created_at","brand","data"],"properties":{"id":{"type":"string"},"event":{"const":"rule.paused"},"created_at":{"type":"string","format":"date-time"},"brand":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":["string","null"]}}},"data":{"type":"object","properties":{"rule":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":["string","null"]}}},"reason":{"enum":["credit","no_plan","manual"]}}}}}}}},"responses":{"2XX":{"description":"هر پاسخ ۲xx یعنی دریافت شد"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer up_live_…"}},"schemas":{"Error":{"type":"object","required":["message"],"properties":{"message":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object"}}},"EventName":{"enum":["draft.created","approval.requested","post.published","post.failed","handoff.opened","credit.low","rule.paused"]},"Me":{"type":"object","properties":{"brand":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":["string","null"]},"kind":{"type":"string"},"has_plan":{"type":"boolean"}}},"key":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"enum":["read","draft","publish"]}},"rate_per_minute":{"type":"integer"},"daily_spend_cap":{"type":"integer"},"spent_today":{"type":"integer"},"expires_at":{"type":["string","null"]}}}}},"Item":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"source":{"type":"string"},"type_id":{"type":["integer","null"]},"price":[],"in_stock":{"type":["boolean","null"]},"cover_url":{"type":["string","null"]},"description":{"type":["string","null"]}}},"ItemInput":{"type":"object","required":["title"],"properties":{"title":{"type":"string","maxLength":255},"description":{"type":"string"},"price":{"type":"number"},"sale_price":{"type":"number"},"in_stock":{"type":"boolean"},"sku":{"type":"string"},"url":{"type":"string","format":"uri"},"type_id":{"type":"integer"},"folder_id":{"type":"integer"},"images":{"type":"array","items":{"type":"string","format":"binary"}}}},"ItemPage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Pagination":{"type":"object","properties":{"current_page":{"type":"integer"},"last_page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"}}},"WebhookDraft":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string"},"format":{"type":"string"},"aspect":{"type":"string"},"title":{"type":["string","null"]},"caption":{"type":["string","null"]},"scheduled_for":{"type":["string","null"]},"created_at":{"type":["string","null"]},"panel_url":{"type":"string"}}},"Draft":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string"},"format":{"type":"string"},"aspect":{"type":"string"},"title":{"type":["string","null"]},"caption":{"type":["string","null"]},"scheduled_for":{"type":["string","null"]},"created_at":{"type":["string","null"]},"media":{"type":"array","items":{"type":"object"}}}},"Preview":{"type":"object","properties":{"title":{"type":"string"},"lines":{"type":"array","items":{"type":"string"}},"cost":{"type":"integer","description":"تومان"},"confirm_token":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}},"ConfirmResult":{"type":"object","properties":{"status":{"const":"done"},"charged":{"type":"integer"},"summary":{"type":"string"},"content_ids":{"type":"array","items":{"type":"integer"}}}},"PostStats":{"type":"object","properties":{"days":{"type":"integer"},"targets":{"type":"object"},"published_by_network":{"type":"object"},"total":{"type":"integer"}}},"PostTarget":{"type":"object","properties":{"content_id":{"type":"integer"},"target_id":{"type":"integer"},"network":{"type":["string","null"]},"network_name":{"type":"string"},"post_url":{"type":["string","null"]},"published_at":{"type":["string","null"]},"panel_url":{"type":"string"}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":["string","null"]},"url":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/EventName"}},"active":{"type":"boolean"},"consecutive_failures":{"type":"integer"},"disabled_at":{"type":["string","null"]},"last_status":{"type":["integer","null"]},"secret":{"type":"string","description":"فقط در پاسخ ساخت، یک بار"}}}}}}