GET/v1/jobs/stream
Strumień zmian zadań (SSE)
jobs_stream
Server-Sent Events: migawka bieżącego pakietu, a następnie zmiany zadań organizacji (etap, procent, nazwa pliku).
Każde zdarzenie ma id, czyli kursor w postaci znacznika czasu. Po ponownym połączeniu przeglądarka wysyła go w Last-Event-ID (lub klient przekazuje ?since=), a migawka jest uzupełniana o wszystko, co zmieniło się w czasie przerwy w połączeniu.
Uruchomienia źródeł mogą też generować zdarzenia {"type": "source", "source": {"id", "status", "updated_at"}} bez kursora ID. status to etap trwającej synchronizacji (listing, syncing, retry) lub jej wynik (ok, partial, error). Pobrane pliki są indeksowane przez zadania i przychodzą jako zdarzenia job, tak jak przesłane pliki.
Uwierzytelnianie
Wyślij klucz API w nagłówku Authorization: Authorization: Bearer <klucz>.
Parametry zapytania
sincestring | nullKursor wznowienia (czas ISO ze strefą czasową), alternatywa dla
Last-Event-ID.
Parametry nagłówka
X-View-AsstringTylko dla kluczy API z rolą
admin. Wykonuje żądanie jako profil dostępu<profile>[:viewer|verifier|editor], np.employee:viewer. Klucz instalacji nie może używać tego nagłówka (403).Last-Event-IDstring | nullID ostatniego odebranego zdarzenia (ponowne połączenie EventSource). Strumień zaczyna się od zdarzeń następujących po nim.
Parametry cookie
kb_view_asstringPlik cookie trybu „View as” dla sesji.
POST /auth/view-asgo ustawia, aDELETE /auth/view-asusuwa.
Odpowiedzi
200`text/event-stream`. Pierwsze pole to `retry: 3000`, następnie zdarzenie `snapshot` z bieżącymi zadaniami i podsumowaniem, a po nim zdarzenia `job` (zmieniło się zadanie) i `summary` (podsumowanie po zmianie statusu). Każde zdarzenie zawiera `id:` – kursor w postaci znacznika czasu (ISO). Po ponownym połączeniu przeglądarka wysyła go w `Last-Event-ID` (lub klient przekazuje go w `?since=`), a migawka jest uzupełniana o wszystko, co zmieniło się w czasie przerwy w połączeniu (do 24 godzin wstecz). Po każdych 15 sekundach ciszy serwer wysyła komentarz `: keep-alive`. Nagłówki odpowiedzi: `Cache-Control: no-cache`, `X-Accel-Buffering: no`.
Nagłówki odpowiedzi
RateLimit-PolicyObowiązujące limity w formacie projektu IETF
draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami"<name>";q=<quota>;w=<window in seconds>.keyto częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest touser, bez danych uwierzytelniającychip);minute,dayimonthto przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.RateLimitCo pozostało z każdego limitu w
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimit najbardziej restrykcyjnej pozycji w
RateLimit-Policy(tej, w której zostało najmniej żądań).X-RateLimit-RemainingLiczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-ResetLiczba sekund do odnowienia najbardziej restrykcyjnego limitu.
text/event-stream
401Nie przesłano danych uwierzytelniających (ani pliku cookie sesji, ani klucza API) lub nie znaleziono klucza.
Nagłówki odpowiedzi
RateLimit-PolicyObowiązujące limity w formacie projektu IETF
draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami"<name>";q=<quota>;w=<window in seconds>.keyto częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest touser, bez danych uwierzytelniającychip);minute,dayimonthto przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.RateLimitCo pozostało z każdego limitu w
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimit najbardziej restrykcyjnej pozycji w
RateLimit-Policy(tej, w której zostało najmniej żądań).X-RateLimit-RemainingLiczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-ResetLiczba sekund do odnowienia najbardziej restrykcyjnego limitu.
application/json
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-PolicyObowiązujące limity w formacie projektu IETF
draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami"<name>";q=<quota>;w=<window in seconds>.keyto częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest touser, bez danych uwierzytelniającychip);minute,dayimonthto przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.RateLimitCo pozostało z każdego limitu w
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimit najbardziej restrykcyjnej pozycji w
RateLimit-Policy(tej, w której zostało najmniej żądań).X-RateLimit-RemainingLiczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-ResetLiczba sekund do odnowienia najbardziej restrykcyjnego limitu.
application/json
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-PolicyObowiązujące limity w formacie projektu IETF
draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami"<name>";q=<quota>;w=<window in seconds>.keyto częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest touser, bez danych uwierzytelniającychip);minute,dayimonthto przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.RateLimitCo pozostało z każdego limitu w
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimit najbardziej restrykcyjnej pozycji w
RateLimit-Policy(tej, w której zostało najmniej żądań).X-RateLimit-RemainingLiczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-ResetLiczba sekund do odnowienia najbardziej restrykcyjnego limitu.
application/json
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-AfterLiczba sekund oczekiwania przed ponowieniem żądania.
RateLimit-PolicyObowiązujące limity w formacie projektu IETF
draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami"<name>";q=<quota>;w=<window in seconds>.keyto częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest touser, bez danych uwierzytelniającychip);minute,dayimonthto przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.RateLimitCo pozostało z każdego limitu w
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimit najbardziej restrykcyjnej pozycji w
RateLimit-Policy(tej, w której zostało najmniej żądań).X-RateLimit-RemainingLiczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-ResetLiczba sekund do odnowienia najbardziej restrykcyjnego limitu.
application/json
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.
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.