API и подключения

Подключите пространство к Claude и другим системам: ключи, права, примеры запросов.

По API внешняя система может работать с задачами и проектами пространства: читать проекты и задачи, создавать задачи, менять исполнителя, срок и статус, писать комментарии и заметки. Всё, что она делает, попадает в ленту задач и проектов с пометкой «через API» и именем ключа.

1. Создайте ключ

Владелец пространства открывает «Настройки» → «API» → «Новый ключ». Назовите ключ, например «Claude», выберите права и скопируйте ключ сразу: он показывается один раз. В пространстве хранится только его отпечаток.

2. Вызывайте API

Адрес API: https://masterteam.pro/api/v1. Ключ передаётся в заголовке X-Api-Key, тело запроса — JSON в UTF-8, ответ — JSON.

curl -H "X-Api-Key: YOUR_API_KEY" https://masterteam.pro/api/v1/projects

import requests

BASE = "https://masterteam.pro/api/v1"
HEADERS = {"X-Api-Key": "YOUR_API_KEY"}

projects = requests.get(f"{BASE}/projects", headers=HEADERS).json()
for p in projects["projects"]:
    print(p["id"], p["name"])

const BASE = "https://masterteam.pro/api/v1";
const headers = { "X-Api-Key": "YOUR_API_KEY" };

const res = await fetch(`${BASE}/projects`, { headers });
console.log((await res.json()).projects);

3. Создайте задачу

curl -X POST https://masterteam.pro/api/v1/tasks \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Проверить позиции в Яндексе",
    "project_id": 12,
    "description": "<p>Ключи: <b>купить квартиру</b></p>",
    "assignee_id": 7,
    "due_date": "2026-11-15",
    "priority": "high"
  }'

Идентификаторы проектов берём из GET /projects, участников — из GET /members, полей проекта — из GET /projects/{id}/fields.

Методы и права

Полное описание в формате OpenAPI (его можно загрузить в Postman или сгенерировать клиент): /openapi.json.

Ошибки

401 — ключ неверен или отозван. 403 — у ключа нет права. 404 — нет такого адреса или объекта. 409 — конфликт (см. Idempotency-Key ниже). 412 — объект изменился с тех пор, как вы его прочитали (см. If-Match ниже). 413 — файл слишком большой. 422 — проверьте данные: в ответе поле error объясняет, что исправить. 429 — слишком много запросов: в заголовке Retry-After сколько ждать.

Каждый ответ несёт заголовок X-Request-Id, а ошибка — поля code (например validation_failed, rate_limited) и request_id. Этот номер можно сообщить в поддержку.

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

Создающие запросы (POST) можно отправить с заголовком Idempotency-Key — любая строка от 8 до 100 знаков (латиница, цифры, . _ : -). Если связь оборвалась, отправьте тот же запрос с тем же ключом: вернётся первый ответ, новая запись не создастся. Тот же ключ с другим запросом — ошибка 409. Ключ помнится 24 часа; ответы с ошибкой не запоминаются, поэтому их можно исправить и отправить снова.

Списки и параллельные правки

Списки отдают заголовок X-Total-Count — всего записей. Параметры ?limit= (до 200, по умолчанию 50 при указанном offset) и ?offset= выбирают страницу. Без параметров придёт весь список, как раньше.

Задача и проект отдают заголовок ETag при чтении. Если при изменении (PATCH) передать тот же ETag в заголовке If-Match, а объект за это время поменяли, ответ — 412, и изменение не сохранится. Тогда прочитайте объект заново и повторите правку. Без If-Match правка проходит как обычно.

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

С одним ключом можно сделать 120 запросов в минуту. Больше — ответ 429 и заголовок Retry-After: 60.

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

Ключ действует от имени владельца, но только в его пространстве, и работает только на перечисленных адресах. Храните ключ как пароль: не публикуйте и не вставляйте в код, который видят другие. Если ключ утёк, отзовите его в настройках и создайте новый. Удалять задачи и участников через API нельзя.