Get started

API / Cookbook / 05

Attach a file to a session

Keep the report, patch or screenshot a run produced next to its transcript. You send the bytes and their hash; Tracez checks them, stores them under your account and hands back an id.

RESTMCPGraphQLLive

Upload, verify, link
actor you: Your script
actor tz: Tracez API
actor obj: Object storage
you -> tz: POST /api/artifacts (raw bytes, X-Content-SHA256)
note tz: session is yours and not redacted?
note tz: hash matches what you declared?
tz -> obj: store bytes under your account
tz --> you: 201 {id, sha256, size}
opt network dropped, so you retry
you -> tz: same session, name and bytes
tz --> you: 201 with the same id
end

Steps

  1. Upload the bytes

    Send the file as the body. Up to 32 MiB per artifact.

    curl https://tracez.recurz.ai/api/artifacts \
  -H "Authorization: Bearer $RECURZ_TOKEN" \
  -H "X-Session-Id: SESSION_ID" \
  -H "X-Artifact-Name: report.html" \
  -H "Content-Type: text/html" \
  -H "X-Content-SHA256: $(shasum -a 256 report.html | cut -d' ' -f1)" \
  --data-binary @report.html
    {"accepted":true,"id":"ARTIFACT_ID","sha256":"…","size":48213}

  2. Retry without worrying

    The id comes from the session, name and content hash, so the same upload twice gives the same artifact. A body that doesn't match X-Content-SHA256 is refused with checksum_mismatch.

  3. List and download

    GET /api/artifacts?session=SESSION_ID
GET /api/artifacts/ARTIFACT_ID/content

    Downloads check ownership again and always arrive as an attachment, with the original type in X-Artifact-Media-Type.

From an agent or GraphQL, call putArtifact with session_id, name, media_type, content_base64 and an optional sha256. Uploads are explicit: Tracez never collects local files by itself.