PATCH/v1/drafts/{draft_id}

Aktualizovat koncept

update_draft

Všechna pole jsou nepovinná. scheduled_publish_at: null zruší naplánovanou publikaci. Úprava schváleného konceptu ho vrátí do stavu publish_requested. Klíč API může koncept upravovat za stejných podmínek, za jakých ho čte (od verze 1.62.0).

Autentizace

Odešlete klíč API v hlavičce Authorization: Authorization: Bearer <klíč>.

Parametry cesty

draft_idintegerpovinné

Parametry hlavičky

Idempotency-Keystring
Klíč pro bezpečné opakování zápisu: 1 až 255 tisknutelných znaků ASCII; doporučuje se UUID v4 pro každou logickou operaci. Opakování se stejným klíčem do 24 hodin operaci znovu nespustí: vrátí uloženou odpověď (stav, hlavičky a tělo) s hlavičkou Idempotency-Replayed: true. Stejný klíč s jinou metodou, cestou, Content-Type nebo tělem vrací 409 api.idempotency_mismatch; dokud první požadavek ještě běží, vrací 409 api.idempotency_in_progress s Retry-After: 1. Po odpovědi 5xx nebo 429 se klíč uvolní a opakování operaci spustí znovu. Klíč platí v rámci organizace a volajícího (klíč API, uživatel nebo klíč vlastního zdroje).
length ≥ 1, length ≤ 255

Tělo požadavku

application/json

Objekt: DraftUpdate

titlestring | null
length ≤ 200
body_markdownstring | null
length ≤ 500000
tagsarray of string | null
items ≤ 30
revision_notestring | null
length ≤ 1000
verify_on_publishboolean | null
notify_followersboolean | null
scheduled_publish_atstring (date-time) | null
null zruší naplánovanou publikaci; pole, které v těle chybí, se nemění.

Odpovědi

200Úspěšná odpověď

Hlavičky odpovědi

RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.
Idempotency-Replayed
true znamená, že jde o znovu vrácenou uloženou odpověď pro tento Idempotency-Key: operace se znovu nespustila.

application/json

Objekt: Draft

idintegerpovinné
org_idintegerpovinné
card_idstring | nullpovinné
Karta, kterou koncept upravuje; null – koncept nové karty.
collection_idintegerpovinné
collectionstringpovinné
titlestringpovinné
body_markdownstringpovinné
tagsarray of stringpovinné
base_versioninteger | null
Verze karty, ze které koncept vznikl.
scheduled_publish_atstring (date-time) | null
workflow_stateDraftWorkflowStatepovinné
revision_notestring | null
verify_on_publishbooleanpovinné
notify_followersbooleanpovinné
created_byintegerpovinné
updated_byinteger | null
created_atstring (date-time)povinné
updated_atstring (date-time)povinné
publish_requested_byinteger | null
publish_requested_atstring (date-time) | null
approved_byinteger | null
approved_atstring (date-time) | null
collaboratorsarray of DraftCollaboratorpovinné
conflictstring | null
card_published – karta byla po vzniku konceptu publikována nebo změněna; card_deleted – karta byla smazána; rozšiřitelné.

400Požadavek je neplatný: hodnota parametru nebo stav objektu akci neumožňuje (`detail` je zpráva).

Hlavičky odpovědi

RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

401Nebyly odeslány žádné přihlašovací údaje (ani cookie relace, ani klíč API), nebo klíč nebyl nalezen.

Hlavičky odpovědi

RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

403Akce není povolena: role nestačí, chybí přístup ke kolekci nebo kartě, požadavek běží v režimu „View as“, nebo je organizace pozastavená či smazaná (`detail` je objekt s `code: org_suspended | org_deleted`).

Hlavičky odpovědi

RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

404Objekt neexistuje nebo vám není dostupný. API nepotvrzuje, že objekt s omezeným přístupem existuje.

Hlavičky odpovědi

RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

409Stav objektu akci neumožňuje, například kvůli duplicitě, probíhajícímu indexování nebo úloze, která už je zpracovaná.

Hlavičky odpovědi

RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

422Chyba validace: tělo nebo parametry neodpovídají schématu (`detail` je seznam chyb validace), nebo je hodnota parametru mimo povolený rozsah (`detail` je zpráva).

Hlavičky odpovědi

RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

429Příliš mnoho požadavků (`api.rate_limited`), kvóta organizace na minutu, den nebo měsíc je vyčerpána (`api.quota_exceeded`; `error.details` obsahuje `quota`, `limit` a `reset_at`), organizace dosáhla svého limitu nebo je služba odpovědí vytížená (`answers.engine_busy`). Počkejte dobu uvedenou v hlavičce `Retry-After`.

Hlavičky odpovědi

Retry-After
Počet sekund, které je třeba počkat před opakováním požadavku.
RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

Chybové kódy

Kódy, které tato operace může vrátit v error.code, kromě obecných kódů každého požadavku.

Bezpečné opakování

S každým požadavkem POST a PATCH odešlete hlavičku Idempotency-Key (například UUID). Opakování se stejným klíčem do 24 hodin vrátí uloženou odpověď, místo aby se požadavek provedl znovu.

Limity četnosti

Odpovědi obsahují hlavičky RateLimit a RateLimit-Policy a starší X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset. Odpověď 429 má hlavičku Retry-After v sekundách: počkejte a požadavek zopakujte.

← drafts · Reference API

curl -X PATCH 'https://api.sursa.com/v1/drafts/1' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"title":"Refund policy","body_markdown":"# Refund policy\n\nRefunds are processed within 14 days.","tags":["string"]}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Vyzkoušet

Klíč API

Klíč zůstává v paměti této karty prohlížeče a odesílá se jen na https://api.sursa.com.

Požadavky pracují se skutečnými daty vaší organizace.

Idempotency-Key header

draft_id path *

Idempotency-Key

Když je pole prázdné, vygeneruje se pro každý požadavek nový klíč.

Tělo požadavku (JSON)