POST/v1/cards/text

Izveidot teksta kartīti (Markdown)

create_text_card

Izveido teksta kartīti no Markdown (kind=text). Tā tiek indeksēta tāpat kā augšupielādēts fails. Ar async=true indeksēšana tiek ievietota rindā: atbilde tiek atgriezta uzreiz, un progress ir pieejams /v1/jobs.

Autentifikācija

Nosūtiet API atslēgu galvenē Authorization: Authorization: Bearer <atslēga>.

Galvenes parametri

Idempotency-Keystring
Atslēga drošam rakstīšanas darbības atkārtojumam: 1–255 drukājamas ASCII rakstzīmes; ieteicams viens UUID v4 katrai loģiskajai operācijai. Atkārtojums ar to pašu atslēgu 24 stundu laikā operāciju neizpilda vēlreiz: tiek atgriezta saglabātā atbilde (statuss, galvenes un saturs) ar galveni Idempotency-Replayed: true. Tā pati atslēga ar citu metodi, ceļu, Content-Type vai saturu atgriež 409 api.idempotency_mismatch; kamēr pirmais pieprasījums vēl izpildās – 409 api.idempotency_in_progress ar Retry-After: 1. Pēc atbildes 5xx vai 429 atslēga tiek atbrīvota, un atkārtojums izpilda operāciju vēlreiz. Atslēga ir piesaistīta organizācijai un izsaucējam (API atslēgai, lietotājam vai pielāgotā avota atslēgai).
length ≥ 1, length ≤ 255
X-View-Asstring
Tikai API atslēgām ar lomu admin. Izpilda pieprasījumu datu profila <profile>[:viewer|verifier|editor] vārdā, piemēram, employee:viewer. Instalācijas atslēga šo galveni lietot nevar (403).

Sīkdatņu parametri

kb_view_asstring
Režīma „View as“ (skatīt kā) sīkdatne sesijai. POST /auth/view-as to iestata, un DELETE /auth/view-as to notīra.

Pieprasījuma saturs

application/json

Objekts: TextCardRequest

titlestringobligāts
length ≥ 1, length ≤ 200
collectionstring
Noklusējums: "default"
body_markdownstring
Kartītes teksts Markdown formātā; content_type uz to neattiecas. Tā vietā var nodot body.
length ≥ 1, length ≤ 500000
tagsarray of string | null
items ≤ 30
categorystring | null
length ≤ 60
sensitiveboolean | null
owner_idinteger | null
asyncboolean
Noklusējums: false
bodystring
Kartītes teksts formātā content_type. Nododiet vai nu body, vai body_markdown; ja nodoti abi, atgriež 422 validation.failed.
length ≥ 1, length ≤ 500000
content_typeCardTextContentType
collection_idinteger | null
Kolekcija pēc ID. Ja norādīts arī collection, noteicošais ir collection_id. Kolekcija, kas organizācijā neeksistē vai nav redzama, atgriež 404 collections.not_found.
folder_idstring | null
Kolekcijas mape, kurā ievietot kartīti, ar tām pašām pārbaudēm kā folder_id faila augšupielādē. Citas kolekcijas mape atgriež 400 folders.card_collection_mismatch, neesoša mape – 404 folders.not_found, bet atļaujas COLLECTION_EDIT_CARDS trūkums šai mapei – 403 authz.forbidden.
length ≤ 64
external_idstring | null
Jaunās kartītes external_id. Ja to izmanto cita organizācijas kartīte, pieprasījums atgriež 409 cards.external_id_taken. Lai izveidotu vai aizstātu kartīti pēc external_id, izmantojiet PUT /v1/cards-by-external-id/{external_id}.
length ≤ 512
metadataMetadataPatch

Atbildes

200Veiksmīga atbilde

Atbildes galvenes

RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.
Idempotency-Replayed
true nozīmē, ka atbilde ir atkārtota no šai Idempotency-Key saglabātās atbildes: operācija netika izpildīta vēlreiz.

application/json

Objekts: TextCardResult

statusstringobligāts
Atļautās vērtības: readyerrorskippedqueued
cardCard | nullobligāts
tablesinteger
timingsobject
Lauki
- total_snumber
errorstring
reasonstring
duplicatetrue
card_idstring | null
job_idinteger
jobJob

400Pieprasījums nav derīgs: parametra vērtība vai objekta stāvoklis neļauj veikt darbību (`detail` ir ziņojums).

Atbildes galvenes

RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

401Nav nosūtīti akreditācijas dati (ne sesijas sīkdatne, ne API atslēga), vai atslēga nav atrasta.

Atbildes galvenes

RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

403Darbība nav atļauta: loma nav pietiekama, nav piekļuves kolekcijai vai kartītei, pieprasījums izpildās režīmā „View as“ vai organizācija ir apturēta vai dzēsta (`detail` ir objekts ar `code: org_suspended | org_deleted`).

Atbildes galvenes

RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

404Objekts neeksistē vai jums nav pieejams. API neapstiprina, ka ierobežotas piekļuves objekts eksistē.

Atbildes galvenes

RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

409Objekta stāvoklis neļauj veikt darbību, piemēram, dublikāts, notiekoša indeksēšana vai jau apstrādāts darbs.

Atbildes galvenes

RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

422Validācijas kļūda: saturs vai parametri neatbilst shēmai (`detail` ir validācijas kļūdu saraksts), vai parametra vērtība ir ārpus pieļaujamā diapazona (`detail` ir ziņojums).

Atbildes galvenes

RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

429Pārāk daudz pieprasījumu (`api.rate_limited`), organizācijas minūtes, dienas vai mēneša kvota ir izlietota (`api.quota_exceeded`; `error.details` satur `quota`, `limit` un `reset_at`), sasniegts organizācijas limits vai atbilžu pakalpojums ir aizņemts (`answers.engine_busy`). Pagaidiet galvenē `Retry-After` norādīto laiku.

Atbildes galvenes

Retry-After
Sekunžu skaits, kas jāpagaida, pirms atkārtojat pieprasījumu.
RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

Kļūdu kodi

Kodi, ko šī operācija var atgriezt laukā error.code papildus vispārīgajiem kodiem, kas iespējami jebkuram pieprasījumam.

Droši atkārtojumi

Ar katru POST un PATCH pieprasījumu nosūtiet galveni Idempotency-Key (piemēram, UUID). Atkārtots pieprasījums ar to pašu atslēgu 24 stundu laikā atgriež saglabāto atbildi, nevis izpilda pieprasījumu vēlreiz.

Pieprasījumu biežuma limiti

Atbildēs ir galvenes RateLimit un RateLimit-Policy, kā arī agrākās X-RateLimit-Limit, X-RateLimit-Remaining un X-RateLimit-Reset. Atbildē 429 ir galvene Retry-After sekundēs: nogaidiet un atkārtojiet pieprasījumu.

← cards · API rokasgrāmata

curl -X POST 'https://api.sursa.com/v1/cards/text' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"title":"Refund policy","collection":"support","body_markdown":"# Refund policy\n\nRefunds are processed within 14 days."}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Izmēģināt

API atslēga

Atslēga glabājas tikai šīs cilnes atmiņā un tiek sūtīta tikai uz https://api.sursa.com.

Pieprasījumi darbojas ar jūsu organizācijas reālajiem datiem.

Idempotency-Key header

X-View-As header

Idempotency-Key

Ja lauks ir tukšs, katram pieprasījumam tiek ģenerēta jauna atslēga.

Pieprasījuma saturs (JSON)