PUT/v1/cards-by-external-id/{external_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 режиму «View as» для сесії. Встановлюється через 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Дію не дозволено: роль не має достатніх прав, немає доступу до колекції чи картки, запит виконується в режимі «View as» або організацію призупинено чи видалено (`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)