Skip to content

Getting started

Use Raw for a file, or another sample, when the partner system cannot tag events yet. Send the periodic live sample on status. YAS tags events from these records later.

The current maximum is 50 MiB per file (or a lower configured Storage limit). The signed upload credential lasts two hours, and complete is due within 24 hours of minting. Use the declared media Content-Type on the PUT. Pin mint and complete to the API region; do not add the region header to the Storage PUT. Keep the server key on your backend; do not send it to the upload URL, share signed URLs, or include them in logs.

This backend shell example uses curl, jq, an existing registered robot, and a JPEG file. Set API_BASE_URL, SERVER_KEY, PARTNER_ID, ROBOT_ID and FILE in your secure environment first. Do not enable shell tracing.

Terminal window
set -eu
BYTE_LENGTH=$(wc -c < "$FILE" | tr -d ' ')
MINT=$(curl --fail-with-body --silent --show-error \
"$API_BASE_URL/v1/robots/raw/media" \
-H "Authorization: Bearer $SERVER_KEY" \
-H 'x-region: ap-southeast-1' \
-H 'Content-Type: application/json' \
--data "$(jq -n --arg partnerId "$PARTNER_ID" --arg robotId "$ROBOT_ID" \
--argjson byteLength "$BYTE_LENGTH" \
'{partnerId:$partnerId,schemaVersion:"2026-11",sourceSystem:"partner-export",
robotId:$robotId,recordedAt:"2026-11-11T00:00:00Z",timezone:"Asia/Hong_Kong",
contentType:"image/jpeg",byteLength:$byteLength}')")
UPLOAD_URL=$(printf '%s' "$MINT" | jq -er '.uploadUrl')
MEDIA_ID=$(printf '%s' "$MINT" | jq -er '.mediaId')
curl --fail-with-body --silent --show-error -X PUT "$UPLOAD_URL" \
-H 'Content-Type: image/jpeg' --data-binary "@$FILE"
curl --fail-with-body --silent --show-error \
"$API_BASE_URL/v1/robots/raw/media/$MEDIA_ID/complete" \
-H "Authorization: Bearer $SERVER_KEY" \
-H 'x-region: ap-southeast-1' \
-H 'Content-Type: application/json' \
--data "$(jq -n --arg partnerId "$PARTNER_ID" \
'{partnerId:$partnerId,schemaVersion:"2026-11",sourceSystem:"partner-export"}')"
unset MINT UPLOAD_URL

Only a successful complete makes the file ready. A lost complete response can be retried using the same mediaId. 409 upload_incomplete means no completed object is available yet. 422 invalid_media means the size or type does not match; mint a new upload because uploaded objects cannot be overwritten. 410 upload_expired means the completion deadline passed. Every mint creates a new file id, so retry complete before minting another file after an uncertain response.

Media uploads require byteLength and the signed upload → complete flow. Requests containing contentBase64 return 400 invalid_body; no inline media upload is supported. The earlier /v1/robots/raw/media/uploads and /v1/robots/raw/media/uploads/{uploadId}/complete flow also remains compatible, including its sizeBytes, idempotencyKey and resumable upload response. Use its matching completion path and identifier.