POST/v1/push/sources/{source_id}/documents

Lähetä asiakirja (luo tai korvaa)

push_upsert_document

Luo tai korvaa asiakirjan external_id-tunnuksen perusteella. JSON-muodossa lähetä sisältö content-kentässä (content_type: html, markdown tai text, enintään 5 Mt). multipart/form-data-muodossa lähetä tiedosto file-osassa (enintään 100 Mt, samat muodot kuin tietopankkiin ladattaessa) ja metatiedot document-osassa (samanmuotoinen JSON ilman content-kenttää) tai erillisinä kenttinä external_id, title, url, path, tags. sync_number on avoimen synkronoinnin numero. Ilman sitä asiakirja kirjoitetaan heti (suora kirjoitus), mutta seuraava täysi synkronointi poistaa sen, ellei sitä lähetetä uudelleen. Saman asiakirjan lähettäminen uudelleen palauttaa unchanged (idempotentti). Asiakirjasta tulee kortti lähteen seuraavassa synkronoinnissa (minuutin kuluessa; avoimen synkronoinnin sisällä sen sulkemisen jälkeen). Versiosta 1.62.0 alkaen: kortin kentät (metadata, category, verifiers, verify_interval_days), tiedosto moniosaisesta latauksesta (upload_id) ja liitteet (attachments); vastaus sisältää status- ja card_id-kentät (asiakirjan tulos). Lähteen asiakirjaraja riippuu paketista.

Todennus

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

Polkuparametrit

source_idintegerpakollinen

Kyselyparametrit

sync_numberinteger

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

Pyynnön runko

application/json

Objekti: PushDocument

external_idstringpakollinen
Asiakirjan pysyvä tunnus järjestelmässäsi. Saman tunnuksen lähettäminen korvaa asiakirjan.
length ≤ 512
titlestringpakollinen
length ≤ 500
urlstring
Linkki asiakirjaan järjestelmässäsi (http tai https).
contentstring
Sisältö (enintään 5 Mt).
content_typestring
Sallitut arvot: htmlmarkdowntext
Oletus: "html"
patharray of string | string
Asiakirjan kansiot: nimien taulukko tai merkkijono, jossa erottimena on ”/” (enintään 10 tasoa).
permissionsPushPermissions
tagsarray of string
items ≤ 50
author_emailstring
Tekijä. Tulee kortin omistajaksi, jos hän on Sursan käyttäjä.
updated_atstring (date-time)
Muokkausaika järjestelmässäsi (osa asiakirjan versiota).
metadataMetadataPatch
Asiakirjan kortin metadata (versiosta 1.62.0 alkaen): objekti korvaa kortin aiemmat metatiedot, {} poistaa kaikki parit; ilman metadata-kenttää kortin metatiedot eivät muutu.
categorystring
Kortin luokka: organisaation luokan avain (GET /v1/categories), versiosta 1.62.0 alkaen.
length ≤ 64
verifiersPushVerifiers
verify_interval_daysinteger
Kortin vahvistusväli päivinä (versiosta 1.62.0 alkaen); ilman sitä käytetään lähteen väliä.
≥ 1, ≤ 3650
upload_idstring
Asiakirjan tiedosto moniosaisesta latauksesta (upl_…, versiosta 1.62.0 alkaen) content-kentän sijaan. Latauksen voi käyttää kerran; saman asiakirjan lähettäminen uudelleen samalla upload_id-tunnuksella ei kuluta sitä. Niin kauan kuin moniosaiset lataukset eivät ole käytettävissä asennuksessa, asiakirja hylätään syyllä file_rejected.
length ≤ 64
attachmentsarray of string
Asiakirjan liitteet moniosaisina latauksina (upl_…, versiosta 1.62.0 alkaen): kustakin tulee lähteen oma kortti, jolla on sama kansio, samat käyttöoikeudet ja samat kortin kentät. Liite, joka puuttuu asiakirjan uudesta versiosta, arkistoidaan.
items ≤ 20

multipart/form-data

filestring (binary)pakollinen
documentstring
Asiakirjan JSON-metatiedot (PushDocument-kentät ilman content-kenttää).
external_idstring
titlestring
urlstring
pathstring
tagsstring

Vastaukset

200Kirjoitettu

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: PushDocumentResult

external_idstringpakollinen
resultstringpakollinen
skipped: atomic-erän asiakirjaa ei käsitelty, koska toinen asiakirja hylättiin (versiosta 1.62.0 alkaen).
Sallitut arvot: createdupdatedunchangeddeletednot_founderrorskipped
versionstring
Asiakirjan versio (sisällön ja metatietojen SHA-256).
errorstring
Syy (kun result = error).
statusPushDocumentStatusValue
card_idstring | null
Asiakirjan kortti, jos se on jo kirjoitettu (versiosta 1.62.0 alkaen).
reasonPushDocumentReason

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

413Pyynnön runko ylittää sallitun koon.

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

415Tiedostomuotoa ei tueta.

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.

← sources · API-viite

curl -X POST 'https://api.sursa.com/v1/push/sources/1/documents' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"crm-1042","title":"Refund policy"}' \
  -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

source_id path *

sync_number query

Idempotency-Key

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

Pyynnön runko (JSON)