POST/v1/drafts

Concept maken

create_draft

Maakt een concept voor een nieuwe kaart (collection, vereist COLLECTION_CREATE_CARDS) of voor een bewerking van een bestaande kaart (card_id, vereist CARD_EDIT; de titel, tags en tekst worden uit de nieuwste versie overgenomen, tenzij ze zijn opgegeven). De auteur is de eerste medeauteur. Een gebruiker kan één actief concept per kaart hebben: een herhaald request geeft 409 drafts.exists met draft_id in details (ga in dat concept verder met PATCH). scheduled_publish_at plant de publicatie. Een API-sleutel geeft de auteur van het concept op in author_id (sinds 1.62.0).

Authenticatie

Stuur een API-sleutel mee in de header Authorization: Authorization: Bearer <sleutel>.

Headerparameters

Idempotency-Keystring
Sleutel om een schrijfactie veilig opnieuw te proberen: 1 tot 255 afdrukbare ASCII-tekens; een UUID v4 per logische bewerking wordt aanbevolen. Een nieuwe poging met dezelfde sleutel binnen 24 uur voert de bewerking niet opnieuw uit: Sursa geeft de opgeslagen response terug (status, headers en body) met de header Idempotency-Replayed: true. Dezelfde sleutel met een andere methode, een ander pad, een andere Content-Type of een andere body geeft 409 api.idempotency_mismatch; zolang het eerste request nog loopt, 409 api.idempotency_in_progress met Retry-After: 1. Na een 5xx- of 429-response wordt de sleutel vrijgegeven en voert een nieuwe poging de bewerking opnieuw uit. De sleutel geldt per organisatie en per aanroeper (API-sleutel, gebruiker of bronsleutel).
length ≥ 1, length ≤ 255

Request-body

application/json

Object: DraftCreate

card_idstring | null
collectionstring | null
Naam van de collectie voor een nieuwe kaart (verplicht zonder 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
Standaard: false
notify_followersboolean
Standaard: false
scheduled_publish_atstring (date-time) | null
author_idinteger
Auteur van het concept als een API-sleutel de aanroep doet (sinds 1.62.0): een actieve gebruiker van de organisatie van de sleutel; de gebruiker wordt created_by en de eerste medeauteur. Verplicht bij een sleutel (anders 422 validation.failed); een gebruiker van een andere organisatie of een inactieve gebruiker geeft 404 users.not_found. De rechten op de collectie en de kaart worden voor de sleutel gecontroleerd, niet voor de auteur. In een sessie is de auteur de aangemelde gebruiker: een andere author_id geeft 422 validation.failed.
≥ 1

Responses

201Gemaakt

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.
Idempotency-Replayed
true: de response is opnieuw afgespeeld uit de opgeslagen response voor deze Idempotency-Key; de bewerking is niet opnieuw uitgevoerd.

application/json

Object: Draft

idintegerverplicht
org_idintegerverplicht
card_idstring | nullverplicht
De kaart die het concept bewerkt; null – een concept van een nieuwe kaart.
collection_idintegerverplicht
collectionstringverplicht
titlestringverplicht
body_markdownstringverplicht
tagsarray of stringverplicht
base_versioninteger | null
Versie van de kaart waarvan het concept is uitgegaan.
scheduled_publish_atstring (date-time) | null
workflow_stateDraftWorkflowStateverplicht
revision_notestring | null
verify_on_publishbooleanverplicht
notify_followersbooleanverplicht
created_byintegerverplicht
updated_byinteger | null
created_atstring (date-time)verplicht
updated_atstring (date-time)verplicht
publish_requested_byinteger | null
publish_requested_atstring (date-time) | null
approved_byinteger | null
approved_atstring (date-time) | null
collaboratorsarray of DraftCollaboratorverplicht
conflictstring | null
card_published – de kaart is gepubliceerd of gewijzigd nadat het concept was begonnen; card_deleted – de kaart is verwijderd; uitbreidbaar.

400Het request is ongeldig: een parameterwaarde of de toestand van het object staat de actie niet toe (`detail` is een melding).

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

401Er zijn geen authenticatiegegevens meegestuurd (geen sessiecookie en geen API-sleutel), of de sleutel is niet gevonden.

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

403De actie is niet toegestaan: de rol volstaat niet, er is geen toegang tot de collectie of kaart, het request draait in de modus “View as”, of de organisatie is opgeschort of verwijderd (`detail` is een object met `code: org_suspended | org_deleted`).

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

404Het object bestaat niet of is niet voor jou beschikbaar. De API bevestigt niet dat een afgeschermd object bestaat.

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

409De toestand van het object staat de actie niet toe, bijvoorbeeld een duplicaat, een lopende indexering of een job die al is verwerkt.

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

422Validatiefout: de body of de parameters komen niet overeen met het schema (`detail` is een lijst met validatiefouten), of een parameterwaarde valt buiten het bereik (`detail` is een melding).

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

429Te veel requests (`api.rate_limited`), het quotum van de organisatie voor de minuut, dag of maand is op (`api.quota_exceeded`; `error.details` bevat `quota`, `limit` en `reset_at`), de limiet van de organisatie is bereikt, of de antwoorddienst is bezet (`answers.engine_busy`). Wacht de tijd af die in de header `Retry-After` staat.

Responseheaders

Retry-After
Aantal seconden dat je moet wachten voordat je het request opnieuw probeert.
RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

Foutcodes

Codes die dit endpoint in error.code kan teruggeven, naast de algemene codes van elk request.

Veilig opnieuw proberen

Stuur bij elke POST en PATCH een header Idempotency-Key mee (bijvoorbeeld een UUID). Een nieuwe poging met dezelfde sleutel binnen 24 uur geeft de opgeslagen response terug, zonder het request opnieuw uit te voeren.

Snelheidslimieten

Responses bevatten de headers RateLimit en RateLimit-Policy en de eerdere X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset. Een response met status 429 bevat Retry-After in seconden: wacht en probeer het daarna opnieuw.

← drafts · API-referentie

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"

Uitproberen

API-sleutel

De sleutel blijft in het geheugen van dit tabblad en wordt alleen naar https://api.sursa.com gestuurd.

Requests werken met de echte gegevens van je organisatie.

Idempotency-Key header

Idempotency-Key

Is dit veld leeg, dan wordt voor elk request een nieuwe sleutel gegenereerd.

Request-body (JSON)