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

Wysyłanie dokumentu (utworzenie lub zastąpienie)

push_upsert_document

Tworzy lub zastępuje dokument według external_id. W JSON wyślij treść w content (content_type: html, markdown lub text, do 5 MB). W multipart/form-data wyślij plik w części file (do 100 MB, te same formaty co przy przesyłaniu do bazy wiedzy) i metadane w części document (JSON o tej samej postaci bez content) lub jako osobne pola external_id, title, url, path, tags. sync_number to numer otwartej synchronizacji. Bez niego dokument jest zapisywany od razu (bezpośredni zapis, direct upsert), ale następna pełna synchronizacja go usuwa, chyba że zostanie wysłany ponownie. Ponowne wysłanie tego samego dokumentu zwraca unchanged (idempotentnie). Dokument staje się kartą przy następnej synchronizacji źródła (w ciągu minuty; w ramach otwartej synchronizacji – po jej zamknięciu). Od wersji 1.62.0: pola karty (metadata, category, verifiers, verify_interval_days), plik z przesyłania wieloczęściowego (upload_id) i załączniki (attachments); odpowiedź zawiera status i card_id (wynik dokumentu). Limit dokumentów źródła zależy od planu.

Uwierzytelnianie

Wyślij klucz API w nagłówku Authorization: Authorization: Bearer <klucz>.

Parametry ścieżki

source_idintegerwymagane

Parametry zapytania

sync_numberinteger

Parametry nagłówka

Idempotency-Keystring
Klucz bezpiecznego ponowienia zapisu: od 1 do 255 drukowalnych znaków ASCII; zalecany jest UUID v4 na każdą operację logiczną. Ponowienie z tym samym kluczem w ciągu 24 godzin nie wykonuje operacji ponownie: zwraca zapisaną odpowiedź (status, nagłówki i treść) z nagłówkiem Idempotency-Replayed: true. Ten sam klucz z inną metodą, ścieżką, Content-Type lub treścią zwraca 409 api.idempotency_mismatch; dopóki pierwsze żądanie jest jeszcze wykonywane – 409 api.idempotency_in_progress z Retry-After: 1. Po odpowiedzi 5xx lub 429 klucz zostaje zwolniony, a ponowienie wykonuje operację jeszcze raz. Klucz obowiązuje w obrębie organizacji i wywołującego (klucz API, użytkownik lub klucz własnego źródła).
length ≥ 1, length ≤ 255

Treść żądania

application/json

Obiekt: PushDocument

external_idstringwymagane
Twój stały identyfikator dokumentu. Wysłanie tego samego identyfikatora zastępuje dokument.
length ≤ 512
titlestringwymagane
length ≤ 500
urlstring
Link do dokumentu w Twoim systemie (http lub https).
contentstring
Zawartość (do 5 MB).
content_typestring
Dozwolone wartości: htmlmarkdowntext
Domyślnie: "html"
patharray of string | string
Foldery dokumentu: tablica nazw lub ciąg rozdzielony znakiem „/” (do 10 poziomów).
permissionsPushPermissions
tagsarray of string
items ≤ 50
author_emailstring
Autor. Staje się właścicielem karty, jeśli jest użytkownikiem Sursy.
updated_atstring (date-time)
Czas modyfikacji w Twoim systemie (część wersji dokumentu).
metadataMetadataPatch
metadata karty dokumentu (od 1.62.0): obiekt zastępuje poprzedni obiekt karty, {} usuwa wszystkie pary; bez pola metadata metadane karty się nie zmieniają.
categorystring
Kategoria karty: klucz kategorii organizacji (GET /v1/categories), od 1.62.0.
length ≤ 64
verifiersPushVerifiers
verify_interval_daysinteger
Okres weryfikacji karty w dniach (od 1.62.0); bez niego obowiązuje okres źródła.
≥ 1, ≤ 3650
upload_idstring
Plik dokumentu z przesyłania wieloczęściowego (upl_…, od 1.62.0) zamiast content. Przesyłanie jest używane jednokrotnie; ponowne wysłanie tego samego dokumentu z tym samym upload_id go nie zużywa. Dopóki przesyłanie wieloczęściowe nie jest dostępne w instalacji, dokument jest odrzucany z przyczyną file_rejected.
length ≤ 64
attachmentsarray of string
Załączniki dokumentu jako przesłania wieloczęściowe (upl_…, od 1.62.0): każdy staje się osobną kartą źródła z tym samym folderem, uprawnieniami i polami karty. Załącznik, którego brakuje w nowej wersji dokumentu, jest archiwizowany.
items ≤ 20

multipart/form-data

filestring (binary)wymagane
documentstring
Metadane dokumentu w JSON (pola PushDocument bez content).
external_idstring
titlestring
urlstring
pathstring
tagsstring

Odpowiedzi

200Zapisano

Nagłówki odpowiedzi

RateLimit-Policy
Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.
RateLimit
Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).
X-RateLimit-Remaining
Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-Reset
Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.
Idempotency-Replayed
true oznacza, że odpowiedź została odtworzona z odpowiedzi zapisanej dla tego Idempotency-Key: operacja nie została wykonana ponownie.

application/json

Obiekt: PushDocumentResult

external_idstringwymagane
resultstringwymagane
skipped: dokument pakietu atomic nie został zastosowany, bo inny dokument odrzucono (od 1.62.0).
Dozwolone wartości: createdupdatedunchangeddeletednot_founderrorskipped
versionstring
Wersja dokumentu (SHA-256 zawartości i metadanych).
errorstring
Przyczyna (gdy result = error).
statusPushDocumentStatusValue
card_idstring | null
Karta dokumentu, jeśli została już zapisana (od 1.62.0).
reasonPushDocumentReason

400Żądanie jest nieprawidłowe: wartość parametru lub stan obiektu nie pozwala na to działanie (`detail` zawiera komunikat).

Nagłówki odpowiedzi

RateLimit-Policy
Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.
RateLimit
Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).
X-RateLimit-Remaining
Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-Reset
Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

401Nie przesłano danych uwierzytelniających (ani pliku cookie sesji, ani klucza API) lub nie znaleziono klucza.

Nagłówki odpowiedzi

RateLimit-Policy
Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.
RateLimit
Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).
X-RateLimit-Remaining
Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-Reset
Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

403Działanie jest niedozwolone: rola jest niewystarczająca, brak dostępu do kolekcji lub karty, żądanie jest wykonywane w trybie „View as” albo organizacja jest zawieszona lub usunięta (`detail` to obiekt z `code: org_suspended | org_deleted`).

Nagłówki odpowiedzi

RateLimit-Policy
Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.
RateLimit
Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).
X-RateLimit-Remaining
Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-Reset
Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

404Obiekt nie istnieje lub nie jest dla Ciebie dostępny. API nie potwierdza istnienia obiektu z ograniczonym dostępem.

Nagłówki odpowiedzi

RateLimit-Policy
Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.
RateLimit
Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).
X-RateLimit-Remaining
Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-Reset
Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

409Stan obiektu nie pozwala na to działanie, np. duplikat, trwające indeksowanie lub zadanie, które zostało już przetworzone.

Nagłówki odpowiedzi

RateLimit-Policy
Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.
RateLimit
Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).
X-RateLimit-Remaining
Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-Reset
Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

413Treść żądania przekracza dozwolony rozmiar.

Nagłówki odpowiedzi

RateLimit-Policy
Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.
RateLimit
Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).
X-RateLimit-Remaining
Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-Reset
Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

415Format pliku nie jest obsługiwany.

Nagłówki odpowiedzi

RateLimit-Policy
Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.
RateLimit
Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).
X-RateLimit-Remaining
Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-Reset
Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

422Błąd walidacji: treść lub parametry nie odpowiadają schematowi (`detail` to lista błędów walidacji) albo wartość parametru jest poza zakresem (`detail` zawiera komunikat).

Nagłówki odpowiedzi

RateLimit-Policy
Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.
RateLimit
Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).
X-RateLimit-Remaining
Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-Reset
Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

429Zbyt wiele żądań (`api.rate_limited`), wyczerpano przydział organizacji na minutę, dzień lub miesiąc (`api.quota_exceeded`; `error.details` zawiera `quota`, `limit` i `reset_at`), osiągnięto limit organizacji albo usługa odpowiedzi jest zajęta (`answers.engine_busy`). Odczekaj czas podany w nagłówku `Retry-After`.

Nagłówki odpowiedzi

Retry-After
Liczba sekund oczekiwania przed ponowieniem żądania.
RateLimit-Policy
Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.
RateLimit
Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).
X-RateLimit-Remaining
Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-Reset
Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

Kody błędów

Kody, które ta operacja może zwrócić w error.code, oprócz ogólnych kodów każdego żądania.

Bezpieczne ponawianie

Wysyłaj nagłówek Idempotency-Key (na przykład UUID) z każdym żądaniem POST i PATCH. Ponowienie z tym samym kluczem w ciągu 24 godzin zwraca zapisaną odpowiedź, zamiast ponownie wykonywać żądanie.

Limity częstotliwości

Odpowiedzi zawierają nagłówki RateLimit i RateLimit-Policy oraz starsze X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Odpowiedź 429 ma nagłówek Retry-After w sekundach: odczekaj i ponów żądanie.

← sources · Dokumentacja 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"

Wypróbuj

Klucz API

Klucz zostaje w pamięci tej karty przeglądarki i jest wysyłany tylko do https://api.sursa.com.

Żądania działają na prawdziwych danych Twojej organizacji.

Idempotency-Key header

source_id path *

sync_number query

Idempotency-Key

Gdy to pole jest puste, dla każdego żądania generowany jest nowy klucz.

Treść żądania (JSON)