API задач

HTTP API для серверных интеграций: создавайте задачи из CRM и форм, забирайте изменения в отчёты, пишите комментарии из скриптов. JSON на входе и выходе, личный токен в заголовке.

Базовый адрес https://ahora.team/api/v1

Что можно сделать с API

Начало работы

Первый запрос

Откройте в Ahora «Настройки воркспейса → API и интеграции» и нажмите «Новый токен». Выберите доступ и срок действия, скопируйте секрет — он показывается один раз.

Проверьте токен запросом /context: он вернёт воркспейс, от чьего имени работает токен, и его права.

Запрос

curl https://ahora.team/api/v1/context \
  -H "Authorization: Bearer $AHORA_TOKEN"

Ответ 200

{
  "workspace": {
    "id": "01J9ZK0A1B2C3D4E5F6G7H8J9K",
    "name": "Тропа",
    "slug": "team"
  },
  "actor": {
    "id": "01J9ZK3P7M1N5Q8S2V4X6Z0B3D",
    "name": "Анна Смирнова"
  },
  "scopes": [
    "tasks:read",
    "tasks:write"
  ]
}

Токены и права

Токен передаётся в заголовке Authorization: Bearer …. Он принадлежит человеку, который его создал, и действует только в одном воркспейсе. Всё, что делает токен, выглядит в Ahora как действие этого человека.

Токен перестаёт работать, если его отозвали, истёк срок или владельца отключили. Если владельца удалили из воркспейса, его токены отзываются насовсем: после повторного приглашения нужен новый токен. Во всех этих случаях приходит 401 invalid_token.

Всё, что делает токен, видно в Ahora так же, как действия человека: смена статуса, приоритета и срока попадает в ленту задачи, наблюдатели и исполнители получают уведомления, упомянутые в комментариях — тоже.

Токен — секрет уровня пароля. Храните его на сервере, а не в коде сайта или мобильного приложения: запросы из браузера с чужого домена API не принимает.

Право	Что разрешает
`tasks:read`	Контекст, доски, статусы, участники, задачи, комментарии и чек-листы
`tasks:write`	Всё из `tasks:read`, а ещё создание и изменение задач, исполнители, комментарии и чек-листы

Формат

Запросы и ответы — JSON в UTF-8, поля в camelCase. Даты — строки ISO 8601: в ответах всегда UTC (2026-10-21T09:00:00.000Z), в запросах можно с любым смещением (2026-10-21T12:00:00+03:00).

Один объект приходит в поле data, список — в data вместе с pagination. В PATCH-запросах отсутствующее поле не меняется, а null очищает его.

В каждом ответе есть заголовок X-Request-Id. Можно передать свой — он вернётся тем же.

Ошибки

При ошибке приходит HTTP-статус и объект error. Ориентируйтесь на code — он не меняется. message написан для людей и может уточняться.

Ответ 404

{
  "error": {
    "code": "status_not_found",
    "message": "Статус не найден",
    "requestId": "req_01JB7F0A2C4E6G8J0L2N4Q6S8U"
  }
}

Статус	Код	Когда
400	`validation_error`	Тело запроса не прошло проверку
400	`invalid_limit`, `invalid_cursor`, `invalid_date`, `invalid_priority`	Неверный параметр списка задач
400	`invalid_idempotency_key`	`Idempotency-Key` длиннее 200 символов
400	`member_not_found`	Среди `assigneeIds` есть не участник воркспейса
401	`authentication_required`	Нет заголовка `Authorization`
401	`invalid_token`	Токен неверный, отозван или истёк
403	`insufficient_scope`	Токену не хватает права, например `tasks:write`
403	`board_archived`, `task_archived`	Доска или задача в архиве — только чтение
404	`board_not_found`, `status_not_found`, `task_not_found`, `member_not_found`, `comment_not_found`, `checklist_item_not_found`	Объекта нет в этом воркспейсе
409	`idempotency_conflict`	Ключ уже использован с другим телом запроса
409	`external_id_conflict`	Такой `externalId` уже есть у задачи этого токена
412	`version_conflict`	Задачу изменили после того, как вы её прочитали
429	`rate_limit_exceeded`	Слишком много запросов на токен или слишком много запросов с неверным токеном

Лимиты

300 запросов в минуту на токен. Лимит приходит в заголовке X-RateLimit-Limit. При превышении — 429 и Retry-After: 60: подождите указанное число секунд и повторите.

С одного адреса можно сделать 30 запросов в минуту с неверным или отозванным токеном, дальше API отвечает 429, не проверяя токен.

Надёжная интеграция

Пагинация

GET /tasks отдаёт задачи страницами, сначала недавно изменённые. Если pagination.hasMore равно true, передайте pagination.nextCursor в параметре cursor следующего запроса с теми же фильтрами. Курсор непрозрачный: не разбирайте и не собирайте его сами.

Ответ 200

{
  "data": [
    "…"
  ],
  "pagination": {
    "nextCursor": "WzE3OTI0MzI5MjgxNDcsIjAxSkI3QzJXOUUiXQ",
    "hasMore": true
  }
}

Повторы без дублей

Если ответ на создание задачи не дошёл, запрос можно безопасно повторить с тем же заголовком Idempotency-Key. В течение суток Ahora вернёт первую созданную задачу, а не сделает вторую. Тот же ключ с другим телом — 409 idempotency_conflict.

externalId — ваш идентификатор: номер лида, заявки, тикета. Он уникален в пределах токена и возвращается в задаче, так что связь не потеряется и без своей базы.

Запрос

curl https://ahora.team/api/v1/tasks \
  -H "Authorization: Bearer $AHORA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-lead-92831" \
  -d '{ "boardId": "01JB6Y0M4QZ8V3K2T7R5N9XW1A", "title": "Перезвонить клиенту", "externalId": "lead-92831" }'

Одновременные изменения

У задачи есть version — она растёт при каждом изменении, в том числе сделанном в приложении. GET /tasks/:taskId возвращает её в заголовке ETag.

Передайте ETag в If-Match при PATCH: если задачу успели изменить, придёт 412 version_conflict, и ничего не запишется. Перечитайте задачу, примените своё изменение и повторите. Без If-Match изменение записывается поверх текущей версии.

Запрос

curl https://ahora.team/api/v1/tasks/01JB7C2W9EXQ4N8R2T6V0Y3Z5B \
  -X PATCH \
  -H "Authorization: Bearer $AHORA_TOKEN" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "task-01JB7C2W9EXQ4N8R2T6V0Y3Z5B-v3"' \
  -d '{ "statusId": "01JB6Y0M4R2D8F0H3K6M9P1S4T" }'

Синхронизация

Чтобы забирать изменения, запоминайте время начала каждого запуска и в следующий раз передавайте его в updatedAfter. В выдачу попадут задачи, у которых изменились поля или исполнители.

Новые комментарии и пункты чек-листа updatedAt задачи не меняют — их запрашивайте отдельно. Задача, удалённая в приложении, просто пропадает из выдачи, а GET /tasks/:taskId отвечает 404. Вебхуков пока нет.

Справочник

Задача

Так выглядит задача во всех ответах.

Поле	Тип	Описание
`id`	string	Идентификатор задачи
`key`	string	Номер, как в приложении: `TEAM-142`
`boardId`, `statusId`	string	Доска и колонка
`title`	string	Название, до 300 символов
`description`	string \| null	Описание в Markdown, до 20 000 символов
`priority`	string \| null	`low`, `medium`, `high` или `urgent`
`tags`	string[]	До 8 тегов по 50 символов
`dueAt`	string \| null	Срок, ISO 8601
`archived`	boolean	Задача завершена и лежит в архиве
`assignees`	{ id, name }[]	Исполнители
`externalId`	string \| null	Ваш идентификатор; виден только токену, который его задал
`createdAt`, `updatedAt`	string	ISO 8601, UTC
`version`	integer	Растёт при каждом изменении

Контекст

Токен и воркспейс

GET/contexttasks:read

Воркспейс токена, его владелец и права. Удобно для проверки токена при настройке интеграции.

Запрос

curl https://ahora.team/api/v1/context \
  -H "Authorization: Bearer $AHORA_TOKEN"

Доски и статусы

Доски и колонки создаются в приложении. Через API их можно только прочитать, чтобы узнать boardId и statusId.

Список досок

GET/boardstasks:read

Все доски воркспейса в порядке боковой панели, включая архивные.

Запрос

curl https://ahora.team/api/v1/boards \
  -H "Authorization: Bearer $AHORA_TOKEN"

Ответ 200

{
  "data": [
    {
      "id": "01JB6Y0M4QZ8V3K2T7R5N9XW1A",
      "name": "Продажи",
      "archived": false
    }
  ]
}

Статусы доски

GET/boards/:boardId/statusestasks:read

Колонки доски слева направо. Первая — статус по умолчанию для новых задач.

Запрос

curl https://ahora.team/api/v1/boards/01JB6Y0M4QZ8V3K2T7R5N9XW1A/statuses \
  -H "Authorization: Bearer $AHORA_TOKEN"

Ответ 200

{
  "data": [
    {
      "id": "01JB6Y0M4R2D8F0H3K6M9P1S4T",
      "name": "К обсуждению",
      "color": "#8E8E93",
      "sortOrder": 0
    }
  ]
}

Участники

Участники воркспейса

GET/memberstasks:read

До 100 участников по алфавиту. Нужны, чтобы найти id исполнителя.

Параметры

querystring: Часть имени

Запрос

curl "https://ahora.team/api/v1/members?query=анна" \
  -H "Authorization: Bearer $AHORA_TOKEN"

Ответ 200

{
  "data": [
    {
      "id": "01J9ZK3P7M1N5Q8S2V4X6Z0B3D",
      "name": "Анна Смирнова"
    }
  ]
}

Задачи

Список задач

GET/taskstasks:read

Задачи воркспейса, сначала недавно изменённые. Без archived=true — только активные.

Параметры

boardIdstring: Только эта доска
statusIdstring: Только эта колонка
assigneeIdstring: Задачи, где участник — исполнитель
prioritystring: low, medium, high или urgent
tagstring: Задачи с этим тегом
archivedboolean: true — только задачи в архиве
dueBefore, dueAfterISO 8601: Срок раньше или позже указанного
updatedAfterISO 8601: Изменённые после указанного момента
querystring: Текст в названии или описании
limitinteger: От 1 до 100, по умолчанию 50
cursorstring: nextCursor из предыдущего ответа

Запрос

curl "https://ahora.team/api/v1/tasks?boardId=01JB6Y0M4QZ8V3K2T7R5N9XW1A&limit=20" \
  -H "Authorization: Bearer $AHORA_TOKEN"

Создать задачу

POST/taskstasks:write

Задача появляется в конце колонки, и все, кто смотрит доску, видят её сразу. Без statusId попадает в первую колонку доски. Исполнители получают уведомление, упомянутые в описании — тоже.

Тело

boardIdstringобязательно: Доска, не в архиве
titlestringобязательно: До 300 символов
statusIdstring: Колонка этой доски
descriptionstring | null: Markdown, до 20 000 символов
prioritystring | null: low, medium, high, urgent
dueAtstring | null: ISO 8601 со смещением
tagsstring[]: До 8 тегов
assigneeIdsstring[]: Участники воркспейса
externalIdstring: Ваш идентификатор, до 200 символов

Заголовки

Idempotency-Keystring: До 200 символов, см. «Повторы без дублей»

Запрос

curl https://ahora.team/api/v1/tasks \
  -H "Authorization: Bearer $AHORA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-lead-92831" \
  -d '{
    "boardId": "01JB6Y0M4QZ8V3K2T7R5N9XW1A",
    "title": "Перезвонить клиенту",
    "description": "Заявка с сайта: интересуется тарифом на 30 человек",
    "priority": "high",
    "dueAt": "2026-10-21T12:00:00+03:00",
    "tags": ["crm"],
    "assigneeIds": ["01J9ZK3P7M1N5Q8S2V4X6Z0B3D"],
    "externalId": "lead-92831"
  }'

Ответ 201

{
  "data": {
    "id": "01JB7C2W9EXQ4N8R2T6V0Y3Z5B",
    "key": "TEAM-142",
    "boardId": "01JB6Y0M4QZ8V3K2T7R5N9XW1A",
    "statusId": "01JB6Y0M4R2D8F0H3K6M9P1S4T",
    "title": "Перезвонить клиенту",
    "description": "Заявка с сайта: интересуется тарифом на 30 человек",
    "priority": "high",
    "tags": [
      "crm"
    ],
    "dueAt": "2026-10-21T09:00:00.000Z",
    "archived": false,
    "assignees": [
      {
        "id": "01J9ZK3P7M1N5Q8S2V4X6Z0B3D",
        "name": "Анна Смирнова"
      }
    ],
    "externalId": "lead-92831",
    "createdAt": "2026-10-19T10:24:05.311Z",
    "updatedAt": "2026-10-19T10:24:05.311Z",
    "version": 1
  }
}

Получить задачу

GET/tasks/:taskIdtasks:read

Возвращает задачу и её версию в заголовке ETag.

Запрос

curl -i https://ahora.team/api/v1/tasks/01JB7C2W9EXQ4N8R2T6V0Y3Z5B \
  -H "Authorization: Bearer $AHORA_TOKEN"

Изменить задачу

PATCH/tasks/:taskIdtasks:write

Передайте только то, что меняете. Завершить задачу — {"archived": true}, вернуть из архива — {"archived": false}. Задачу в архиве можно только вернуть.

При смене статуса карточка встаёт в конец новой колонки. Смена статуса, приоритета и срока записывается в ленту задачи, наблюдатели узнают о новом статусе и о завершении.

Тело

titlestring: До 300 символов
descriptionstring | null: Markdown
statusIdstring: Колонка той же доски
prioritystring | null: low, medium, high, urgent
dueAtstring | null: ISO 8601 со смещением
tagsstring[]: Заменяет теги целиком
archivedboolean: Завершить или вернуть из архива

Заголовки

If-Matchstring: ETag задачи, см. «Одновременные изменения»

Запрос

curl https://ahora.team/api/v1/tasks/01JB7C2W9EXQ4N8R2T6V0Y3Z5B \
  -X PATCH \
  -H "Authorization: Bearer $AHORA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "priority": "urgent", "dueAt": null }'

Ответ 200

{
  "data": {
    "id": "01JB7C2W9EXQ4N8R2T6V0Y3Z5B",
    "key": "TEAM-142",
    "boardId": "01JB6Y0M4QZ8V3K2T7R5N9XW1A",
    "statusId": "01JB6Y0M4R2D8F0H3K6M9P1S4T",
    "title": "Перезвонить клиенту",
    "description": "Заявка с сайта: интересуется тарифом на 30 человек",
    "priority": "urgent",
    "tags": [
      "crm"
    ],
    "dueAt": null,
    "archived": false,
    "assignees": [
      {
        "id": "01J9ZK3P7M1N5Q8S2V4X6Z0B3D",
        "name": "Анна Смирнова"
      }
    ],
    "externalId": "lead-92831",
    "createdAt": "2026-10-19T10:24:05.311Z",
    "updatedAt": "2026-10-19T11:02:40.118Z",
    "version": 2
  }
}

Исполнители

Назначить исполнителя

PUT/tasks/:taskId/assignees/:userIdtasks:write

Повторное назначение ничего не меняет. Новый исполнитель получает уведомление, а в ленте задачи появляется запись. Возвращает текущий список исполнителей.

Запрос

curl https://ahora.team/api/v1/tasks/01JB7C2W9EXQ4N8R2T6V0Y3Z5B/assignees/01J9ZK3P7M1N5Q8S2V4X6Z0B3D \
  -X PUT \
  -H "Authorization: Bearer $AHORA_TOKEN"

Ответ 200

{
  "data": [
    {
      "id": "01J9ZK3P7M1N5Q8S2V4X6Z0B3D",
      "name": "Анна Смирнова"
    }
  ]
}

Снять исполнителя

DELETE/tasks/:taskId/assignees/:userIdtasks:write

Возвращает оставшихся исполнителей.

Запрос

curl https://ahora.team/api/v1/tasks/01JB7C2W9EXQ4N8R2T6V0Y3Z5B/assignees/01J9ZK3P7M1N5Q8S2V4X6Z0B3D \
  -X DELETE \
  -H "Authorization: Bearer $AHORA_TOKEN"

{
  "data": [
    {
      "id": "01JB7D4F6H8K0M2P4R6T8V0X2Z",
      "body": "Клиент просит перезвонить после обеда",
      "kind": "text",
      "parentId": null,
      "createdAt": "2026-10-19T10:31:12.004Z",
      "author": {
        "id": "01J9ZK3P7M1N5Q8S2V4X6Z0B3D",
        "name": "Анна Смирнова"
      }
    }
  ]
}

Написать комментарий

POST/tasks/:taskId/commentstasks:write

Комментарий подписан именем владельца токена и сразу появляется у всех, у кого открыта задача. Наблюдатели и упомянутые получают уведомление. Чтобы ответить в ветке, передайте parentId.

Тело

bodystringобязательно: Текст, до 20 000 символов
parentIdstring | null: Комментарий этой же задачи

Запрос

curl https://ahora.team/api/v1/tasks/01JB7C2W9EXQ4N8R2T6V0Y3Z5B/comments \
  -H "Authorization: Bearer $AHORA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Счёт оплачен, можно начинать" }'

Чек-лист

Пункты чек-листа

GET/tasks/:taskId/checklisttasks:read

Пункты в порядке, в котором они стоят в задаче.

Запрос

curl https://ahora.team/api/v1/tasks/01JB7C2W9EXQ4N8R2T6V0Y3Z5B/checklist \
  -H "Authorization: Bearer $AHORA_TOKEN"

Ответ 200

{
  "data": [
    {
      "id": "01JB7E1G3J5L7N9Q1S3U5W7Y9A",
      "taskId": "01JB7C2W9EXQ4N8R2T6V0Y3Z5B",
      "title": "Отправить договор",
      "isDone": false,
      "sortOrder": 0,
      "createdAt": "2026-10-19T10:40:00.000Z"
    }
  ]
}

Добавить пункт

POST/tasks/:taskId/checklisttasks:write

Пункт добавляется в конец списка.

Тело

titlestringобязательно: До 500 символов

Запрос

curl https://ahora.team/api/v1/tasks/01JB7C2W9EXQ4N8R2T6V0Y3Z5B/checklist \
  -H "Authorization: Bearer $AHORA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Отправить договор" }'

Изменить пункт

PATCH/tasks/:taskId/checklist/:itemIdtasks:write

Переименовать пункт или отметить выполненным.

Тело

titlestring: До 500 символов
isDoneboolean: Выполнен ли пункт

Запрос

curl https://ahora.team/api/v1/tasks/01JB7C2W9EXQ4N8R2T6V0Y3Z5B/checklist/01JB7E1G3J5L7N9Q1S3U5W7Y9A \
  -X PATCH \
  -H "Authorization: Bearer $AHORA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "isDone": true }'

Удалить пункт

DELETE/tasks/:taskId/checklist/:itemIdtasks:write

Возвращает {"ok": true}.

Запрос

curl https://ahora.team/api/v1/tasks/01JB7C2W9EXQ4N8R2T6V0Y3Z5B/checklist/01JB7E1G3J5L7N9Q1S3U5W7Y9A \
  -X DELETE \
  -H "Authorization: Bearer $AHORA_TOKEN"

Чего в API нет

Если вам нужно что-то из этого, напишите нам — так мы поймём, что делать дальше.

Вебхуков: изменения нужно забирать запросом с updatedAfter
Создания и изменения досок и статусов, сортировки карточек и массовых операций
Удаления задач — только перенос в архив
Файлов, ссылок на документы, чатов и базы знаний
OAuth-приложений и SDK — только личные токены и HTTP

Первый запрос

Токены и права

Формат

Ошибки

Лимиты

Пагинация

Повторы без дублей

Одновременные изменения

Синхронизация

Задача

Контекст

Токен и воркспейс

Доски и статусы

Список досок

Статусы доски

Участники

Участники воркспейса

Параметры

Задачи

Список задач

Параметры

Создать задачу

Тело

Заголовки

Получить задачу

Изменить задачу

Тело

Заголовки

Исполнители

Назначить исполнителя

Снять исполнителя

Комментарии

Комментарии задачи

Написать комментарий

Тело

Чек-лист

Пункты чек-листа

Добавить пункт

Тело

Изменить пункт

Тело

Удалить пункт

Чего в API нет