Pereiti prie turinio
Sursa Developers

POST/v1/drafts

Sukurti juodraštį

create_draft

Sukuria naujos kortelės juodraštį (collection, reikia COLLECTION_CREATE_CARDS) arba esamos kortelės pakeitimo juodraštį (card_id, reikia CARD_EDIT; pavadinimas, žymos ir tekstas imami iš naujausios versijos, jei nenurodyti). Autorius – pirmasis bendraautoris. Naudotojas gali turėti vieną aktyvų juodraštį kiekvienai kortelei: pakartotinė užklausa grąžina 409 drafts.exists su draft_id lauke details (tęskite tame juodraštyje su PATCH). scheduled_publish_at suplanuoja paskelbimą. API raktas juodraščio autorių nurodo lauke author_id (nuo 1.62.0).

Autentifikavimas

Siųskite API raktą antraštėje Authorization: Authorization: Bearer <raktas>.

Antraštės parametrai

  • Idempotency-Keystring

    Raktas saugiam rašymo operacijos pakartojimui: nuo 1 iki 255 spausdinamų ASCII simbolių; rekomenduojamas atskiras UUID v4 kiekvienai loginei operacijai. Pakartojus užklausą su tuo pačiu raktu per 24 valandas, operacija iš naujo nevykdoma: grąžinamas išsaugotas atsakas (būsena, antraštės ir turinys) su antrašte Idempotency-Replayed: true. Tas pats raktas su kitu metodu, keliu, Content-Type ar turiniu grąžina 409 api.idempotency_mismatch; kol pirmoji užklausa dar vykdoma – 409 api.idempotency_in_progress su Retry-After: 1. Po 5xx ar 429 atsako raktas atlaisvinamas, ir pakartojimas operaciją vykdo iš naujo. Raktas galioja organizacijos ir iškvietėjo (API rakto, naudotojo arba pasirinktinio šaltinio rakto) ribose.

    length ≥ 1, length ≤ 255

Užklausos turinys

application/json

Objektas: DraftCreate

  • card_idstring | null
  • collectionstring | null

    Rinkinio pavadinimas naujai kortelei (privalomas be card_id).

  • titlestring | null

    length ≤ 200

  • body_markdownstring | null

    length ≤ 500000

  • tagsarray of string | null

    items ≤ 30

  • revision_notestring | null

    length ≤ 1000

  • verify_on_publishboolean

    Numatytoji reikšmė: false

  • notify_followersboolean

    Numatytoji reikšmė: false

  • scheduled_publish_atstring (date-time) | null
  • author_idinteger

    Juodraščio autorius, kai kviečiama API raktu (nuo 1.62.0): aktyvus rakto organizacijos naudotojas; jis tampa created_by ir pirmuoju bendraautoriu. Raktui privalomas (kitaip 422 validation.failed); kitos organizacijos arba neaktyvus naudotojas grąžina 404 users.not_found. Leidimai rinkiniui ir kortelei tikrinami raktui, ne autoriui. Sesijoje autorius – prisijungęs naudotojas: kitoks author_id grąžina 422 validation.failed.

    ≥ 1

Atsakai

201Sukurta

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

  • Idempotency-Replayed

    true – atsakas pakartotas iš šiam Idempotency-Key išsaugoto atsako: operacija iš naujo nevykdyta.

application/json

Objektas: Draft

  • idintegerprivalomas
  • org_idintegerprivalomas
  • card_idstring | nullprivalomas

    Kortelė, kurią redaguoja juodraštis; null – naujos kortelės juodraštis.

  • collection_idintegerprivalomas
  • collectionstringprivalomas
  • titlestringprivalomas
  • body_markdownstringprivalomas
  • tagsarray of stringprivalomas
  • base_versioninteger | null

    Kortelės versija, nuo kurios pradėtas juodraštis.

  • scheduled_publish_atstring (date-time) | null
  • workflow_stateDraftWorkflowStateprivalomas
  • revision_notestring | null
  • verify_on_publishbooleanprivalomas
  • notify_followersbooleanprivalomas
  • created_byintegerprivalomas
  • updated_byinteger | null
  • created_atstring (date-time)privalomas
  • updated_atstring (date-time)privalomas
  • publish_requested_byinteger | null
  • publish_requested_atstring (date-time) | null
  • approved_byinteger | null
  • approved_atstring (date-time) | null
  • collaboratorsarray of DraftCollaboratorprivalomas
  • conflictstring | null

    card_published – kortelė paskelbta arba pakeista pradėjus juodraštį; card_deleted – kortelė ištrinta; išvardijimas plečiamas.

400Užklausa netinkama: parametro reikšmė arba objekto būsena neleidžia atlikti veiksmo (`detail` – pranešimas).

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

401Prisijungimo duomenys neišsiųsti (nei sesijos slapukas, nei API raktas) arba raktas nerastas.

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

403Veiksmas neleidžiamas: vaidmuo nesuteikia reikiamų teisių, nėra prieigos prie rinkinio ar kortelės, užklausa vykdoma režimu „View as“ arba organizacijos veikla sustabdyta ar organizacija ištrinta (`detail` – objektas su `code: org_suspended | org_deleted`).

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

404Objekto nėra arba jis jums nepasiekiamas. API nepatvirtina, kad ribotos prieigos objektas egzistuoja.

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

409Objekto būsena neleidžia atlikti veiksmo, pvz., dublikatas, vyksta indeksavimas arba darbas jau apdorotas.

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

422Validavimo klaida: turinys ar parametrai neatitinka schemos (`detail` – validavimo klaidų sąrašas) arba parametro reikšmė nepatenka į leistiną intervalą (`detail` – pranešimas).

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

429Per daug užklausų (`api.rate_limited`), išnaudota organizacijos minutės, dienos ar mėnesio kvota (`api.quota_exceeded`; `error.details` pateikia `quota`, `limit` ir `reset_at`), pasiektas organizacijos limitas arba atsakymų paslauga užimta (`answers.engine_busy`). Palaukite tiek, kiek nurodyta antraštėje `Retry-After`.

Atsako antraštės

  • Retry-After

    Kiek sekundžių palaukti prieš kartojant užklausą.

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

Klaidų kodai

Kodai, kuriuos ši operacija gali grąžinti lauke error.code, be bendrųjų kodų, galimų bet kuriai užklausai.

Saugūs pakartojimai

Su kiekviena POST ir PATCH užklausa siųskite antraštę Idempotency-Key (pavyzdžiui, UUID). Pakartojus užklausą su tuo pačiu raktu per 24 valandas, grąžinamas išsaugotas atsakas, o užklausa iš naujo nevykdoma.

Užklausų dažnio limitai

Atsakuose yra antraštės RateLimit ir RateLimit-Policy bei ankstesnės X-RateLimit-Limit, X-RateLimit-Remaining ir X-RateLimit-Reset. Atsake 429 yra antraštė Retry-After sekundėmis: palaukite ir pakartokite užklausą.

← drafts · API žinynas