POST/v1/push/sources/{source_id}/documents

Слање документа (креирање или замена)

push_upsert_document

Креира или замењује документ по external_id. Са JSON телом пошаљите садржај у content (content_type: html, markdown или text, до 5 MB). Са multipart/form-data пошаљите фајл у делу file (до 100 MB, исти формати као за отпремање у базу знања) и метаподатке у делу document (JSON истог облика без content) или као засебна поља external_id, title, url, path, tags. sync_number је број отворене синхронизације. Без њега документ се уписује одмах (директно креирање или замена), али га следећа потпуна синхронизација брише ако се поново не пошаље. Поновно слање истог документа враћа unchanged (идемпотентно). Документ постаје картица при следећој синхронизацији извора (у року од једног минута; унутар отворене синхронизације – после њеног затварања). Од верзије 1.62.0: поља картице (metadata, category, verifiers, verify_interval_days), фајл из отпремања у деловима (upload_id) и прилози (attachments); одговор садржи status и card_id (резултат документа). Ограничење броја докумената извора зависи од плана.

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

Пошаљите API кључ у заглављу Authorization: Authorization: Bearer <кључ>.

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

source_idintegerобавезно

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

sync_numberinteger

Параметри заглавља

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

Објекат: PushDocument

external_idstringобавезно
Ваш стабилни ID документа. Слање истог идентификатора замењује документ.
length ≤ 512
titlestringобавезно
length ≤ 500
urlstring
Линк на документ у вашем систему (http или https).
contentstring
Садржај (до 5 MB).
content_typestring
Дозвољене вредности: htmlmarkdowntext
Подразумевано: "html"
patharray of string | string
Фолдери документа: низ назива или стринг раздвојен знаком „/“ (до 10 нивоа).
permissionsPushPermissions
tagsarray of string
items ≤ 50
author_emailstring
Аутор. Постаје власник картице ако је корисник платформе Sursa.
updated_atstring (date-time)
Време измене у вашем систему (део верзије документа).
metadataMetadataPatch
metadata картице документа (од верзије 1.62.0): објекат замењује претходни објекат картице, {} уклања све парове; без поља metadata метаподаци картице се не мењају.
categorystring
Категорија картице: кључ категорије организације (GET /v1/categories), од верзије 1.62.0.
length ≤ 64
verifiersPushVerifiers
verify_interval_daysinteger
Интервал провере картице у данима (од верзије 1.62.0); без њега – интервал извора.
≥ 1, ≤ 3650
upload_idstring
Фајл документа из отпремања у деловима (upl_…, од верзије 1.62.0) уместо content. Отпремање се користи једном; поновно слање истог документа са истим upload_id га не троши. Док отпремање у деловима није доступно у инсталацији, документ се одбија са разлогом file_rejected.
length ≤ 64
attachmentsarray of string
Прилози документа као отпремања у деловима (upl_…, од верзије 1.62.0): сваки постаје засебна картица извора са истим фолдером, дозволама и пољима картице. Прилог који недостаје у новој верзији документа се архивира.
items ≤ 20

multipart/form-data

filestring (binary)обавезно
documentstring
JSON метаподаци документа (поља PushDocument без content).
external_idstring
titlestring
urlstring
pathstring
tagsstring

Одговори

200Уписано

Заглавља одговора

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

Објекат: PushDocumentResult

external_idstringобавезно
resultstringобавезно
skipped: документ из пакета atomic није примењен јер је други документ одбијен (од верзије 1.62.0).
Дозвољене вредности: createdupdatedunchangeddeletednot_founderrorskipped
versionstring
Верзија документа (SHA-256 садржаја и метаподатака).
errorstring
Разлог (када је result = error).
statusPushDocumentStatusValue
card_idstring | null
Картица документа, ако је већ уписана (од верзије 1.62.0).
reasonPushDocumentReason

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Акредитиви нису послати (ни колачић сесије ни 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Радња није дозвољена: улога није довољна, нема приступа колекцији или картици, захтев се извршава у режиму „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

Кодови грешака

Кодови које ова операција може да врати у error.code, поред општих кодова сваког захтева.

Безбедни поновни покушаји

Уз сваки POST и PATCH захтев пошаљите заглавље Idempotency-Key (на пример UUID). Поновни покушај са истим кључем у року од 24 сата враћа сачувани одговор уместо да поново изврши захтев.

Ограничења учесталости

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

← sources · API референца

curl -X POST 'https://api.sursa.com/v1/push/sources/1/documents' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"crm-1042","title":"Refund policy"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Испробајте

API кључ

Кључ остаје у меморији овог језичка прегледача и шаље се само на https://api.sursa.com.

Захтеви раде са стварним подацима ваше организације.

Idempotency-Key header

source_id path *

sync_number query

Idempotency-Key

Ако је поље празно, за сваки захтев се генерише нови кључ.

Тело захтева (JSON)