POST/v1/cards
Augšupielādēt failu kā kartīti
upload_card
Nosūtiet dokumentu multipart/form-data formas laukā file. Pirms saglabāšanas Sursa pārbauda, vai faila nosaukuma paplašinājums, daļas deklarētais Content-Type un satura paraksts sakrīt:
- PDF;
- DOCX, XLSX, XLSM, PPTX: ZIP ar deklarēto galvenā dokumenta tipu;
- ODS: ZIP ar ierakstu mimetype;
- XLS: OLE2 dokuments ar darbgrāmatas straumi;
- TXT, MD, CSV, TSV, HTML, AsciiDoc, EML: teksts bez nulles baitiem UTF-8 vai vienbaita kodējumā, bet e-pastam – arī galvenes sākumā;
- PNG, JPEG, TIFF, WebP, BMP: pēc paraksta.
Neatbilstība atgriež 415 files.type_mismatch; paplašinājums, kas nav formātu sarakstā, atgriež 415 cards.unsupported_format. Fails, kas ir lielāks par instalācijas augšupielādes limitu vai organizācijas kopējo krātuvi pēc tās plāna, atgriež 413 files.too_large. Ja ieslēgta pretvīrusu pārbaude, inficēts fails atgriež 422 files.infected, bet, ja skeneris nav pieejams un spēkā ir politika „reject“ (noraidīt), pieprasījums atgriež 503 files.scan_unavailable. Katrs noraidījums tiek ierakstīts audita žurnālā kā file.rejected.
Formas vietā varat nosūtīt application/json saturu (CardUploadFromUpload, kopš 1.62.0): fails ir gatava augšupielāde pa daļām upload_id (POST /v1/uploads ar mērķi card_file), lauki ir tie paši, kas formā, un tags ir virkņu saraksts. Augšupielādes fails jau ir pārbaudīts complete brīdī (formāts, pretvīrusu pārbaude), un izmēra limits ir augšupielādes pa daļām limits, nevis viena pieprasījuma augšupielādes limits. Augšupielāde tiek izmantota vienreiz – tajā pašā transakcijā, kas izveido kartīti: jau izmantota augšupielāde atgriež 409 uploads.already_used, vēl negatava – 409 uploads.not_ready, noraidīta – 422 uploads.rejected, ar citu mērķi – 422 uploads.purpose_mismatch, beigusies – 410 uploads.expired, bet cita izsaucēja vai nezināma augšupielāde atgriež 404 uploads.not_found. Ja kartītes pārbaudes neizdodas (kolekcija, kategorija, limiti), augšupielāde netiek iztērēta.
Autentifikācija
Nosūtiet API atslēgu galvenē Authorization: Authorization: Bearer <atslēga>.
Galvenes parametri
Idempotency-KeystringAtslē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-Typevai saturu atgriež409 api.idempotency_mismatch; kamēr pirmais pieprasījums vēl izpildās –409 api.idempotency_in_progressarRetry-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-AsstringTikai 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_asstringRežīma „View as“ (skatīt kā) sīkdatne sesijai.
POST /auth/view-asto iestata, unDELETE /auth/view-asto notīra.
Pieprasījuma saturs
multipart/form-data
filestring (application/octet-stream)obligātscollectionstringNoklusējums: "default"
tagsstringNoklusējums: ""
forcebooleanNoklusējums: false
owner_idinteger | nullverify_interval_daysinteger | nullcategorystring | nullsensitiveboolean | nullasyncbooleanNoklusējums: false
reviewbooleanNoklusējums: false
folder_idstring | nullKolekcijas
collectionmape, kurā ievietot jauno kartīti. Citas kolekcijas mape atgriež400 folders.card_collection_mismatch, neesoša mape –404 folders.not_found, bet atļaujasCOLLECTION_EDIT_CARDStrūkums šai mapei –403 authz.forbidden. Pārbaude notiek pirms faila saglabāšanas. Jau augšupielādēta faila dublikāts (skipped) uz mapi netiek pārvietots.length ≤ 64
collection_idinteger | nullKolekcija pēc ID. Ja norādīts arī
collection, noteicošais ircollection_id. Kolekcija, kas organizācijā neeksistē vai nav redzama, atgriež404 collections.not_found.external_idstring | nullJaunās kartītes
external_id. Ar to kartīte tiek izveidota pat tad, ja kolekcijā jau ir tāds pats fails. Ja to izmanto cita organizācijas kartīte, pieprasījums atgriež409 cards.external_id_taken. Lai izveidotu vai aizstātu kartīti pēcexternal_id, izmantojietPUT /v1/cards-by-external-id/{external_id}.length ≤ 512
metadatastring | nullJaunās kartītes
metadata: JSON objekts kā formas lauka vērtība. Noteikumi ir tādi paši kāMetadataPatch.
application/json
upload_idstringobligātsGatava augšupielāde (
ready) ar mērķicard_file; to izmanto vienu reizi.collectionstringNoklusējums: "default"
collection_idinteger | nullKolekcija pēc ID. Ja nodots arī
collection, noteicošais ircollection_id. Kolekcija, kas organizācijā neeksistē, nav redzama vai ir ārpus atslēgas kolekcijām, atgriež404 collections.not_found.tagsarray of stringitems ≤ 30
forcebooleanNoklusējums: false
owner_idinteger | nullverify_interval_daysinteger | nullcategorystring | nullsensitiveboolean | nullasyncbooleanNoklusējums: false
reviewbooleanNoklusējums: false
folder_idstring | nulllength ≤ 64
external_idstring | nullJaunās kartītes
external_id, tāpat kā formas laukā. Ar to kartīte tiek izveidota arī tad, ja kolekcijā jau ir tāds pats fails. Ja to izmanto cita organizācijas kartīte, pieprasījums atgriež409 cards.external_id_taken.length ≤ 512
metadataMetadataPatch
Atbildes
200`queued` (asinhroni), `skipped` (dublikāts), `ready` vai `error` (sinhroni).
Atbildes galvenes
RateLimit-PolicySpēkā esošie limiti IETF dokumenta projekta
draft-ietf-httpapi-ratelimit-headersformātā: ar komatiem atdalīti elementi"<name>";q=<quota>;w=<window in seconds>.keyir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas iruser, bez akreditācijas datiem –ip);minute,dayunmonthir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.RateLimitCik atlicis no katra
RateLimit-Policylimita:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitStingrākā
RateLimit-Policyieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).X-RateLimit-RemainingAtlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-ResetSekundes līdz stingrākā limita atiestatīšanai.
Idempotency-Replayedtruenozīmē, ka atbilde ir atkārtota no šaiIdempotency-Keysaglabātās atbildes: operācija netika izpildīta vēlreiz.
application/json
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-PolicySpēkā esošie limiti IETF dokumenta projekta
draft-ietf-httpapi-ratelimit-headersformātā: ar komatiem atdalīti elementi"<name>";q=<quota>;w=<window in seconds>.keyir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas iruser, bez akreditācijas datiem –ip);minute,dayunmonthir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.RateLimitCik atlicis no katra
RateLimit-Policylimita:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitStingrākā
RateLimit-Policyieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).X-RateLimit-RemainingAtlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-ResetSekundes līdz stingrākā limita atiestatīšanai.
application/json
401Nav nosūtīti akreditācijas dati (ne sesijas sīkdatne, ne API atslēga), vai atslēga nav atrasta.
Atbildes galvenes
RateLimit-PolicySpēkā esošie limiti IETF dokumenta projekta
draft-ietf-httpapi-ratelimit-headersformātā: ar komatiem atdalīti elementi"<name>";q=<quota>;w=<window in seconds>.keyir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas iruser, bez akreditācijas datiem –ip);minute,dayunmonthir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.RateLimitCik atlicis no katra
RateLimit-Policylimita:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitStingrākā
RateLimit-Policyieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).X-RateLimit-RemainingAtlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-ResetSekundes līdz stingrākā limita atiestatīšanai.
application/json
402Organizācija ir sasniegusi plāna limitu (kartītes, krātuve vai lietotāji). `error.details` satur `kind`, `limit` un `used`.
Atbildes galvenes
RateLimit-PolicySpēkā esošie limiti IETF dokumenta projekta
draft-ietf-httpapi-ratelimit-headersformātā: ar komatiem atdalīti elementi"<name>";q=<quota>;w=<window in seconds>.keyir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas iruser, bez akreditācijas datiem –ip);minute,dayunmonthir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.RateLimitCik atlicis no katra
RateLimit-Policylimita:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitStingrākā
RateLimit-Policyieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).X-RateLimit-RemainingAtlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-ResetSekundes līdz stingrākā limita atiestatīšanai.
application/json
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-PolicySpēkā esošie limiti IETF dokumenta projekta
draft-ietf-httpapi-ratelimit-headersformātā: ar komatiem atdalīti elementi"<name>";q=<quota>;w=<window in seconds>.keyir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas iruser, bez akreditācijas datiem –ip);minute,dayunmonthir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.RateLimitCik atlicis no katra
RateLimit-Policylimita:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitStingrākā
RateLimit-Policyieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).X-RateLimit-RemainingAtlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-ResetSekundes līdz stingrākā limita atiestatīšanai.
application/json
404Objekts neeksistē vai jums nav pieejams. API neapstiprina, ka ierobežotas piekļuves objekts eksistē.
Atbildes galvenes
RateLimit-PolicySpēkā esošie limiti IETF dokumenta projekta
draft-ietf-httpapi-ratelimit-headersformātā: ar komatiem atdalīti elementi"<name>";q=<quota>;w=<window in seconds>.keyir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas iruser, bez akreditācijas datiem –ip);minute,dayunmonthir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.RateLimitCik atlicis no katra
RateLimit-Policylimita:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitStingrākā
RateLimit-Policyieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).X-RateLimit-RemainingAtlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-ResetSekundes līdz stingrākā limita atiestatīšanai.
application/json
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-PolicySpēkā esošie limiti IETF dokumenta projekta
draft-ietf-httpapi-ratelimit-headersformātā: ar komatiem atdalīti elementi"<name>";q=<quota>;w=<window in seconds>.keyir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas iruser, bez akreditācijas datiem –ip);minute,dayunmonthir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.RateLimitCik atlicis no katra
RateLimit-Policylimita:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitStingrākā
RateLimit-Policyieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).X-RateLimit-RemainingAtlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-ResetSekundes līdz stingrākā limita atiestatīšanai.
application/json
410Objekts eksistēja, bet vairs nav pieejams: saite ir izmantota vai tās derīguma termiņš ir beidzies, vai fails ir dzēsts glabāšanas perioda beigās.
Atbildes galvenes
RateLimit-PolicySpēkā esošie limiti IETF dokumenta projekta
draft-ietf-httpapi-ratelimit-headersformātā: ar komatiem atdalīti elementi"<name>";q=<quota>;w=<window in seconds>.keyir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas iruser, bez akreditācijas datiem –ip);minute,dayunmonthir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.RateLimitCik atlicis no katra
RateLimit-Policylimita:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitStingrākā
RateLimit-Policyieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).X-RateLimit-RemainingAtlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-ResetSekundes līdz stingrākā limita atiestatīšanai.
application/json
413Pieprasījuma saturs pārsniedz atļauto izmēru.
Atbildes galvenes
RateLimit-PolicySpēkā esošie limiti IETF dokumenta projekta
draft-ietf-httpapi-ratelimit-headersformātā: ar komatiem atdalīti elementi"<name>";q=<quota>;w=<window in seconds>.keyir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas iruser, bez akreditācijas datiem –ip);minute,dayunmonthir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.RateLimitCik atlicis no katra
RateLimit-Policylimita:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitStingrākā
RateLimit-Policyieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).X-RateLimit-RemainingAtlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-ResetSekundes līdz stingrākā limita atiestatīšanai.
application/json
415Faila formāts netiek atbalstīts.
Atbildes galvenes
RateLimit-PolicySpēkā esošie limiti IETF dokumenta projekta
draft-ietf-httpapi-ratelimit-headersformātā: ar komatiem atdalīti elementi"<name>";q=<quota>;w=<window in seconds>.keyir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas iruser, bez akreditācijas datiem –ip);minute,dayunmonthir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.RateLimitCik atlicis no katra
RateLimit-Policylimita:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitStingrākā
RateLimit-Policyieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).X-RateLimit-RemainingAtlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-ResetSekundes līdz stingrākā limita atiestatīšanai.
application/json
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-PolicySpēkā esošie limiti IETF dokumenta projekta
draft-ietf-httpapi-ratelimit-headersformātā: ar komatiem atdalīti elementi"<name>";q=<quota>;w=<window in seconds>.keyir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas iruser, bez akreditācijas datiem –ip);minute,dayunmonthir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.RateLimitCik atlicis no katra
RateLimit-Policylimita:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitStingrākā
RateLimit-Policyieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).X-RateLimit-RemainingAtlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-ResetSekundes līdz stingrākā limita atiestatīšanai.
application/json
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-AfterSekunžu skaits, kas jāpagaida, pirms atkārtojat pieprasījumu.
RateLimit-PolicySpēkā esošie limiti IETF dokumenta projekta
draft-ietf-httpapi-ratelimit-headersformātā: ar komatiem atdalīti elementi"<name>";q=<quota>;w=<window in seconds>.keyir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas iruser, bez akreditācijas datiem –ip);minute,dayunmonthir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.RateLimitCik atlicis no katra
RateLimit-Policylimita:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitStingrākā
RateLimit-Policyieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).X-RateLimit-RemainingAtlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-ResetSekundes līdz stingrākā limita atiestatīšanai.
application/json
503Pakalpojums, no kura atkarīgs šis pieprasījums, īslaicīgi nav pieejams. Atkārtojiet vēlāk.
Atbildes galvenes
RateLimit-PolicySpēkā esošie limiti IETF dokumenta projekta
draft-ietf-httpapi-ratelimit-headersformātā: ar komatiem atdalīti elementi"<name>";q=<quota>;w=<window in seconds>.keyir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas iruser, bez akreditācijas datiem –ip);minute,dayunmonthir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.RateLimitCik atlicis no katra
RateLimit-Policylimita:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitStingrākā
RateLimit-Policyieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).X-RateLimit-RemainingAtlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-ResetSekundes līdz stingrākā limita atiestatīšanai.
application/json
Kļūdu kodi
Kodi, ko šī operācija var atgriezt laukā error.code papildus vispārīgajiem kodiem, kas iespējami jebkuram pieprasījumam.
- 400api.metadata_invalid
- 409api.idempotency_in_progress
- 400api.idempotency_key_invalid
- 409api.idempotency_mismatch
- 401auth.not_authenticated
- 403auth.system_scope
- 403authz.forbidden
- 403cards.duplicate_restricted
- 409cards.external_id_taken
- 403cards.no_access
- 404cards.not_found
- 400cards.review_requires_async
- 403cards.sensitivity_admin_only
- 415cards.unsupported_format
- 400categories.unknown
- 409collections.index_outdated
- 400collections.invalid_name
- 403collections.no_write_access
- 404collections.not_found
- 422files.infected
- 503files.scan_unavailable
- 413files.too_large
- 415files.type_mismatch
- 400folders.card_collection_mismatch
- 404folders.not_found
- 404jobs.not_found
- 402limits.cards
- 403org.deleted
- 403org.suspended
- 409uploads.already_used
- 410uploads.expired
- 404uploads.not_found
- 409uploads.not_ready
- 422uploads.purpose_mismatch
- 422uploads.rejected
- 400users.not_in_org
- 422validation.failed
- 403view_as.read_only
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.