POST/v1/uploads

Aloita moniosainen lataus

create_upload

Avaa latausistunnon suurelle tiedostolle (enintään asennuksen moniosaisten latausten rajaan asti, oletuksena 5 Gt): nimi, sisältötyyppi, koko ja purpose, joka kertoo, mikä latausta käyttää: card_file (POST /v1/cards), archive (POST /v1/cards/archive) tai import_attachment (mukautetun lähteen asiakirjan liite). Vastauksessa on id (upl_ ja 32 heksadesimaalimerkkiä), osan koko part_size ja osien määrä part_count. Jokainen osa viimeistä lukuun ottamatta on täsmälleen part_size tavua (5–100 MiB), ja viimeinen osa on jäännös. Keskeneräinen lataus säilyy 24 tuntia (expires_at).

Käyttötarkoituksen muotojen ulkopuolinen tiedostotarkenne palauttaa 415 uploads.unsupported_format (tuonnin liite hyväksyy minkä tahansa tarkenteen). Tiedosto, joka on suurempi kuin asennuksen raja tai organisaation paketin mukainen kokonaistallennustila, palauttaa 413 uploads.too_large. Jos tallennustilaa ei ole riittävästi jäljellä, kun organisaation keskeneräiset lataukset otetaan huomioon, palautuu 402 limits.storage.

Osat kulkevat Sursan kautta (PUT /v1/uploads/{upload_id}/parts/{n}) ja salataan tiedostotallennustilassa organisaation avaimella; suoria linkkejä tallennustilaan ei ole. Vain latauksen luonut API-avain tai käyttäjä voi nähdä ja käyttää sitä. Lisätty versiossa 1.62.0.

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

Pyynnön runko

application/json

Objekti: UploadCreate

filenamestringpakollinen
Tiedoston nimi tiedostotarkenteineen; tarkenne määrää muodon.
length ≥ 1, length ≤ 255
content_typestring
Ilmoitettu sisältötyyppi (MIME); sitä verrataan tiedoston sisällön tunnisteeseen.
length ≤ 255
sizeinteger (int64)pakollinen
Tiedoston koko tavuina.
≥ 1
purposeUploadPurposepakollinen
sha256string
Tiedoston SHA-256, jos se tiedetään etukäteen; complete vertaa tiedoston tarkistussummaa siihen.

Vastaukset

201Latausistunto on luotu.

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

idstringpakollinen
Latauksen tunnus (upl_ ja sen perässä 32 heksadesimaalimerkkiä).
purposeUploadPurposepakollinen
filenamestringpakollinen
Tiedoston nimi (ilman kansioita).
content_typestringpakollinen
Ilmoitettu sisältötyyppi; tyhjä, jos sitä ei ole ilmoitettu.
sizeinteger (int64)pakollinen
Tiedoston koko tavuina.
sha256string | nullpakollinen
Tiedoston SHA-256, joka ilmoitettiin luonnissa tai complete-vaiheessa; null, jos sitä ei vielä tiedetä.
statusUploadStatuspakollinen
part_sizeinteger (int64)pakollinen
Kunkin osan koko viimeistä lukuun ottamatta (5–100 MiB).
part_countintegerpakollinen
Osien määrä.
≥ 1, ≤ 1000
parts_receivedintegerpakollinen
Vastaanotettujen osien määrä.
≥ 0
partsarray of UploadPartpakollinen
Vastaanotetut osat numeroittain (tyhjä POST /v1/uploads-vastauksessa).
reject_reasonstring | nullpakollinen
Hylkäyksen syy (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Luettelo voi laajentua; null, jos latausta ei ole hylätty.
reject_detailsobject | nullpakollinen
Hylkäyksen tiedot (tiedostotarkenne, ilmoitettu ja tunnistettu muoto, tarkistussummat); null, jos latausta ei ole hylätty.
created_atstring (date-time)pakollinen
Latauksen luontiaika.
expires_atstring (date-time)pakollinen
Määräaika, johon mennessä lataus on viimeisteltävä ja valmis lataus käytettävä.
completed_atstring (date-time) | nullpakollinen
Milloin tarkistus päättyi (ready tai rejected).
consumed_atstring (date-time) | nullpakollinen
Milloin lataus käytettiin (kortti, arkisto tai tuonti).

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

402Organisaatio on saavuttanut paketin rajan (kortit, tallennustila tai käyttäjät). `error.details` sisältää kentät `kind`, `limit` ja `used`.

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

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.

← uploads · API-viite

curl -X POST 'https://api.sursa.com/v1/uploads' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"filename":"document.pdf","size":1,"purpose":"card_file"}' \
  -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

Idempotency-Key

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

Pyynnön runko (JSON)