PUT/v1/cards-by-external-id/{external_id}

Создать или заменить карточку по внешнему ID

upsert_card_by_external_id

Создаёт или заменяет карточку по external_id интегратора. Передайте текст как application/json (CardTextUpsert) или файл как multipart/form-data (CardFileUpsertForm, с теми же проверками файла, что и у POST /v1/cards). Если в организации нет карточки с этим external_id, карточка создаётся в коллекции и папке из тела запроса (201). Иначе содержимое заменяется новой версией и индексируется заново так же, как новая версия файла, а сведения карточки (заголовок, теги, владелец, категория, metadata) получают переданные значения (200). Неизменившееся содержимое не создаёт новую версию (status: skipped, reason: unchanged), поэтому повторять запрос безопасно даже без Idempotency-Key. Если передан metadata, он заменяет весь объект. Доступ проверяется как для загрузки, когда карточка создаётся, и как для изменения карточки, когда она заменяется. Содержимое карточки, которая видна вызывающему лишь частично, не заменяется (403 cards.content_whole_access). Карточки источников так не перезаписываются: если external_id принадлежит документу своего источника или найденную карточку ведёт источник, запрос возвращает 409 cards.managed_by_source. Смена содержимого снимает верификацию карточки, как и любая новая версия (причина update).

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

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

Параметры пути

external_idstringобязательно
external_id карточки: строка длиной от 1 до 512 символов, уникальная в пределах организации.
length ≥ 1, length ≤ 512

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

X-View-Asstring
Только для ключей API с ролью admin. Выполняет запрос от имени профиля доступа <profile>[:viewer|verifier|editor], например employee:viewer. Ключ установки этот заголовок использовать не может (403).

Параметры cookie

kb_view_asstring
Cookie режима «Смотреть как» для сессии. POST /auth/view-as устанавливает её, DELETE /auth/view-as — сбрасывает.

Тело запроса

application/json

Объект: CardTextUpsert

titlestring
length ≥ 1, length ≤ 200
bodystringобязательно
Текст карточки в формате content_type.
length ≥ 1, length ≤ 500000
content_typeCardTextContentType
collectionstring
Коллекция по названию — при создании карточки. По умолчанию — коллекция установки по умолчанию.
collection_idinteger | null
Коллекция по ID — при создании карточки. Если передан и collection, приоритет у collection_id.
folder_idstring | null
Папка коллекции для новой карточки, с теми же проверками, что у folder_id при загрузке файла.
length ≤ 64
tagsarray of string | null
items ≤ 30
categorystring | null
length ≤ 60
sensitiveboolean | null
owner_idinteger | null
verify_interval_daysinteger | null
≥ 1, ≤ 3650
metadataMetadataPatch
asyncboolean
true — ответ сразу, а карточка индексируется в очереди; false — ответ после индексации.
По умолчанию: false

multipart/form-data

Объект: CardFileUpsertForm

filestring (application/octet-stream)обязательно
titlestring | null
Заголовок карточки. Если не передан, новая карточка получает имя файла, а существующая сохраняет свой заголовок.
length ≤ 200
collectionstring
collection_idinteger | null
folder_idstring | null
length ≤ 64
tagsstring
Теги через запятую.
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
metadatastring | null
metadata: объект JSON как значение поля формы. Правила — как у MetadataPatch.
asyncboolean
По умолчанию: false

Ответы

200Карточка уже существовала. Её содержимое заменено (`queued`, `ready`, `error`) или не изменилось (`skipped`).

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

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

Объект: UploadResult

statusstringобязательно
Допустимые значения: queuedskippedreadyerror
job_idinteger
jobJob
cardCard | null
duplicatetrue
card_idstring | null
reasonstring
unchanged или an identical file is already indexed.
tablesinteger
timingsobject
Поля
- total_snumber
errorstring

201Карточка создана (`queued` для асинхронного запроса, `ready` или `error` — для синхронного).

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

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

Объект: UploadResult

statusstringобязательно
Допустимые значения: queuedskippedreadyerror
job_idinteger
jobJob
cardCard | null
duplicatetrue
card_idstring | null
reasonstring
unchanged или an identical file is already indexed.
tablesinteger
timingsobject
Поля
- total_snumber
errorstring

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

402Организация достигла лимита тарифа (карточки, хранилище или пользователи). В `error.details` — `kind`, `limit` и `used`.

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

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

413Тело запроса больше допустимого размера.

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

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

415Формат файла не поддерживается.

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

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

503Сервис, от которого зависит этот запрос, временно недоступен. Повторите позже.

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

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, помимо общих кодов любого запроса.

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

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

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

curl -X PUT 'https://api.sursa.com/v1/cards-by-external-id/EXTERNAL_ID' \
  -H "Content-Type: application/json" \
  -d '{"title":"Refund policy","body":"# Refund policy\n\nRefunds are processed within 14 days.","collection":"support"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Попробовать

Ключ API

Ключ хранится только в памяти этой вкладки и отправляется только на https://api.sursa.com.

Запросы работают с настоящими данными вашей организации.

X-View-As header

external_id path *

Тело запроса (JSON)