Przejdź do treści
Sursa Developers

POST/v1/cards/text

Tworzenie karty tekstowej (Markdown)

create_text_card

Tworzy kartę tekstową z Markdown (kind=text). Jest indeksowana tak samo jak przesłany plik. Z async=true indeksowanie trafia do kolejki: odpowiedź wraca od razu, a postęp jest dostępny w /v1/jobs.

Uwierzytelnianie

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

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

  • X-View-Asstring

    Tylko 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).

Parametry cookie

  • kb_view_asstring

    Plik cookie trybu „View as” dla sesji. POST /auth/view-as go ustawia, a DELETE /auth/view-as usuwa.

Treść żądania

application/json

Obiekt: TextCardRequest

  • titlestringwymagane

    length ≥ 1, length ≤ 200

  • collectionstring

    Domyślnie: "default"

  • body_markdownstring

    Tekst karty w formacie Markdown; content_type go nie dotyczy. Zamiast niego można przekazać body.

    length ≥ 1, length ≤ 500000

  • tagsarray of string | null

    items ≤ 30

  • categorystring | null

    length ≤ 60

  • sensitiveboolean | null
  • owner_idinteger | null
  • asyncboolean

    Domyślnie: false

  • bodystring

    Tekst karty w formacie content_type. Przekaż body albo body_markdown; przekazanie obu zwraca 422 validation.failed.

    length ≥ 1, length ≤ 500000

  • content_typeCardTextContentType
  • collection_idinteger | null

    Kolekcja według ID. Gdy przekazano też collection, pierwszeństwo ma collection_id. Kolekcja, która nie istnieje w organizacji lub nie jest widoczna, zwraca 404 collections.not_found.

  • folder_idstring | null

    Folder kolekcji, w którym ma się znaleźć karta, z tymi samymi sprawdzeniami co folder_id przy przesyłaniu pliku. Folder innej kolekcji zwraca 400 folders.card_collection_mismatch, brakujący folder – 404 folders.not_found, a brak uprawnienia COLLECTION_EDIT_CARDS do folderu – 403 authz.forbidden.

    length ≤ 64

  • external_idstring | null

    external_id nowej karty. Jeśli używa go inna karta organizacji, żądanie zwraca 409 cards.external_id_taken. Aby utworzyć lub zastąpić kartę według external_id, użyj PUT /v1/cards-by-external-id/{external_id}.

    length ≤ 512

  • metadataMetadataPatch

Odpowiedzi

200Pomyślna odpowiedź

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: TextCardResult

  • statusstringwymagane

    Dozwolone wartości: readyerrorskippedqueued

  • cardCard | nullwymagane
  • tablesinteger
  • timingsobject
    Pola
    • total_snumber
  • errorstring
  • reasonstring
  • duplicatetrue
  • card_idstring | null
  • job_idinteger
  • jobJob
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

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.

← cards · Dokumentacja API