Developers

FocusWork API

REST + GraphQL + Webhooks. Типизированные SDK, OpenAPI 3.1 спецификация, rate-limit честный — не «10 000 в день на всех».

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

Получите API-ключ в Настройки → Разработчикам → API-ключи. Первый запрос:

curl https://api.focuswork.pro/v1/users/me \
  -H "Authorization: Bearer ft_live_abc...xyz"

Ответ — JSON с профилем пользователя. Если 401 — проверьте токен.

Базовые URL

Endpoint	URL
REST	`https://api.focuswork.pro/v1/`
GraphQL	`https://api.focuswork.pro/v1/graphql`
Webhooks (outgoing)	Настраиваются в воркспейсе
OpenAPI спецификация	`https://api.focuswork.pro/v1/openapi.json`

Аутентификация

Bearer-токен в заголовке Authorization. Два типа токенов:

Personal access tokens — выпускаются пользователем для своих скриптов, scope = всё что доступно пользователю.
OAuth 2.0 apps — для интеграций с user-consent flow (PKCE поддерживается).

Rate limits

Тариф	REST/GraphQL	Webhooks доставки
Free	60 / минуту	—
Pro	1 000 / минуту	10 000 / день
Business	5 000 / минуту	100 000 / день
Enterprise	Custom (часто 50 000+ / минуту)	Без лимита

Заголовок X-RateLimit-Remaining в каждом ответе. При превышении — 429 с Retry-After.

Основные ресурсы

Метод	Путь	Что делает
`GET`	`/v1/users/me`	Текущий пользователь
`GET`	`/v1/projects`	Список проектов воркспейса
`POST`	`/v1/projects`	Создать проект
`GET`	`/v1/tasks?project=...`	Задачи с фильтрами
`POST`	`/v1/tasks`	Создать задачу
`PUT`	`/v1/tasks/{id}`	Полное обновление
`PATCH`	`/v1/tasks/{id}`	Частичное обновление
`POST`	`/v1/sync/push`	Bulk-загрузка изменений (CRDT)
`GET`	`/v1/sync/pull?cursor=...`	Long-poll для real-time
`POST`	`/v1/files`	Загрузить файл (multipart)
`GET`	`/v1/search?q=...`	Полнотекстовый поиск
`GET`	`/v1/audit-log`	Enterprise audit log

Webhooks

События доставляются с HMAC-SHA256 подписью в заголовке X-FocusWork-Signature. Ретрай-policy: exponential backoff (1с → 5с → 30с → 5мин → 1ч → 6ч), всего 6 попыток. После — dead-letter queue в админке.

События:

task.created, task.updated, task.completed, task.deleted
project.created, project.archived
comment.added, comment.deleted
user.joined, user.removed
integration.connected, integration.failed

SDK

JavaScript / TypeScript — npm i @focuswork/sdk (официальный)
Python — pip install focuswork (официальный)
Go — go get github.com/focuswork/sdk-go (официальный)
Ruby — gem install focuswork-rb (community, поддерживается @rb-fw)
PHP — composer require focuswork/sdk (community)

Все SDK поддерживают automatic retries, идемпотентные ключи, типизированные responses.