POST/v1/cards/text

Luo tekstikortti (Markdown)

create_text_card

Luo tekstikortin Markdown-tekstistä (kind=text). Se indeksoidaan samalla tavalla kuin ladattu tiedosto. Kun async=true, indeksointi asetetaan jonoon: vastaus palautuu heti, ja edistyminen on nähtävissä kohteessa /v1/jobs.

Todennus

Lähetä API-avain Authorization-otsakkeessa: Authorization: Bearer <avain>.

Otsakeparametrit

Idempotency-Keystring
Avain kirjoituksen turvalliseen uusintayritykseen: 1–255 tulostettavaa ASCII-merkkiä; suositus on yksi UUID v4 jokaista loogista toimintoa kohden. Uusintayritys samalla avaimella 24 tunnin kuluessa ei suorita toimintoa uudelleen: se palauttaa tallennetun vastauksen (tila, otsakkeet ja runko) Idempotency-Replayed: true -otsakkeella. Sama avain eri metodilla, polulla, Content-Type-arvolla tai rungolla palauttaa 409 api.idempotency_mismatch; kun ensimmäinen pyyntö on vielä käynnissä, vastaus on 409 api.idempotency_in_progress ja Retry-After: 1. 5xx- tai 429-vastauksen jälkeen avain vapautuu, ja uusintayritys suorittaa toiminnon uudelleen. Avain on sidottu organisaatioon ja kutsujaan (API-avain, käyttäjä tai mukautetun lähteen avain).
length ≥ 1, length ≤ 255
X-View-Asstring
Vain API-avaimille, joilla on admin-rooli. Suorittaa pyynnön dataprofiilin <profile>[:viewer|verifier|editor] puolesta, esimerkiksi employee:viewer. Asennusavain ei voi käyttää tätä otsaketta (403).

Evästeparametrit

kb_view_asstring
Istunnon ”View as” -tilan eväste. POST /auth/view-as asettaa sen ja DELETE /auth/view-as poistaa sen.

Pyynnön runko

application/json

Objekti: TextCardRequest

titlestringpakollinen
length ≥ 1, length ≤ 200
collectionstring
Oletus: "default"
body_markdownstring
Kortin teksti Markdown-muodossa; content_type ei koske sitä. Sen sijaan voi välittää body-kentän.
length ≥ 1, length ≤ 500000
tagsarray of string | null
items ≤ 30
categorystring | null
length ≤ 60
sensitiveboolean | null
owner_idinteger | null
asyncboolean
Oletus: false
bodystring
Kortin teksti content_type-muodossa. Välitä joko body tai body_markdown; molempien välittäminen palauttaa 422 validation.failed.
length ≥ 1, length ≤ 500000
content_typeCardTextContentType
collection_idinteger | null
Kokoelma tunnuksen mukaan. Jos myös collection välitetään, collection_id ratkaisee. Kokoelma, jota organisaatiossa ei ole tai joka ei näy, palauttaa 404 collections.not_found.
folder_idstring | null
Kokoelman kansio, johon kortti sijoitetaan, samoin tarkistuksin kuin tiedoston latauksen folder_id. Toisen kokoelman kansio palauttaa 400 folders.card_collection_mismatch, puuttuva kansio palauttaa 404 folders.not_found, ja jos kansioon ei ole COLLECTION_EDIT_CARDS-käyttöoikeutta, tulos on 403 authz.forbidden.
length ≤ 64
external_idstring | null
Uuden kortin external_id. Jos organisaation toinen kortti käyttää sitä, pyyntö palauttaa 409 cards.external_id_taken. Kun haluat luoda tai korvata kortin external_id-tunnuksen mukaan, käytä PUT /v1/cards-by-external-id/{external_id}.
length ≤ 512
metadataMetadataPatch

Vastaukset

200Onnistunut vastaus

Vastausotsakkeet

RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.
Idempotency-Replayed
true tarkoittaa, että vastaus toistettiin tälle Idempotency-Key-arvolle tallennetusta vastauksesta: toimintoa ei suoritettu uudelleen.

application/json

Objekti: TextCardResult

statusstringpakollinen
Sallitut arvot: readyerrorskippedqueued
cardCard | nullpakollinen
tablesinteger
timingsobject
Kentät
- total_snumber
errorstring
reasonstring
duplicatetrue
card_idstring | null
job_idinteger
jobJob

400Pyyntö on virheellinen: parametrin arvo tai objektin tila ei salli toimenpidettä (`detail` on viesti).

Vastausotsakkeet

RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

401Tunnistetietoja ei lähetetty (ei istuntoevästettä eikä API-avainta), tai avainta ei löytynyt.

Vastausotsakkeet

RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

403Toimenpide ei ole sallittu: rooli ei riitä, kokoelmaan tai korttiin ei ole käyttöoikeutta, pyyntö suoritetaan ”View as” -tilassa, tai organisaation toiminta on keskeytetty tai organisaatio on poistettu (`detail` on objekti, jossa on `code: org_suspended | org_deleted`).

Vastausotsakkeet

RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

404Objektia ei ole tai se ei ole saatavillasi. API ei paljasta, onko rajoitettu objekti olemassa.

Vastausotsakkeet

RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

409Objektin tila ei salli toimenpidettä, esimerkiksi kaksoiskappale, käynnissä oleva indeksointi tai jo käsitelty työ.

Vastausotsakkeet

RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

422Validointivirhe: runko tai parametrit eivät vastaa skeemaa (`detail` on validointivirheiden lista), tai parametrin arvo on sallitun alueen ulkopuolella (`detail` on viesti).

Vastausotsakkeet

RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

429Liian monta pyyntöä (`api.rate_limited`), organisaation minuutti-, päivä- tai kuukausikiintiö on käytetty (`api.quota_exceeded`; `error.details` sisältää kentät `quota`, `limit` ja `reset_at`), organisaation raja on saavutettu tai vastauspalvelu on kuormitettu (`answers.engine_busy`). Odota `Retry-After`-otsakkeen ilmoittama aika.

Vastausotsakkeet

Retry-After
Kuinka monta sekuntia odotetaan ennen pyynnön uusintayritystä.
RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

Virhekoodit

Koodit, jotka tämä päätepiste voi palauttaa error.code-kentässä kaikkien pyyntöjen yleisten koodien lisäksi.

Turvalliset uusintayritykset

Lähetä jokaisen POST- ja PATCH-pyynnön mukana Idempotency-Key-otsake (esimerkiksi UUID). Kun pyyntö toistetaan samalla avaimella 24 tunnin kuluessa, palautetaan tallennettu vastaus eikä pyyntöä suoriteta uudelleen.

Nopeusrajoitukset

Vastauksissa ovat RateLimit- ja RateLimit-Policy-otsakkeet sekä aiemmat X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset. 429-vastauksessa on Retry-After sekunteina: odota ja yritä uudelleen.

← cards · API-viite

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

Kokeile

API-avain

Avain säilyy vain tämän välilehden muistissa, ja se lähetetään ainoastaan osoitteeseen https://api.sursa.com.

Pyynnöt kohdistuvat organisaatiosi todellisiin tietoihin.

Idempotency-Key header

X-View-As header

Idempotency-Key

Jos kenttä on tyhjä, jokaiselle pyynnölle luodaan uusi avain.

Pyynnön runko (JSON)