POST/v1/drafts

Piszkozat létrehozása

create_draft

Piszkozatot hoz létre egy új kártyához (collection, COLLECTION_CREATE_CARDS jogosultság szükséges) vagy egy meglévő kártya szerkesztéséhez (card_id, CARD_EDIT jogosultság szükséges; a címet, a címkéket és a szöveget a legutóbbi verzióból veszi, ha nincsenek megadva). A szerző az első társszerző. Egy felhasználónak kártyánként egy aktív piszkozata lehet: az ismételt kérés 409 drafts.exists választ ad, a details mezőben a draft_id értékkel (abban a piszkozatban folytasd a munkát PATCH kéréssel). A scheduled_publish_at ütemezi a közzétételt. Egy API-kulcs az author_id mezőben adja meg a piszkozat szerzőjét (az 1.62.0 verziótól).

Hitelesítés

Küldj egy API-kulcsot az Authorization fejlécben: Authorization: Bearer <kulcs>.

Fejlécparaméterek

Idempotency-Keystring
Kulcs egy írási kérés biztonságos megismétléséhez: 1–255 nyomtatható ASCII-karakter; logikai műveletenként egy UUID v4 ajánlott. Ha 24 órán belül ugyanazzal a kulccsal ismétled meg a kérést, a művelet nem fut le újra: a mentett választ kapod vissza (állapot, fejlécek és törzs) az Idempotency-Replayed: true fejléccel. Ugyanaz a kulcs más metódussal, útvonallal, Content-Type értékkel vagy törzzsel 409 api.idempotency_mismatch választ ad; amíg az első kérés még fut, a válasz 409 api.idempotency_in_progress, Retry-After: 1 fejléccel. 5xx vagy 429 válasz után a kulcs felszabadul, és a megismételt kérés újra lefuttatja a műveletet. A kulcs a szervezethez és a hívóhoz (API-kulcs, felhasználó vagy egyéni forrás forráskulcsa) kötődik.
length ≥ 1, length ≤ 255

Kéréstörzs

application/json

Objektum: DraftCreate

card_idstring | null
collectionstring | null
Az új kártya gyűjteményének neve (card_id nélkül kötelező).
titlestring | null
length ≤ 200
body_markdownstring | null
length ≤ 500000
tagsarray of string | null
items ≤ 30
revision_notestring | null
length ≤ 1000
verify_on_publishboolean
Alapértelmezett: false
notify_followersboolean
Alapértelmezett: false
scheduled_publish_atstring (date-time) | null
author_idinteger
A piszkozat szerzője, ha API-kulcs hív (az 1.62.0 verziótól): a kulcs szervezetének egy aktív felhasználója; ő lesz a created_by és az első társszerző. Kulcsnál kötelező (ellenkező esetben 422 validation.failed); más szervezet felhasználójára vagy inaktív felhasználóra 404 users.not_found a válasz. A gyűjteményen és a kártyán lévő jogosultságokat a rendszer a kulcsra ellenőrzi, nem a szerzőre. Munkamenetben a szerző a bejelentkezett felhasználó: eltérő author_id esetén 422 validation.failed a válasz.
≥ 1

Válaszok

201Létrehozva

Válaszfejlécek

RateLimit-Policy
Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.
RateLimit
Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).
X-RateLimit-Remaining
A legszigorúbb korlát szerint még hátralévő kérések száma.
X-RateLimit-Reset
A legszigorúbb korlát visszaállásáig hátralévő másodpercek.
Idempotency-Replayed
A true azt jelenti, hogy a válasz az ehhez az Idempotency-Key kulcshoz mentett válasz megismétlése: a művelet nem futott le újra.

application/json

Objektum: Draft

idintegerkötelező
org_idintegerkötelező
card_idstring | nullkötelező
A kártya, amelyet a piszkozat szerkeszt; null – új kártya piszkozata.
collection_idintegerkötelező
collectionstringkötelező
titlestringkötelező
body_markdownstringkötelező
tagsarray of stringkötelező
base_versioninteger | null
A kártya verziója, amelyből a piszkozat kiindult.
scheduled_publish_atstring (date-time) | null
workflow_stateDraftWorkflowStatekötelező
revision_notestring | null
verify_on_publishbooleankötelező
notify_followersbooleankötelező
created_byintegerkötelező
updated_byinteger | null
created_atstring (date-time)kötelező
updated_atstring (date-time)kötelező
publish_requested_byinteger | null
publish_requested_atstring (date-time) | null
approved_byinteger | null
approved_atstring (date-time) | null
collaboratorsarray of DraftCollaboratorkötelező
conflictstring | null
card_published – a kártyát a piszkozat megkezdése után közzétették vagy módosították; card_deleted – a kártyát törölték; bővíthető.

400A kérés érvénytelen: egy paraméter értéke vagy az objektum állapota nem teszi lehetővé a műveletet (a `detail` egy üzenet).

Válaszfejlécek

RateLimit-Policy
Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.
RateLimit
Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).
X-RateLimit-Remaining
A legszigorúbb korlát szerint még hátralévő kérések száma.
X-RateLimit-Reset
A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

401Nem érkeztek hitelesítő adatok (sem munkamenet-süti, sem API-kulcs), vagy a kulcs nem található.

Válaszfejlécek

RateLimit-Policy
Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.
RateLimit
Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).
X-RateLimit-Remaining
A legszigorúbb korlát szerint még hátralévő kérések száma.
X-RateLimit-Reset
A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

403A művelet nem engedélyezett: a szerepkör nem elegendő, nincs hozzáférés a gyűjteményhez vagy a kártyához, a kérés „View as” módban fut, vagy a szervezetet felfüggesztették vagy törölték (a `detail` egy objektum, `code: org_suspended | org_deleted` mezővel).

Válaszfejlécek

RateLimit-Policy
Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.
RateLimit
Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).
X-RateLimit-Remaining
A legszigorúbb korlát szerint még hátralévő kérések száma.
X-RateLimit-Reset
A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

404Az objektum nem létezik, vagy nem érhető el számodra. Az API nem erősíti meg, hogy egy korlátozott hozzáférésű objektum létezik.

Válaszfejlécek

RateLimit-Policy
Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.
RateLimit
Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).
X-RateLimit-Remaining
A legszigorúbb korlát szerint még hátralévő kérések száma.
X-RateLimit-Reset
A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

409Az objektum állapota nem teszi lehetővé a műveletet, például ismétlődés, folyamatban lévő indexelés vagy már feldolgozott feladat miatt.

Válaszfejlécek

RateLimit-Policy
Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.
RateLimit
Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).
X-RateLimit-Remaining
A legszigorúbb korlát szerint még hátralévő kérések száma.
X-RateLimit-Reset
A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

422Érvényesítési hiba: a törzs vagy a paraméterek nem felelnek meg a sémának (a `detail` az érvényesítési hibák listája), vagy egy paraméter értéke kívül esik a megengedett tartományon (a `detail` egy üzenet).

Válaszfejlécek

RateLimit-Policy
Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.
RateLimit
Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).
X-RateLimit-Remaining
A legszigorúbb korlát szerint még hátralévő kérések száma.
X-RateLimit-Reset
A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

429Túl sok kérés (`api.rate_limited`), elfogyott a szervezet percre, napra vagy hónapra szóló kvótája (`api.quota_exceeded`; az `error.details` a `quota`, a `limit` és a `reset_at` mezőt tartalmazza), a szervezet elérte a korlátját, vagy a válaszszolgáltatás foglalt (`answers.engine_busy`). Várj a `Retry-After` fejlécben megadott ideig.

Válaszfejlécek

Retry-After
Ennyi másodpercet várj, mielőtt újrapróbálod a kérést.
RateLimit-Policy
Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.
RateLimit
Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).
X-RateLimit-Remaining
A legszigorúbb korlát szerint még hátralévő kérések száma.
X-RateLimit-Reset
A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

Hibakódok

Azok a kódok, amelyeket ez a végpont hiba esetén az error.code mezőben visszaadhat, a minden kérésre érvényes általános kódokon kívül.

Biztonságos újrapróbálkozás

Minden POST és PATCH kéréssel küldj Idempotency-Key fejlécet (például egy UUID-t). Ha 24 órán belül ugyanazzal a kulccsal megismétled a kérést, a mentett választ kapod vissza, és a kérés nem fut le újra.

Gyakorisági korlátok

A válaszokban ott van a RateLimit és a RateLimit-Policy fejléc, valamint a korábbi X-RateLimit-Limit, X-RateLimit-Remaining és X-RateLimit-Reset fejléc. A 429-es válasz Retry-After fejléce másodpercben adja meg a várakozást: várj, majd próbáld újra.

← drafts · API-referencia

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

Kipróbálás

API-kulcs

A kulcs ennek a lapnak a memóriájában marad, és a konzol csak ide küldi el: https://api.sursa.com.

A kérések a szervezeted valódi adataival dolgoznak.

Idempotency-Key header

Idempotency-Key

Ha a mező üres, minden kéréshez új kulcs készül.

Kéréstörzs (JSON)