API

UTasks Developer API

API عمومی برای یکپارچه‌سازی سرویس‌های دیگر با UTasks.

شروع کار

نشانی پایه

https://app.utasks.io/utb

همه نقطه‌های پایانی با پیشوند /pub/v1/ شروع می‌شوند.

احراز هویت

API از توکن Bearer استفاده می‌کند. برای گرفتن کلید، دستور /apikey new را به @UTasksBot بفرستید.

کلید را در سرآیند هر درخواست بفرستید:

Authorization: Bearer utb_xxxxxxxxxxxxxxxx

بررسی اتصال

مطمئن شوید کلید کار می‌کند – پروفایل خود را درخواست کنید:

GET /utb/pub/v1/profile
Authorization: Bearer utb_...

نقطه‌های پایانی

پروفایل

`GET /pub/v1/profile`

پروفایل صاحب کلید API را برمی‌گرداند. برای بررسی اتصال مناسب است.

پاسخ 200 – شیء PubProfileModel

{
  "userId": "abc123",
  "userName": "ivan",
  "title": "Ivan Petrov",
  "role": "PRO",
  "roleExpireDate": "2025-12-31T00:00:00Z",
  "locale": "ru",
  "timeZone": "Europe/Moscow",
  "timeZoneId": 3
}

پروژه‌ها

`GET /pub/v1/projects`

پروژه‌هایی که کاربر فعلی عضو آن‌هاست.

پاسخ 200 – آرایه‌ای از PubProjectModel

`GET /pub/v1/projects/{id}`

گرفتن پروژه با شناسه. فقط برای پروژه‌هایی که کاربر عضو آن‌هاست.

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
`id`	string	✓	شناسه پروژه

پاسخ 200 – شیء PubProjectModel

`GET /pub/v1/projects/{id}/users`

اعضای پروژه با وضعیتشان. فقط برای پروژه‌هایی که کاربر عضو آن‌هاست.

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
`id`	string	✓	شناسه پروژه

پاسخ 200 – آرایه‌ای از PubProjectUserModel

وظایف

`GET /pub/v1/tasks`

وظایف کاربر فعلی – بر اساس محدوده یا پروژه.

پارامترهای پرس‌وجو

پارامتر	نوع	توضیح
`scope`	`PubTaskScope`	محدوده وظایف (به‌طور پیش‌فرض `All`). اگر `projectId` تعیین شده باشد نادیده گرفته می‌شود
`projectId`	string	شناسه پروژه؛ عضویت فعال لازم است
`completed`	boolean	`true` – به جای وظایف باز، وظایف تکمیل‌شده برگردانده شوند
`q`	string	عبارت جستجو (در عنوان‌ها جستجو می‌کند)

پاسخ 200 – آرایه‌ای از PubTaskModel

نمونه

GET /utb/pub/v1/tasks?scope=Today
Authorization: Bearer utb_...

GET /utb/pub/v1/tasks?projectId=abc123&completed=false
Authorization: Bearer utb_...

`POST /pub/v1/tasks`

ساختن وظیفه در یک پروژه یا در صندوق ورودی شخصی. همان اعلان‌هایی را در پیام‌رسان می‌فرستد که وظایف ساخته‌شده در برنامه.

بدنه درخواست – PubCreateTaskRequest

پاسخ 200 – شیء PubTaskModel

نمونه

{
  "title": "تهیه گزارش",
  "description": "گزارش شاخص‌های فصلی",
  "projectId": "abc123",
  "planDate": "2025-08-01T09:00:00Z",
  "dueDate": "2025-08-05T18:00:00Z",
  "priority": "High",
  "assigneeIds": ["user1", "user2"]
}

`GET /pub/v1/tasks/{id}`

گرفتن وظیفه با شناسه.

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
`id`	string	✓	شناسه وظیفه

پاسخ 200 – شیء PubTaskModel

`PATCH /pub/v1/tasks/{id}`

به‌روزرسانی بخشی از وظیفه. فقط فیلدهایی که می‌فرستید (و null نیستند) به‌روز می‌شوند. فهرست خالی assigneeIds همه مسئولان را حذف می‌کند.

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
`id`	string	✓	شناسه وظیفه

بدنه درخواست – PubUpdateTaskRequest

پاسخ 200 – شیء PubTaskModel

نمونه – تغییر وضعیت و اولویت

{
  "status": "InProgress",
  "priority": "Highest"
}

نمونه – پاک کردن تاریخ برنامه‌ریزی‌شده

{
  "clearPlanDate": true
}

`DELETE /pub/v1/tasks/{id}`

حذف وظیفه. برای سازنده وظیفه و مدیران پروژه مجاز است.

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
`id`	string	✓	شناسه وظیفه

`POST /pub/v1/tasks/{id}/complete`

علامت زدن وظیفه به‌عنوان تکمیل‌شده. سازنده کل وظیفه را می‌بندد؛ مسئول فقط سهم خودش را علامت می‌زند – وقتی همه مسئولان سهم خود را تکمیل کنند، وظیفه به‌طور کلی بسته می‌شود. برای سازنده و مسئولان در دسترس است.

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
`id`	string	✓	شناسه وظیفه

`POST /pub/v1/tasks/{id}/uncomplete`

بازگشایی وظیفه تکمیل‌شده برای همه شرکت‌کنندگان؛ وضعیت به New برمی‌گردد. برای سازنده و مسئولان در دسترس است.

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
`id`	string	✓	شناسه وظیفه

`GET /pub/v1/tasks/{id}/history`

تاریخچه تغییرات و نظرات وظیفه، به‌طور پیش‌فرض از قدیمی‌ترین به جدیدترین.

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
`id`	string	✓	شناسه وظیفه

پارامترهای پرس‌وجو

پارامتر	نوع	توضیح
`filter`	string	فیلتر رکوردهای تاریخچه
`sort`	string	ترتیب مرتب‌سازی رکوردها

پاسخ 200 – آرایه‌ای از PubTaskHistoryItemModel

`POST /pub/v1/tasks/{id}/attachassignee`

افزودن کاربر فعلی (صاحب کلید API) به‌عنوان مسئول وظیفه.

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
`id`	string	✓	شناسه وظیفه

`POST /pub/v1/tasks/{id}/publish`

انتشار کارت وظیفه به‌صورت پیام در چت پروژه (برای پروژه‌های عمومی) یا در چت شخصی سازنده.

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
`id`	string	✓	شناسه وظیفه

`POST /pub/v1/tasks/{id}/comments`

افزودن نظر متنی به وظیفه.

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
`id`	string	✓	شناسه وظیفه

بدنه درخواست – PubCommentRequest

{
  "text": "انجام شد، لطفاً بررسی کنید"
}

مدل‌های داده

PubProfileModel

پروفایل کاربری که صاحب کلید API است.

فیلد	نوع	توضیح
`userId`	string	شناسه کاربر
`userName`	string	نام کاربری
`title`	string	نام نمایشی
`role`	string	طرح / نقش
`roleExpireDate`	string (ISO 8601)	تاریخ پایان طرح
`locale`	string	زبان رابط کاربری
`timeZone`	string	منطقه زمانی (IANA)
`timeZoneId`	number	شناسه منطقه زمانی

PubProjectModel

فیلد	نوع	توضیح
`id`	string	شناسه پروژه
`name`	string	نام پروژه
`description`	string	شرح
`type`	`UTProjectType`	نوع پروژه

PubProjectUserModel

فیلد	نوع	توضیح
`id`	string	شناسه کاربر
`userName`	string	نام کاربری
`title`	string	نام نمایشی
`status`	`UTUserStatus`	وضعیت عضو در پروژه

PubUserModel

اطلاعات کوتاه کاربر (درون وظایف به کار می‌رود).

فیلد	نوع	توضیح
`id`	string	شناسه کاربر
`userName`	string	نام کاربری
`title`	string	نام نمایشی

PubTaskModel

فیلد	نوع	توضیح
`id`	string	شناسه وظیفه
`number`	string	شماره خوانای وظیفه، مثلاً `UT-12`
`title`	string	عنوان وظیفه
`description`	string	شرح
`status`	`UTTaskStatus`	وضعیت
`priority`	`UTTaskPriority`	اولویت
`projectId`	string \| null	شناسه پروژه؛ برای وظایف صندوق ورودی شخصی `null`
`projectName`	string \| null	نام پروژه؛ برای صندوق ورودی شخصی `null`
`planDate`	string \| null	تاریخ برنامه‌ریزی‌شده (ISO 8601)
`planCron`	string \| null	قاعده تکرار برای تاریخ برنامه‌ریزی‌شده
`dueDate`	string \| null	مهلت (ISO 8601)
`isCompleted`	boolean	وظیفه به‌طور کلی تکمیل شده است. برای وظایفی با چند مسئول، فقط وقتی `true` می‌شود که هر یک از آن‌ها سهم خود را علامت زده باشد
`completedDate`	string \| null	تاریخ تکمیل
`completedUserIds`	string[]	شناسه مسئولانی که سهم خود را تکمیل‌شده علامت زده‌اند
`personalCompleted`	boolean	وظیفه برای کاربر فعلی تکمیل شده است: یا به‌طور کلی تکمیل شده، یا کاربر سهم خود را علامت زده است
`author`	`PubUserModel`	سازنده وظیفه
`assignees`	`PubUserModel[]`	مسئولان

PubCreateTaskRequest

فیلد	نوع	الزامی	توضیح
`title`	string	✓	عنوان وظیفه، تا ۵۰۰۰ نویسه
`description`	string \| null		شرح، تا ۵۰۰۰ نویسه
`projectId`	string \| null		شناسه پروژه؛ برای صندوق ورودی شخصی آن را نفرستید
`planDate`	string \| null		تاریخ برنامه‌ریزی‌شده (ISO 8601)
`dueDate`	string \| null		مهلت؛ نمی‌تواند زودتر از تاریخ برنامه‌ریزی‌شده باشد
`planCron`	string \| null		قاعده تکرار برای تاریخ برنامه‌ریزی‌شده
`priority`	`UTTaskPriority`		اولویت
`assigneeIds`	string[] \| null		شناسه مسئولان. باید عضو پروژه باشند

PubUpdateTaskRequest

همه فیلدها اختیاری‌اند. فقط فیلدهایی را بفرستید که می‌خواهید تغییر دهند.

فیلد	نوع	توضیح
`title`	string \| null	عنوان تازه، تا ۵۰۰۰ نویسه
`description`	string \| null	شرح تازه، تا ۵۰۰۰ نویسه
`planDate`	string \| null	تاریخ برنامه‌ریزی‌شده تازه
`dueDate`	string \| null	مهلت تازه؛ نمی‌تواند زودتر از تاریخ برنامه‌ریزی‌شده باشد
`clearPlanDate`	boolean	پاک کردن تاریخ برنامه‌ریزی‌شده (بر `planDate` مقدم است)
`clearDueDate`	boolean	پاک کردن مهلت (بر `dueDate` مقدم است)
`planCron`	string \| null	قاعده تکرار تازه
`priority`	`UTTaskPriority`	اولویت تازه
`status`	`UTTaskStatus`	وضعیت تازه
`assigneeIds`	string[] \| null	فهرست کامل تازه مسئولان (آرایه خالی همه را حذف می‌کند)

PubCommentRequest

فیلد	نوع	الزامی	توضیح
`text`	string	✓	متن نظر

PubCommentModel

فیلد	نوع	توضیح
`text`	string	متن نظر
`createDate`	string (ISO 8601)	تاریخ ساخته شدن

PubTaskHistoryItemModel

یک رکورد از تاریخچه تغییرات وظیفه.

فیلد	نوع	توضیح
`date`	string (ISO 8601)	تاریخ رویداد
`author`	`PubUserModel`	سازنده تغییر
`comment`	string	متن نظر (اگر این رکورد نظر باشد)
`change`	`PubTaskHistoryChangeModel`	جزئیات تغییر فیلد

PubTaskHistoryChangeModel

فیلد	نوع	توضیح
`field`	string	نام فیلد تغییرکرده
`oldValue`	string	مقدار قبلی
`newValue`	string	مقدار تازه

شمارش‌ها (enum)

UTTaskStatus

وضعیت وظیفه.

مقدار	توضیح
`New`	جدید
`ToDo`	برنامه‌ریزی‌شده
`InProgress`	در حال انجام
`Resolved`	انجام‌شده
`Review`	در بررسی
`Approved`	تأییدشده
`Closed`	بسته‌شده

UTTaskPriority

اولویت وظیفه.

مقدار	توضیح
`None`	تعیین نشده
`Lowest`	خیلی کم
`Low`	کم
`Medium`	متوسط
`High`	زیاد
`Highest`	خیلی زیاد

UTProjectType

نوع پروژه.

مقدار	توضیح
`Private`	خصوصی
`Public`	عمومی
`Dynamic`	پویا

UTUserStatus

نقش عضو در پروژه.

مقدار	توضیح
`None`	بدون نقش
`Creator`	سازنده
`Administrator`	مدیر
`Member`	عضو

PubTaskScope

محدوده فیلتر وظایف.

مقدار	توضیح
`All`	همه وظایف
`Inbox`	صندوق ورودی
`Today`	موعد امروز
`Tomorrow`	موعد فردا
`Week`	موعد این هفته
`Completed`	تکمیل‌شده

نمونه‌های استفاده

گرفتن وظایف امروز

GET /utb/pub/v1/tasks?scope=Today
Authorization: Bearer utb_...

ساختن وظیفه در صندوق ورودی شخصی

POST /utb/pub/v1/tasks
Authorization: Bearer utb_...
Content-Type: application/json

{
  "title": "تماس با مشتری",
  "planDate": "2025-08-01T10:00:00Z",
  "priority": "High"
}

ساختن وظیفه در یک پروژه با مسئولان

POST /utb/pub/v1/tasks
Authorization: Bearer utb_...
Content-Type: application/json

{
  "title": "بررسی PR #42",
  "projectId": "proj_abc",
  "assigneeIds": ["user_1", "user_2"],
  "dueDate": "2025-08-03T18:00:00Z",
  "priority": "Medium"
}

بردن وظیفه به وضعیت «در حال انجام»

PATCH /utb/pub/v1/tasks/task_xyz
Authorization: Bearer utb_...
Content-Type: application/json

{
  "status": "InProgress"
}

تکمیل وظیفه

POST /utb/pub/v1/tasks/task_xyz/complete
Authorization: Bearer utb_...

افزودن نظر

POST /utb/pub/v1/tasks/task_xyz/comments
Authorization: Bearer utb_...
Content-Type: application/json

{
  "text": "انجام شد، منتظر بررسی شما هستم"
}

کدهای خطا

کد	توضیح
`400`	درخواست نادرست – بدنه درخواست را بررسی کنید
`401`	احراز هویت نشده – کلید API خود را بررسی کنید
`403`	ممنوع – دسترسی کافی برای این کار ندارید
`404`	شیء پیدا نشد
`500`	خطای داخلی سرور

بدنه خطا در قالب ProblemDetails برگردانده می‌شود:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Title is required"
}

اتصال سرور MCP