> ## Documentation Index
> Fetch the complete documentation index at: https://docs.backapp.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Files

> Understand file uploads, result URLs, and retention.

## 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](https://docs.backapp.dev/quickstart.md), 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.

```bash theme={null}
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:

```json theme={null}
{"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](https://docs.backapp.dev/legacy-ai.md#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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.