Перейти к содержанию
Sursa для разработчиков

POST/v1/drafts

Создать черновик

create_draft

Создаёт черновик новой карточки (collection, нужно COLLECTION_CREATE_CARDS) или правки существующей карточки (card_id, нужно CARD_EDIT; заголовок, теги и текст берутся из последней версии, если не заданы). Автор становится первым соавтором. У пользователя может быть один активный черновик на карточку: повторный запрос возвращает 409 drafts.exists с draft_id в details (продолжайте в этом черновике через PATCH). scheduled_publish_at назначает публикацию по расписанию. Ключ API указывает автора черновика в author_id (начиная с 1.62.0).

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

Передайте ключ API в заголовке Authorization: Authorization: Bearer <ключ>.

Параметры заголовков

  • Idempotency-Keystring

    Ключ для безопасного повтора записи: от 1 до 255 печатных символов ASCII; рекомендуется UUID v4 на каждую логическую операцию. Повтор с тем же ключом в течение 24 часов не выполняет операцию заново: он возвращает сохранённый ответ (статус, заголовки и тело) с заголовком Idempotency-Replayed: true. Тот же ключ с другим методом, путём, Content-Type или телом — ответ 409 api.idempotency_mismatch; пока первый запрос ещё выполняется — 409 api.idempotency_in_progress с Retry-After: 1. После ответа 5xx или 429 ключ освобождается, и повтор выполняет операцию заново. Ключ действует в пределах организации и вызывающей стороны (ключ API, пользователь или ключ своего источника).

    length ≥ 1, length ≤ 255

Тело запроса

application/json

Объект: DraftCreate

  • card_idstring | null
  • collectionstring | null

    Название коллекции для новой карточки (обязательно без card_id).

  • titlestring | null

    length ≤ 200

  • body_markdownstring | null

    length ≤ 500000

  • tagsarray of string | null

    items ≤ 30

  • revision_notestring | null

    length ≤ 1000

  • verify_on_publishboolean

    По умолчанию: false

  • notify_followersboolean

    По умолчанию: false

  • scheduled_publish_atstring (date-time) | null
  • author_idinteger

    Автор черновика, когда вызывает ключ API (начиная с 1.62.0): активный пользователь организации ключа; он становится created_by и первым соавтором. Для ключа обязателен (иначе 422 validation.failed); пользователь другой организации или неактивный пользователь возвращает 404 users.not_found. Права на коллекцию и карточку проверяются у ключа, а не у автора. В сессии автор — вошедший пользователь: другой author_id возвращает 422 validation.failed.

    ≥ 1

Ответы

201Создано

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

  • Idempotency-Replayed

    true — ответ воспроизведён из сохранённого для этого Idempotency-Key: операция повторно не выполнялась.

application/json

Объект: Draft

  • idintegerобязательно
  • org_idintegerобязательно
  • card_idstring | nullобязательно

    Карточка, которую правит черновик; null — черновик новой карточки.

  • collection_idintegerобязательно
  • collectionstringобязательно
  • titlestringобязательно
  • body_markdownstringобязательно
  • tagsarray of stringобязательно
  • base_versioninteger | null

    Версия карточки, с которой начат черновик.

  • scheduled_publish_atstring (date-time) | null
  • workflow_stateDraftWorkflowStateобязательно
  • revision_notestring | null
  • verify_on_publishbooleanобязательно
  • notify_followersbooleanобязательно
  • created_byintegerобязательно
  • updated_byinteger | null
  • created_atstring (date-time)обязательно
  • updated_atstring (date-time)обязательно
  • publish_requested_byinteger | null
  • publish_requested_atstring (date-time) | null
  • approved_byinteger | null
  • approved_atstring (date-time) | null
  • collaboratorsarray of DraftCollaboratorобязательно
  • conflictstring | null

    card_published — карточку опубликовали или изменили после начала черновика; card_deleted — карточку удалили; перечисление расширяемое.

400Запрос неверен: значение параметра или состояние объекта не позволяет выполнить действие (`detail` — сообщение).

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

401Учётные данные не переданы (нет ни cookie сессии, ни ключа API) или ключ не найден.

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

403Действие запрещено: недостаточно прав роли, нет доступа к коллекции или карточке, запрос выполняется в режиме «Смотреть как» либо организация приостановлена или удалена (`detail` — объект с `code: org_suspended | org_deleted`).

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

404Объект не существует или вам недоступен. API не подтверждает существование объекта с ограниченным доступом.

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

409Состояние объекта не позволяет выполнить действие: например, дубль, идёт индексация или задание уже обработано.

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

422Ошибка проверки: тело или параметры не соответствуют схеме (`detail` — список ошибок проверки) либо значение параметра вне допустимого диапазона (`detail` — сообщение).

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

429Слишком много запросов (`api.rate_limited`), квота организации на минуту, день или месяц исчерпана (`api.quota_exceeded`; в `error.details` — `quota`, `limit` и `reset_at`), достигнут лимит организации или сервис ответов занят (`answers.engine_busy`). Подождите время, указанное в заголовке `Retry-After`.

Заголовки ответа

  • Retry-After

    Сколько секунд подождать перед повтором запроса.

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

Коды ошибок

Коды, которые эта операция может вернуть в error.code, помимо общих кодов любого запроса.

Безопасные повторы

Передавайте заголовок Idempotency-Key (например, UUID) с каждым POST и PATCH. Повтор с тем же ключом в течение 24 часов возвращает сохранённый ответ, а не выполняет запрос снова.

Лимиты частоты

В ответах есть заголовки RateLimit и RateLimit-Policy, а также прежние X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. В ответе 429 есть Retry-After в секундах: подождите и повторите запрос.

← drafts · Справочник API