Files

Upload a file

POST /api/upload uploads audio for existing integrations. Send JSON to your assigned legacy API origin with a legacy bearer token. For v2 image effects, attach the source image directly to the multipart request.

Field	Type	Description
`file_name`	string	Required. Use a unique base file name without directory separators. Keep the same name across chunks.
`file_chunk`	string	Required. Base64-encoded bytes for one chunk.
`start_byte`	integer	Required. Zero-based offset in the original file. Start at zero and send chunks in order.
`end_byte`	integer	Required. Exclusive end offset. Use `start_byte` plus the number of decoded bytes in the chunk.

The example uploads a short audio file in one request. Set LEGACY_API_ORIGIN to the assigned origin without a trailing slash or /api, and set LEGACY_ACCESS_TOKEN to your legacy session token.

audio_file='sample.m4a'
file_name="sample-$(date +%s).m4a"
byte_count=$(wc -c < "$audio_file" | tr -d '[:space:]')

base64 < "$audio_file" | tr -d '\n' |
  jq -Rs --arg name "$file_name" --argjson bytes "$byte_count" \
    '{file_name: $name, file_chunk: ., start_byte: 0, end_byte: $bytes}' |
  curl --fail-with-body --silent --show-error "$LEGACY_API_ORIGIN/api/upload" \
    -H "Authorization: Bearer $LEGACY_ACCESS_TOKEN" \
    -H 'Content-Type: application/json' --data-binary @-

HTTP 200 acknowledges the offsets for the chunk. For example, a first chunk of 1,024 bytes returns:

{"status":"success","start_byte":0,"end_byte":1024}

400 confirms a missing or invalid file field or byte range. Read the error string and correct the request.
401 indicates an authentication failure. Check the legacy token and the API origin.
409 means the requested offset would leave a gap. The response includes size, the current number of bytes stored. Check which bytes have already been uploaded, then resume from that offset.

After uploading all bytes, pass the same file_name to transcribe audio. Treat result URLs as opaque. The current storage serves public URLs. Anyone with the URL can access the file while it is available.

App retention settings

Backapp operators configure File retention hours for each app in the management panel. For a tracked file, Backapp applies that setting when its file record is created. For example, a setting of 24 makes new files eligible for cleanup 24 hours after their record is created. Leaving the setting blank gives new files no scheduled expiry. Changing the setting preserves expiry dates on existing records. Upload requests follow the app setting. There is no request-level expiry field. Cleanup runs hourly and can defer deletion after a recent write or a storage error. Download results within your app’s retention window. The URL can return HTTP 404 after cleanup.

Get started

Subscriptions

AI

Examples

Troubleshooting

Files

Upload a file

App retention settings