Соглашения

Регистр полей

Все поля запросов и ответов используют snake_case — например, due_date, task_status_id.

Обёртки ответа

Успешные ответы оборачиваются в обёртку data:

{ "data": { "id": "task_6a2918cff58b0a1d387866ee" } }

Списочные эндпоинты добавляют объект pagination:

{
  "data": [ /* … */ ],
  "pagination": { "next_cursor": "…", "has_more": true }
}

Ошибки используют отдельную обёртку — см. Ошибки.

Пагинация

Списочные эндпоинты используют пагинацию по курсору. Передайте next_cursor из предыдущего ответа, чтобы получить следующую страницу; has_more подсказывает, когда остановиться. Считайте курсор непрозрачным.

Фильтрация

GET /public/v1/tasks принимает фильтры как query-параметры: priority, task_status_id, state (open / closed), task_type_id, assignee_id, due_date_from / due_date_to / due_date, tag_id. Без фильтров возвращаются все задачи в рамках доступа — тот же набор, что и в табличном виде проекта в веб-приложении.

curl "https://api.bordio.com/public/v1/tasks?project_id=proj_6594a1b2c3d4e5f6a7b8c9d1&state=open&priority=high,critical" \
  -H "Authorization: Bearer brd_sk_live_..."

Как комбинируются фильтры:

• Разные параметры → AND. state=open&priority=high вернёт открытые задачи, которые при этом high-приоритета.
• Несколько значений внутри одного параметра → OR. Значения перечисляются через запятую: priority=high,critical совпадает с любым из приоритетов. tag_id=tag_a,tag_b совпадает с задачами, у которых есть хотя бы один из перечисленных тегов.
• Id передаются в публичной форме (task_status_…, task_type_…, user_…, tag_…). Некорректное значение вернёт 400 validation_error; корректный id, которому ничего не соответствует, просто даст пустую страницу. Исключение — project_id: проект вне доступа вашего ключа вернёт 404 not_found_error.
• priority тоже принимает none — задачи без приоритета (priority=none,low = «нет приоритета или low»).
• assignee_id принимает спец-значение none — задачи без исполнителя. Его можно смешивать с id пользователей: assignee_id=user_6594a1b2c3d4e5f6a7b8c9d1,none (либо этот пользователь, либо никто).
• due_date_from / due_date_to принимают YYYY-MM-DD (трактуется как начало / конец этих суток, UTC) или полный ISO-8601 datetime. Задачи без дедлайна никогда не попадают под диапазон.
• due_date=none возвращает только задачи без дедлайна. Его нельзя сочетать с due_date_from / due_date_to (400 validation_error).

Рецепты типовых запросов (задачи без исполнителя, просроченные, без приоритета) — в Фильтрации задач. Полный список параметров со схемами — в справочнике API.

Очистка полей

PATCH-эндпоинты различают две вещи: не переданное поле остаётся без изменений, а поле со значением null очищается — но только там, где «без значения» осмысленно:

Эндпоинт	Поля, принимающие null	Эффект
PATCH /tasks/:id	priority, due_date, description, assignee_ids, reporter_ids, tag_ids	Очищает значение (assignee_ids: null = никто; tag_ids/reporter_ids: то же, что [])
PATCH /tasks/:id/subtasks/:id	assignee_id, due_date	Снимает исполнителя / дедлайн
PATCH /scheduled-events/:id	description, location, reminder_minutes_before	Очищает текст / снимает напоминание

Всё остальное — non-clearable: null в обязательное поле (title, task_status_id, start_at, …) вернёт 400 validation_error, а не будет молча проигнорирован. Чтобы сбросить числовую оценку — отправьте 0; чтобы очистить значение отдельного custom field — передайте его элемент в custom_fields со значением null.

Обратите внимание на отличие от фильтров: в query-параметрах GET /tasks JSON-null не существует, поэтому ту же роль играет спец-значение none (assignee_id=none, priority=none, due_date=none) — см. Фильтрацию задач.

Идемпотентность

POST-запросы (создание) принимают заголовок Idempotency-Key. Отправьте уникальный ключ (до 255 символов — хорошо подойдёт UUID), чтобы повторённый запрос не смог создать дубликат:

curl -X POST https://api.bordio.com/public/v1/tasks \
  -H "Authorization: Bearer brd_sk_live_..." \
  -H "Idempotency-Key: 6a2918cf-f58b-0a1d-3878-66ee00000001" \
  -H "Content-Type: application/json" \
  -d '{ "title": "New task" }'

Как это работает:

• Тот же ключ, то же тело → возвращается сохранённый результат; ничего нового не создаётся.
• Тот же ключ, другое тело → 409 conflict_error (already_exists).
• Тот же ключ, пока первый запрос ещё в процессе выполнения → 409 conflict_error — повторите после завершения первого.
• Ключи запоминаются на 24 часа, затем истекают — повторное использование ключа после этого считается совершенно новым запросом.
• Ключ привязан к своему эндпоинту (и рабочему пространству): тот же ключ на другом эндпоинте независим.
• Только POST идемпотентен через этот заголовок. PATCH/DELETE — нет: PATCH безопасно повторять по своей природе, поскольку он устанавливает поля в значения, которые вы отправляете.