{"openapi":"3.0.3","info":{"title":"Aladdin Public API","version":"1.0.0","description":"Read-only public API for third-party integrations. Authenticate with a Bearer API token (`ald_...`). Navigate section → board → optional column → tasks. Visibility follows the subject user unless the token has `elevated_read=true` (then sections/boards/tasks outside subject ACL are readable; product UI ACL is unchanged). Scopes: `tasks:read`, `boards:read`, `users:read`."},"servers":[{"url":"https://api.aladdinhub.io/v1","description":"Production"}],"components":{"securitySchemes":{"ApiToken":{"type":"http","scheme":"bearer","bearerFormat":"ald_...","description":"API token issued in Управление → API-токены. Shown once at create/rotate."}},"schemas":{"PublicUser":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"role":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"team":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","name","isActive"]},"PublicTaskListItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"columnId":{"type":"string","format":"uuid"},"boardId":{"type":"string","format":"uuid","nullable":true},"boardName":{"type":"string","nullable":true},"columnName":{"type":"string","nullable":true},"author":{"$ref":"#/components/schemas/PublicUser"},"assignee":{"allOf":[{"$ref":"#/components/schemas/PublicUser"}],"nullable":true},"isClosed":{"type":"boolean"},"isPaused":{"type":"boolean"},"isUrgent":{"type":"boolean"},"deadlineStart":{"type":"string","format":"date-time","nullable":true},"deadlineEnd":{"type":"string","format":"date-time","nullable":true},"progress":{"type":"integer"},"complexity":{"type":"integer","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"closedAt":{"type":"string","format":"date-time","nullable":true},"startedAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"commentCount":{"type":"integer"},"status":{"type":"string","nullable":true}}},"PublicTaskDetail":{"allOf":[{"$ref":"#/components/schemas/PublicTaskListItem"},{"type":"object","properties":{"descriptionBlocks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"order":{"type":"integer"},"content":{"type":"string","nullable":true},"type":{"type":"string","nullable":true}}}},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"content":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true},"author":{"$ref":"#/components/schemas/PublicUser"},"parentId":{"type":"string","format":"uuid","nullable":true}}}}}}]},"PublicBoard":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"department":{"type":"string","nullable":true},"visibilityType":{"type":"string","nullable":true},"columns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"order":{"type":"integer"},"type":{"type":"string","nullable":true}}}}}},"PublicDepartment":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"order":{"type":"integer"},"color":{"type":"string","nullable":true},"icon":{"type":"string","nullable":true}},"required":["code","name","order"]},"Error":{"type":"object","properties":{"statusCode":{"type":"integer"},"message":{"type":"string"},"error":{"type":"string"}}}}},"security":[{"ApiToken":[]}],"paths":{"/tasks":{"get":{"operationId":"listTasks","tags":["Tasks"],"summary":"List tasks visible to the token subject","description":"Requires scope `tasks:read`. **boardId is required.** Optional filters: columnId, authorId, assigneeId, isUrgent, slaStatus (completed|on_time|overdue vs deadlineEnd), search, date ranges. Cursor pagination.","parameters":[{"name":"boardId","in":"query","required":true,"description":"Board UUID. Listing tasks without a board is not allowed.","schema":{"type":"string","format":"uuid"}},{"name":"columnId","in":"query","description":"Optional column UUID on the same board.","schema":{"type":"string","format":"uuid"}},{"name":"authorId","in":"query","description":"Filter by task author user id.","schema":{"type":"string","format":"uuid"}},{"name":"assigneeId","in":"query","description":"Filter by assignee user id.","schema":{"type":"string","format":"uuid"}},{"name":"isUrgent","in":"query","description":"true = only urgent; false = only non-urgent.","schema":{"type":"boolean"}},{"name":"slaStatus","in":"query","description":"completed = closed; on_time = open and deadlineEnd not past (or missing); overdue = open and deadlineEnd < now.","schema":{"type":"string","enum":["completed","on_time","overdue"]}},{"name":"search","in":"query","schema":{"type":"string","maxLength":200}},{"name":"updatedSince","in":"query","description":"Deprecated alias of updatedFrom. Inclusive lower bound on updatedAt.","schema":{"type":"string","format":"date-time"}},{"name":"updatedFrom","in":"query","description":"Inclusive lower bound on updatedAt (ISO-8601 or YYYY-MM-DD UTC).","schema":{"type":"string","format":"date-time"}},{"name":"updatedTo","in":"query","description":"Inclusive upper bound on updatedAt (ISO-8601 or YYYY-MM-DD UTC).","schema":{"type":"string","format":"date-time"}},{"name":"updatedOn","in":"query","description":"Exact UTC calendar day for updatedAt (YYYY-MM-DD). Do not combine with updatedFrom/To/Since.","schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"createdFrom","in":"query","description":"Inclusive lower bound on createdAt (ISO-8601 or YYYY-MM-DD UTC).","schema":{"type":"string","format":"date-time"}},{"name":"createdTo","in":"query","description":"Inclusive upper bound on createdAt (ISO-8601 or YYYY-MM-DD UTC).","schema":{"type":"string","format":"date-time"}},{"name":"createdOn","in":"query","description":"Exact UTC calendar day for createdAt (YYYY-MM-DD). Do not combine with createdFrom/To.","schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"deadlineFrom","in":"query","description":"Inclusive lower bound: tasks whose deadlineStart/deadlineEnd interval overlaps the range.","schema":{"type":"string","format":"date-time"}},{"name":"deadlineTo","in":"query","description":"Inclusive upper bound for deadline overlap filter.","schema":{"type":"string","format":"date-time"}},{"name":"deadlineOn","in":"query","description":"Exact UTC calendar day overlapping the task deadline (YYYY-MM-DD). Do not combine with deadlineFrom/To.","schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Task page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicTaskListItem"}},"nextCursor":{"type":"string","nullable":true},"limit":{"type":"integer"}}}}}},"401":{"description":"Invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope or IP denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited"}}}},"/tasks/{id}":{"get":{"operationId":"getTask","tags":["Tasks"],"summary":"Get a task by id","description":"Requires scope `tasks:read`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Task detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicTaskDetail"}}}},"401":{"description":"Invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/departments":{"get":{"operationId":"listDepartments","tags":["Departments"],"summary":"List board sections (departments)","description":"Requires scope `boards:read`. Without `elevated_read`, only sections where the subject can see at least one board. With `elevated_read`, the full active catalog.","responses":{"200":{"description":"Departments","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicDepartment"}}}}}}},"401":{"description":"Invalid token"},"403":{"description":"Missing scope or IP denied"},"429":{"description":"Rate limited"}}}},"/departments/{code}/boards":{"get":{"operationId":"listBoardsByDepartment","tags":["Departments"],"summary":"List boards in a section","description":"Requires scope `boards:read`. Unknown `code` returns an empty list (no tech/creative substitution).","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"},"description":"Section code (e.g. tech, creative, commercial)."}],"responses":{"200":{"description":"Boards","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicBoard"}}}}}}},"401":{"description":"Invalid token"},"403":{"description":"Missing scope or IP denied"},"429":{"description":"Rate limited"}}}},"/boards":{"get":{"operationId":"listBoards","tags":["Boards"],"summary":"List boards visible to the token","description":"Requires scope `boards:read`. Flat list across sections. Subject ACL unless `elevated_read`.","responses":{"200":{"description":"Boards","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicBoard"}}}}}}},"401":{"description":"Invalid token"},"403":{"description":"Missing scope or IP denied"},"429":{"description":"Rate limited"}}}},"/boards/{boardId}/tasks":{"get":{"operationId":"listBoardTasks","tags":["Boards"],"summary":"List tasks on a board","description":"Requires scope `tasks:read` only. Same filters as GET /tasks (columnId, author, assignee, urgent, sla, dates). boardId comes from the path.","parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"columnId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"authorId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"assigneeId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"isUrgent","in":"query","schema":{"type":"boolean"}},{"name":"slaStatus","in":"query","schema":{"type":"string","enum":["completed","on_time","overdue"]}},{"name":"search","in":"query","schema":{"type":"string","maxLength":200}},{"name":"createdFrom","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"createdTo","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"createdOn","in":"query","schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"updatedFrom","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"updatedTo","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Task page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicTaskListItem"}},"nextCursor":{"type":"string","nullable":true},"limit":{"type":"integer"}}}}}},"401":{"description":"Invalid token"},"403":{"description":"Missing scope or IP denied"},"404":{"description":"Board not found"},"429":{"description":"Rate limited"}}}},"/boards/{id}":{"get":{"operationId":"getBoard","tags":["Boards"],"summary":"Get a board with columns","description":"Requires scope `boards:read`. Task cards are not included.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Board","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicBoard"}}}},"401":{"description":"Invalid token"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/users":{"get":{"operationId":"listUsers","tags":["Users"],"summary":"List users (public fields only)","description":"Requires scope `users:read`. Never returns email, phone, telegram, birthDate, or password.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Users page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicUser"}},"nextCursor":{"type":"string","nullable":true},"limit":{"type":"integer"}}}}}},"401":{"description":"Invalid token"},"403":{"description":"Missing scope or IP denied"},"429":{"description":"Rate limited"}}}}},"tags":[{"name":"Departments","description":"Read sections then boards"},{"name":"Tasks","description":"Read tasks"},{"name":"Boards","description":"Read boards and columns"},{"name":"Users","description":"Read directory (public fields)"}]}