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

# Files API: Upload, List, and Manage Files in Dohoo

> Use the Dohoo Files API to upload images and videos via a secure two-step presigned URL flow, check processing status, and delete files.

The Dohoo Files API lets you upload images and videos to Dohoo-managed storage, check their processing status, retrieve them, and delete them when they're no longer needed. Dohoo uses a two-step presigned URL upload flow: you first request a signed S3 URL from Dohoo, then PUT your file bytes directly to S3. This keeps large uploads fast and avoids routing binary data through Dohoo's servers.

<Note>
  Every request to the Dohoo API (except the S3 PUT in step 2) must include your API key in the `X-API-Key` header.

  ```
  X-API-Key: dh_live_xxxxxxxxxxxxxxxxxxxxxxxx
  ```
</Note>

***

## Step 1 — Get a presigned upload URL

<br />

`POST /api/upload/presigned-url`

Request a short-lived presigned URL from Dohoo. Provide the filename and MIME type of the file you want to upload. Dohoo returns a signed S3 URL along with a `fileId` you'll use to track and reference the file later.

**Request body**

<ParamField body="filename" type="string" required>
  The original filename including its extension (e.g. `my-video.mp4`).
</ParamField>

<ParamField body="contentType" type="string" required>
  The MIME type of the file (e.g. `video/mp4`, `image/jpeg`).
</ParamField>

```bash theme={null}
curl -X POST https://dohoo.ai/api/upload/presigned-url \
  -H "X-API-Key: dh_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"filename": "my-video.mp4", "contentType": "video/mp4"}'
```

**Response**

```json theme={null}
{
  "fileId": "abc123",
  "uploadUrl": "https://s3.amazonaws.com/..."
}
```

Save both values. You'll PUT to `uploadUrl` in step 2, and reference `fileId` in all subsequent API calls.

***

## Step 2 — Upload the file to S3

<br />

`PUT {uploadUrl}`

PUT the raw file bytes directly to the presigned S3 URL you received in step 1. You do **not** need to include your `X-API-Key` header for this request — the URL is already cryptographically signed and authorises the upload on its own.

Set the `Content-Type` header to match the MIME type you specified when requesting the URL.

```bash theme={null}
curl -X PUT "{uploadUrl}" \
  -H "Content-Type: video/mp4" \
  --data-binary @my-video.mp4
```

A `200 OK` from S3 means the upload succeeded. Proceed to check processing status if your file requires transcoding before publishing.

***

## Check upload status

<br />

`GET /api/upload/status/:id`

Returns the current processing status of an uploaded file. Poll this endpoint after uploading a video to confirm it has finished transcoding before you attempt to publish it.

<ParamField path="id" type="string" required>
  The `fileId` returned in step 1.
</ParamField>

```bash theme={null}
curl https://dohoo.ai/api/upload/status/abc123 \
  -H "X-API-Key: dh_live_xxxx"
```

<Tip>
  Poll `GET /api/upload/status/:id` at a short interval (e.g. every 5 seconds) until the status indicates the file is ready before calling a publish endpoint. This prevents publish failures caused by files that are still processing.
</Tip>

***

## List all files

<br />

`GET /api/upload/files`

Returns a list of all files you have uploaded to Dohoo.

```bash theme={null}
curl https://dohoo.ai/api/upload/files \
  -H "X-API-Key: dh_live_xxxx"
```

***

## Get the latest uploaded file

<br />

`GET /api/upload/latest`

Returns metadata for the most recently uploaded file in your account. Useful for quickly referencing the last file you uploaded without having to list all files.

```bash theme={null}
curl https://dohoo.ai/api/upload/latest \
  -H "X-API-Key: dh_live_xxxx"
```

***

## Download a file

<br />

`GET /api/upload/direct/{fileId}`

Returns the file itself as a binary response. Use this endpoint when you need to retrieve the original file contents, for example to serve it from your own infrastructure or archive it locally.

<ParamField path="fileId" type="string" required>
  The unique identifier of the file to download.
</ParamField>

```bash theme={null}
curl https://dohoo.ai/api/upload/direct/abc123 \
  -H "X-API-Key: dh_live_xxxx" \
  --output my-video.mp4
```

***

## Delete a file

<br />

`DELETE /api/upload/file/{fileId}`

Permanently deletes a file from Dohoo storage.

<ParamField path="fileId" type="string" required>
  The unique identifier of the file to delete.
</ParamField>

```bash theme={null}
curl -X DELETE https://dohoo.ai/api/upload/file/abc123 \
  -H "X-API-Key: dh_live_xxxx"
```

<Warning>
  Deleted files cannot be recovered. Make sure you no longer need the file — or have a copy elsewhere — before calling this endpoint.
</Warning>