Evidence API

Evidence-rivi on yksi istunnon aikana tallennettu artefakti — tilannekuva, valkotaulu, videoleike, tallenne tai ladattu dokumentti. Jokainen rivi kantaa sha256 + byte_size + mime , jotta eheydenvarmennusketju voi todistaa, ettei tavuja peukaloitu tallennuksen ja auditoinnin välillä.

Evidence-objekti

{
  "id": "ev-7f3a...",
  "session": "0c8f4d2e-1a3b-4c5d-9e7f-1234567890ab",
  "kind": "snapshot",
  "status": "ready",
  "mime": "image/jpeg",
  "byte_size": 184523,
  "sha256": "f9cc12fda76c30dcc9bee627baed6c9e8fe11b813313de70b1463f9f73e5e418",
  "captured_at": "2026-05-23T10:14:02.481Z",
  "created_at": "2026-05-23T10:14:02.917Z",
  "completed_at": "2026-05-23T10:14:03.211Z"
}

Lajit

Laji	Tallentaja	Huomiot
`snapshot`	Operaattori tai kenttäpuoli	Yksittäinen pysäytyskuva (JPEG). Yleisin laji.
`whiteboard`	Operaattori	Excalidraw-vienti — PNG + kanoninen JSON. Katso Valkotaulut.
`clip`	Operaattori	Lyhyt MP4-leike live-istunnosta — käytetään kenttäkäyttäjän demonstroiman liikkeen tallentamiseen.
`recording`	Järjestelmä	Koko istunnon tallenne. Jälkikäsitelty libx264 medium / crf20:een istunnon päätyttyä.
`document`	Operaattori	Tiedostoliite istunnon aikaisesta chatista (PDF:t, valokuvat jne.). Perusta PDF-allekirjoitukselle.

Status

Status	Merkitys
`pending`	Rivi luotu; tavut eivät vielä objektitallennuksessa.
`uploading`	Multipart-lataus käynnissä.
`ready`	Tavut on tallennettu; sha256 + byte_size on viimeistelty. Vain `ready` -rivit ovat ladattavissa.
`failed`	Tallennus tai lataus keskeytyi. `completed_at` on null.

Listaa istunnon todisteet

GET /api/v1/public/sessions/{session_id}/evidence — laajuus evidence:read

curl "https://app.nexbasira.com/api/v1/public/sessions/0c8f.../evidence?kind=snapshot&limit=50" \
  -H "Authorization: Bearer nb_sec_..."

Kyselyparametrit

Parametri	Tyyppi	Huomiot
`kind`	string	Suodatin — yksi näistä: `snapshot`, `whiteboard`, `clip`, `recording`, `document`.
`limit`	int	Maksimi 100. Oletuksena 25.
`cursor`	opaque	Edellisen vastauksen `next_cursor`.

Hae allekirjoitettu lataus-URL

GET /api/v1/public/evidence/{evidence_id}/download — laajuus evidence:read

Palauttaa lyhytikäisen esiallekirjoitetun URL:n, josta asiakas hakee raakatavut. URL osoittaa suoraan objektitallennuksen taustajärjestelmään, joten lataukset ohittavat sovelluspalvelimemme — ei kaistanleveyden egress-maksuja sinun päästäsi julkista API:a.

curl "https://app.nexbasira.com/api/v1/public/evidence/ev-7f3a.../download" \
  -H "Authorization: Bearer nb_sec_..."

{
  "url": "https://s3.eu-central-1.amazonaws.com/nb-prod-evidence/orgs/.../snapshot.jpg?X-Amz-Algorithm=...",
  "expires_in_seconds": 900,
  "sha256": "f9cc12fda76c30dcc9bee627baed6c9e8fe11b813313de70b1463f9f73e5e418",
  "byte_size": 184523,
  "mime": "image/jpeg",
  "kind": "snapshot"
}

Kutsu uudelleen, kun URL vanhenee — ei nopeusrajarangaistusta toistuvista muodostuksista. Latauksen jälkeen tiivistä tavut SHA-256:lla ja vertaa palautettuun sha256 :een varmentaaksesi, että tiedosto on ehjä päästä päähän.

# integrity check — Python
import hashlib, requests
r = requests.get(presigned["url"]); r.raise_for_status()
assert hashlib.sha256(r.content).hexdigest() == presigned["sha256"]

Yleiset virheet

Status	Koodi	Milloin
403	`permission_denied`	Tunnisteelta puuttuu `evidence:read`.
404	`not_found`	Evidence-riviä ei ole olemassa tunnisteen organisaatiossa.
409	`evidence_not_ready`	Lataus pyydetty riviltä, jonka `status` ei ole `ready`.
410	`retention_expired`	Organisaation säilytyskäytäntö on ohittanut rivin ikärajan; tavut on poistettu objektitallennuksesta.

Huomiot

Ei POST/PATCH/DELETE. Todisteet tallennetaan asiakaspuolella (operaattori + kenttä-SPA) istunnon aikana. Julkinen API on vain luku tässä resurssissa.
Säilytys. Jokainen organisaatio määrittää säilytysikkunan (oletus 7 vuotta eIDAS-yhteensopiville asennuksille). Ikkunan jälkeen objektitallennuksen elinkaarisäännöt poistavat tavut; rivi jää, jottei auditointiketju katkea, mutta /download palauttaa 410:n.
Ankkuroitu auditointiketjuun. Jokainen ready -rivi lisää sha256:nsa istuntokohtaiseen tiivisteketjuun, joka ankkuroidaan TSA:han istunnon päättyessä. Ketjun pää + TSA-kuitti ovat tavoitettavissa SPA-puolen audit-verify-päätepisteen kautta.