API Таски v1.0

Обзор

API построено на GraphQL: все операции идут одним POST-запросом на адрес выше. Тело запроса — JSON с полями query и (необязательно) variables.

Ключевые свойства, которые стоит знать до начала работы:

Ключи доступа

Ключ выпускается в интерфейсе Таски. Где именно — зависит от того, к какому пространству нужен доступ:

Ключ выглядит так:

taska_k3f9a1c7b204_x8Qm2LpZv...

Он состоит из трёх частей: префикса taska, публичного идентификатора ключа и секрета. Публичный идентификатор виден в интерфейсе и в журнале обращений — по нему удобно понять, какая именно интеграция сделала запрос.

Авторизация

Ключ передаётся в заголовке Authorization:

Authorization: Bearer taska_k3f9a1c7b204_x8Qm2LpZv...

Если ваш прокси или платформа перехватывает Authorization, используйте запасной заголовок — он равнозначен:

X-Taska-Api-Key: taska_k3f9a1c7b204_x8Qm2LpZv...

Проверить ключ можно запросом viewer — он не требует никаких прав и возвращает контекст, в котором работает ключ:

query {
  viewer {
    tokenName
    tokenPrefix
    scopes
    spaceId
    spaceTitle
    actingUserEmail
    expiresAt
    rateLimitPerMinute
  }
}

Когда ключ перестаёт работать

Запрос вернёт 401 с кодом unauthenticated, если:

• ключ отозван или удалён;
• истёк заданный при выпуске срок действия;
• запрос пришёл с адреса вне белого списка IP (если список задан);
• пользователь, от имени которого выпущен ключ, покинул пространство или был из него исключён. Это проверяется на каждом запросе: отключение сотрудника автоматически закрывает его интеграции, без ручной чистки ключей.

Быстрый старт

curl -s http://taska.be/api/v1/graphql \
  -H "Authorization: Bearer $TASKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ projects { totalCount items { id title type } } }"}'

async function taska(query, variables = {}) {
  const response = await fetch('http://taska.be/api/v1/graphql', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.TASKA_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query, variables }),
  });

  const payload = await response.json();

  // GraphQL отвечает 200 даже на прикладные ошибки — проверяем тело ответа,
  // а не только HTTP-статус.
  if (payload.errors?.length) {
    const first = payload.errors[0];
    throw new Error(`[${first.extensions?.code}] ${first.message}`);
  }

  return payload.data;
}

const { createTask } = await taska(`
  mutation NewTask($statusId: ID!, $title: String!) {
    createTask(statusId: $statusId, title: $title) {
      task { id title status { title } }
    }
  }
`, { statusId: '42', title: 'Задача из внешнего сервиса' });

import os
import requests

ENDPOINT = "http://taska.be/api/v1/graphql"
SESSION = requests.Session()
SESSION.headers["Authorization"] = f"Bearer {os.environ['TASKA_API_KEY']}"


def taska(query: str, **variables):
    response = SESSION.post(ENDPOINT, json={"query": query, "variables": variables})
    payload = response.json()

    if payload.get("errors"):
        error = payload["errors"][0]
        code = (error.get("extensions") or {}).get("code")
        raise RuntimeError(f"[{code}] {error['message']}")

    return payload["data"]


data = taska(
    """
    query OpenTasks($limit: Int) {
      tasks(filter: {isCompleted: false}, orderBy: DEADLINE, orderDirection: ASC, limit: $limit) {
        totalCount
        items { id title deadline performer { fullName } }
      }
    }
    """,
    limit=50,
)

Права доступа

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

Права на чтение и на запись независимы: tasks:write не включает tasks:read. Это сделано специально — так можно выдать ключ, который только создаёт задачи из внешней системы, но не может выгрузить содержимое пространства.

Ошибки

Ошибки приходят в стандартном для GraphQL виде. Ориентируйтесь на extensions.code — это стабильный машиночитаемый идентификатор. Текст message предназначен человеку и может меняться.

{
  "data": null,
  "errors": [
    {
      "message": "Ключу не хватает права «tasks:write». Выданные права: tasks:read.",
      "extensions": {
        "code": "forbidden",
        "required_scope": "tasks:write",
        "granted_scopes": ["tasks:read"]
      }
    }
  ]
}

Пагинация

Все списки устроены одинаково: аргументы limit и offset, ответ одной формы.

query Page($offset: Int!) {
  tasks(limit: 100, offset: $offset) {
    items { id title }
    totalCount   # всего под фильтр
    hasMore      # есть ли следующая страница
    limit        # фактически применённый размер страницы
    offset
  }
}

Значение limit по умолчанию — 50, максимум — 200. Запрос большего значения не даст ошибки: он будет тихо уменьшен до максимума, а фактический размер вернётся в поле limit. Проверяйте его, если нарезаете выгрузку по страницам.

Полная выгрузка выглядит так:

async function fetchAll(query, variables = {}) {
  const all = [];
  let offset = 0;

  for (;;) {
    const page = (await taska(query, { ...variables, offset })).tasks;
    all.push(...page.items);
    if (!page.hasMore) break;
    // Шагаем на фактический limit, а не на запрошенный — сервер мог его урезать.
    offset += page.limit;
  }

  return all;
}

Лимиты и ограничения

Частота запросов

Лимит задаётся для каждого ключа отдельно (по умолчанию 120 запросов в минуту). Мутация расходует бюджет как два обычных запроса — она пишет в базу и рассылает уведомления.

Каждый ответ содержит текущее состояние счётчика:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 96
X-RateLimit-Reset: 34

При превышении вернётся 429 и заголовок Retry-After. Правильная реакция — подождать указанное число секунд, а не повторять сразу.

Сложность запроса

Максимальная вложенность — 12 уровней. Связи в схеме цикличны (проект → доски → статусы → доска → проект), и без ограничения одним запросом можно было бы вытянуть всю базу.

Лимиты тарифа

Количество проектов, досок и статусов ограничено тарифом пространства ровно так же, как в интерфейсе. При исчерпании вернётся quota_exceeded с деталями.

Безопасность

Модель данных

Иерархия сущностей внутри пространства:

Space (пространство — привязано к ключу)
├── Member                     участники
└── Project                    проект
    ├── Board                  канбан-доска
    │   └── Status             колонка доски
    │       └── Task           задача
    │           ├── Todo       пункт чек-листа
    │           ├── Tag        тег
    │           └── FieldValue значение пользовательского поля
    ├── TaskField              описание поля задач проекта
    ├── Epic                   эпик (строка диаграммы Гантта)
    │   └── EpicDependency     зависимость между эпиками
    └── Storage                хранилище базы знаний
        ├── Folder             папка (может быть вложенной)
        └── Page               страница

Полезные детали:

• Задача может существовать вне доски — во «входящих» пространства. Такие задачи ищутся фильтром { inInbox: true }.
• Тип проекта (simple, complex, storage, roadmap) определяет, что создаётся автоматически. У simple сразу появляется доска с набором статусов, у storage — хранилище базы знаний.
• Поля задач бывают системными (у них заполнен builtinKey: описание, исполнитель, статус, приоритет, дедлайн, теги, эпик) и пользовательскими. Системные нельзя удалять и переименовывать — только скрывать и переставлять.
• Допустимые значения всех перечислимых полей (приоритеты, цвета, иконки, типы) отдаёт запрос metadata. Запросите его один раз при настройке интеграции.

Блочный редактор

Страница базы знаний бывает трёх типов, и тип задаётся один раз, при создании (pageType): wysiwyg — форматированный HTML, markdown — обычный markdown, blocks — блочный редактор. Последний и есть основной формат статей: из него собираются таблицы, диаграммы, колонки, чек-листы, карточки задач, живые выборки задач и всё остальное, чего в тексте выразить нельзя.

Содержимое блочной страницы лежит в том же поле content, но это строка с JSON-документом. API принимает её как есть и не разбирает: формат — контракт редактора, и вся ответственность за него на том, кто пишет. Поэтому ниже он описан целиком.

Документ

{
  "version": 1,
  "blocks": [
    { "id": "blk_Qa7vMx0Lp2", "type": "heading",   "data": { "level": 1, "spans": [ { "text": "Регламент" } ] } },
    { "id": "blk_8fKd1sZbNe", "type": "paragraph", "data": { "spans": [ { "text": "Как обрабатывать заявки." } ] } }
  ]
}

• id — стабильный идентификатор блока, blk_ + 10 символов base62. По нему адресуются правки, якоря оглавления и ссылка диаграммы на таблицу, поэтому уникальность обязательна: копируя блок, выдайте копии новый id.
• type — тип блока из таблицы ниже. Неизвестный тип редактор превращает в пустой абзац: содержимое такого блока теряется молча.
• data — поля блока. Набор зависит от типа; отсутствующие поля дополняются значениями по умолчанию при чтении.
• version — версия формата документа. Сейчас всегда 1.

Текст: сегменты и метки

Форматированный текст — это не HTML, а массив сегментов. Каждый сегмент — кусок текста с набором меток:

"spans": [
  { "text": "Обычный текст, " },
  { "text": "жирный", "marks": [ { "type": "bold" } ] },
  { "text": " и ссылка", "marks": [ { "type": "link", "href": "https://taska.be" } ] }
]

Кроме плоского spans у некоторых блоков есть отдельные текстовые поля — caption, title, body, summary. Все они устроены одинаково: объект { "spans": [ … ] }.

Типы блоков

Что важно знать про отдельные блоки:

• Диаграмма своих цифр не хранит. Она ссылается полем sourceId на блок-таблицу в этой же статье, а labelCol и valueCols — индексы её колонок (с нуля). Сначала вставьте таблицу, потом диаграмму с её id.
• Оглавление вычисляется на лету из заголовков статьи — записывать в него пункты не нужно и некуда.
• Карточка и выборка задач — живые. В документе лежат только идентификаторы и фильтры; названия, статусы и исполнители подтягиваются при открытии статьи.
• Картинки и файлы должны быть уже загружены. В документе хранится slug файла, а загрузка идёт не через GraphQL. Возьмите slug уже загруженного файла запросом files.
• Встраиваются только известные сервисы — Figma, Miro, YouTube, RUTUBE, VK Видео, Vimeo, Loom, документы Google и Яндекса, CodePen. Прочие ссылки блок покажет карточкой: почти все сайты запрещают встраивать себя во фрейм.
• Код — плоский текст. Подсветка вычисляется при рендере, поэтому меток внутри code нет и быть не может.
• Переиспользуемый фрагмент — отдельная сущность хранилища: один и тот же текст, показанный в нескольких статьях. В публичном API его нет, в документе хранится только fragmentId.

Вложенность

Вкладывать блоки умеют ровно два типа — layout (2–3 колонки) и toggle (одна сворачиваемая секция). Оба хранят вложенное в data.cells — массиве списков блоков того же формата, что и blocks документа:

{
  "id": "blk_Lc93pQmT1x",
  "type": "layout",
  "data": {
    "columns": 2,
    "ratios": [1, 1],
    "cells": [
      [ { "id": "blk_a1", "type": "paragraph", "data": { "spans": [ { "text": "Слева" } ] } } ],
      [ { "id": "blk_b2", "type": "paragraph", "data": { "spans": [ { "text": "Справа" } ] } } ]
    ]
  }
}

• Колонки нельзя вкладывать в колонки, а в сворачиваемую секцию — ни колонки, ни другую секцию.
• Длина cells равна columns; у toggle ячейка всегда одна.
• Пустая ячейка при чтении получает пустой абзац — иначе в неё некуда поставить курсор.
• Вложенность пунктов списка — это не дерево, а поле level у пункта (0–4).

Ограничения

Как писать блочную статью

Содержимое передаётся строкой, поэтому документ удобнее собрать объектом и сериализовать в переменную запроса — экранировать JSON внутри JSON руками не нужно:

mutation NewArticle($storageId: ID!, $content: String!) {
  createPage(
    storageId: $storageId
    title: "Регламент обработки заявок"
    pageType: "blocks"
    content: $content
  ) {
    page { id title pageType }
  }
}

{
  "storageId": "4",
  "content": "{\"version\":1,\"blocks\":[ … ]}"
}

Небольшая статья целиком — заголовок, текст, таблица и диаграмма по ней:

{
  "version": 1,
  "blocks": [
    { "id": "blk_h1", "type": "heading",   "data": { "level": 1, "spans": [ { "text": "Выручка за квартал" } ] } },
    { "id": "blk_p1", "type": "paragraph", "data": { "spans": [
        { "text": "Подробности — в " },
        { "text": "соседней статье", "marks": [ { "type": "pageLink", "pageId": "31", "snapshot": "Методика расчёта" } ] },
        { "text": ". Ответственный: " },
        { "text": "Иван", "marks": [ { "type": "mention", "userId": "7", "snapshot": "Иван Петров" } ] }
      ] } },
    { "id": "blk_t1", "type": "table", "data": {
        "widths": [1, 1],
        "headerRow": true,
        "headerCol": false,
        "rows": [
          { "id": "row_1", "cells": [
              { "id": "c11", "spans": [ { "text": "Месяц" } ],   "align": "left",  "valign": "top" },
              { "id": "c12", "spans": [ { "text": "Выручка" } ], "align": "right", "valign": "top" } ] },
          { "id": "row_2", "cells": [
              { "id": "c21", "spans": [ { "text": "Январь" } ],  "align": "left",  "valign": "top" },
              { "id": "c22", "spans": [ { "text": "120" } ],     "align": "right", "valign": "top" } ] }
        ] } },
    { "id": "blk_c1", "type": "chart", "data": {
        "sourceId": "blk_t1", "kind": "bar", "labelCol": 0, "valueCols": [1],
        "height": 320, "legend": true, "stacked": false,
        "caption": { "spans": [ { "text": "Помесячно, тыс. ₽" } ] } } }
  ]
}

Как править существующую статью

Гранулярных операций над блоками в публичном API нет: правка — это «прочитать content, изменить нужный блок, записать документ целиком». Блок ищите по id, а не по позиции: позиции меняются при каждом редактировании в интерфейсе.

query Read($id: ID!) {
  page(id: $id) { id pageType content updatedAt }
}

mutation Write($id: ID!, $content: String!) {
  updatePage(id: $id, content: $content) { page { id updatedAt } }
}

Тип страницы при этом менять нельзя: markdown-строка в блочной странице покажется одним абзацем, а JSON-документ в markdown-странице — простынёй фигурных скобок. Если формат не тот, заведите новую страницу.

Рецепты

Создать задачу в конкретной колонке

Достаточно указать statusId — доска и проект определяются автоматически:

mutation {
  createTask(
    statusId: "42"
    title: "Проверить заявку №1043"
    description: "Пришла из внешней системы"
    priority: "second"
    deadline: "2026-08-15T12:00:00+03:00"
    performerId: "7"
    tagIds: ["3", "5"]
  ) {
    task { id title status { title } performer { fullName } }
  }
}

Создать задачу во «входящих» пространства

mutation {
  createTask(title: "Разобрать позже") {
    task { id }
  }
}

Найти нужную колонку по названию

Идентификаторы статусов удобно один раз получить и закешировать у себя — они не меняются:

query {
  boards(projectId: "12") {
    items {
      id
      title
      statuses { id title icon }
    }
  }
}

Передвинуть задачу и закрыть её

mutation Advance($id: ID!, $statusId: ID!) {
  moveTask(id: $id, statusId: $statusId, position: 1) {
    task { id status { title } }
  }
}

mutation Finish($id: ID!) {
  completeTask(id: $id) {
    rescheduled           # true — задача повторяющаяся и перенесена на след. итерацию
    task { isCompleted completedAt }
  }
}

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

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

mutation {
  clearDeadline: updateTask(id: "301", deadline: null) { task { deadline } }
  unassign:      updateTask(id: "302", performerId: null) { task { performer { id } } }
}

Записать значения пользовательских полей

query FieldsOfProject {
  taskFields(projectId: "12") {
    items { id title fieldType options builtinKey }
  }
}

mutation {
  setTaskFieldValues(
    taskId: "301"
    values: [
      { fieldId: "8",  value: "ООО «Ромашка»" },        # text
      { fieldId: "9",  value: 14990 },                  # number
      { fieldId: "10", value: "opt_a1b2c3" },           # select — ОДИН id опции
      { fieldId: "11", value: ["opt_x1", "opt_y2"] },   # multiselect — список id
      { fieldId: "12", value: null }                    # очистить значение
    ]
  ) {
    task { fieldValues { fieldId value } }
  }
}

Пустое значение любого типа (null, пустая строка, пустой список) трактуется как «очистить поле»: значение удаляется, а не сохраняется пустым.

Задачи с дедлайном на неделю вперёд

query Upcoming($from: DateTimeScalar!, $to: DateTimeScalar!) {
  tasks(
    filter: { isCompleted: false, deadlineFrom: $from, deadlineTo: $to }
    orderBy: DEADLINE
    orderDirection: ASC
    limit: 200
  ) {
    totalCount
    items {
      id title deadline
      project { title }
      performer { fullName email }
    }
  }
}

Завести страницу в базе знаний

mutation {
  createPage(
    storageId: "4"
    title: "Регламент обработки заявок"
    pageType: "markdown"
    content: "## Шаг 1\n\nПроверить реквизиты."
  ) {
    page { id title pageType }
  }
}

Так создаётся простая markdown-страница. Для полноценной статьи — с таблицами, диаграммами, колонками, чек-листами и карточками задач — нужен pageType: "blocks" и JSON-документ в content: формат описан в разделе Блочный редактор. Тип страницы фиксируется при создании и потом не меняется.

Инкрементальная синхронизация

Чтобы не выкачивать всё пространство при каждом прогоне, используйте фильтр updatedFrom. Он есть у задач, проектов и страниц и отдаёт всё, что изменилось после указанного момента.

query Changed($since: DateTimeScalar!, $offset: Int!) {
  tasks(
    filter: { updatedFrom: $since }
    orderBy: UPDATED
    orderDirection: ASC
    limit: 200
    offset: $offset
  ) {
    items { id title updatedAt isCompleted status { id } }
    hasMore
    limit
  }
}

Удаления через updatedFrom не приходят: удалённый объект просто перестаёт появляться в выдаче. Если для вас важны удаления, сверяйте набор идентификаторов со своей копией.

Справочник: запросы

Список собран прямо из работающей схемы, поэтому не может устареть. Полное описание типов — в SDL-схеме; её же удобно скормить генератору типизированных клиентов.

Полный список запросов с аргументами и возвращаемыми типами доступен в SDL-схеме и подгружается в интерактивном виде после загрузки страницы.

Справочник: мутации

Полный список мутаций с аргументами и возвращаемыми типами доступен в SDL-схеме и подгружается в интерактивном виде после загрузки страницы.