API reference

Get a media upload

The session's status: which parts arrived, the vault item once completed, and its moderation status.

View as MarkdownUpdated Oct 31, 2026

GET/api/external/v1/media/uploads/{id}also served at /api/external/media/uploads/{id}New

The session's status: which parts arrived, the vault item once completed, and its moderation status.

Poll this after complete until moderationStatus leaves PENDING — every 15–30 seconds is plenty. Sessions are kept for 30 days.

Authentication

Send the creator's API key as a bearer token: Authorization: Bearer dpfn_…. See Authentication & API keys.

For a creator you manage or onboarded

GET /api/external/v1/creators/{creatorId}/media/uploads/{id} — an agency's own key for a creator or AI persona it manages (needs canManageVault), or your app owner's own key for an account your app onboarded. The X-Dropfans-Account header still works but is deprecated. See Acting for a creator.

Path parameters

Name	Type	Required	Description
`id`	string	Required	The upload `id` from POST /api/external/v1/media/uploads.

Responses

200The session.

Name Type Description

id string Upload id.

kind

string

What you are uploading.

One of: image, video, audio

status

string

uploading until you complete it; processing while a complete runs; completed once the vault item exists.

One of: uploading, processing, completed, failed, expired

fileName string The file name, stored on the vault item.

contentType string The stored content type.

sizeBytes integer The declared size.

folderId string | null The vault folder the item goes in.

partSize integer | null Image / audio: bytes per part (the last part is the remainder). Null for video.

totalParts integer | null Image / audio: number of parts. Null for video.

receivedParts integer[] | null Part numbers received so far.

missingParts integer[] | null Part numbers still to upload.

vaultItemId string | null The vault item, once completed.

moderationStatus

string | null

The vault item’s moderation status, once completed.

One of: PENDING, APPROVED, FLAGGED, REJECTED

bunnyStreamId string | null Video: the Stream video id — poll [video-status](/developers/reference/video-status) with it.

error

object | null

{ code, message } when the upload failed or expired.

Show child attributes

`code`	string	Machine-readable reason.
`message`	string \| null	Human-readable reason.

expiresAt

string

Upload the parts (or the tus bytes) and complete before this.

Format: date-time

createdAt

string

When the session was opened.

Format: date-time

completedAt

string | null

When it completed.

Format: date-time

Example response

{
  "id": "mu_3f9c1a7be0d24c55a1e8b6f2",
  "kind": "image",
  "status": "completed",
  "fileName": "beach.jpg",
  "contentType": "image/jpeg",
  "sizeBytes": 7904267,
  "folderId": null,
  "partSize": 3145728,
  "totalParts": 3,
  "receivedParts": [
    1,
    2,
    3
  ],
  "missingParts": [],
  "vaultItemId": "clxv9z8y70003item",
  "moderationStatus": "PENDING",
  "bunnyStreamId": null,
  "error": null,
  "expiresAt": "2026-10-31T18:00:00.000Z",
  "createdAt": "2026-10-31T10:00:00.000Z",
  "completedAt": "2026-10-31T10:00:41.000Z"
}

Errors

Status	Body	When
401	`{"error":"Unauthorized","code":"unauthorized"}`	Missing or invalid API key.
404	`{"error":"Upload not found","code":"upload_not_found"}`	Unknown id, or an upload of another account.
400	`{"error":"X-Dropfans-Account must be an account id (from GET /api/external/agency/creators), not a username.","code":"invalid_account_header"}`	`X-Dropfans-Account` is not an account id.
400	`{"error":"X-Dropfans-Account names a different account than the path — send one or the other.","code":"account_mismatch"}`	Called under /v1/creators/{creatorId}/ with an `X-Dropfans-Account` naming another account.
403	`{"error":"This key cannot act for that account.","code":"account_not_managed"}`	The creator in the path (or `X-Dropfans-Account`) is one this key cannot act for: no ACCEPTED management by your agency and not an account your app onboarded (or it no longer holds a key bound to your app), a key minted for one creator, or someone is suspended, banned or deleted. An unknown id gets the same answer.
403	`{"error":"The agency does not have permission for this on that account.","code":"permission_denied","permission":"canManageVault"}`	For a managed creator: the agency lacks `canManageVault` on that account.
403	`{"error":"This app does not have the vault API category enabled. Contact support to enable it.","code":"api_category_disabled","category":"vault"}`	Your app has the Vault [API category](/developers/concepts/api-categories) switched off.

Rate limiting

Every response carries the X-RateLimit-Tier header and, on limited tiers, the per-minute and per-day trios — read X-RateLimit-Remaining and X-RateLimit-Reset instead of hardcoding limits. Details in Rate limits.

Code samples

curl "https://www.dropfans.io/api/external/v1/media/uploads/$VAULT_ITEM_ID" \
  -H "Authorization: Bearer $DROPFANS_API_KEY"

const vaultItemId = '…'; // from an earlier response

const res = await fetch(`https://www.dropfans.io/api/external/v1/media/uploads/${vaultItemId}`, {
  headers: {
    Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
  },
});
console.log(await res.json());

import os
import requests

vault_item_id = "…"  # from an earlier response

res = requests.get(
    f"https://www.dropfans.io/api/external/v1/media/uploads/{vault_item_id}",
    headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
)
print(res.json())

← Previous

Complete a media upload

Create a sellable drop from vault items

Questions? [email protected]