> ## Documentation Index
> Fetch the complete documentation index at: https://www.dropfans.io/developers/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /api/external/drops — Create a sellable drop from vault items

> Packages up to 10 vault items into a drop and returns a checkout URL.

- Source: https://www.dropfans.io/developers/reference/create-drop
- Section: API reference
- OpenAPI: https://www.dropfans.io/developers/openapi.json

Packages up to 10 vault items into a drop and returns a checkout URL.

Price is USD **dollars**: either `0` (free) or between $5 and $750. Use APPROVED vault items — the drop inherits its moderation status from its media, so a drop built from approved items is sellable (and attachable to a post) immediately, while one containing PENDING items waits for review. Hand the buyer the returned `buyUrl`, or build a Telegram link from [GET /api/external/links](https://www.dropfans.io/developers/reference/get-links.md)' `telegram.buyTemplate`.

> [!WARNING] `description` is validated but NOT stored
> The `description` field runs through the prohibited-word filter and is then deliberately discarded — it is never shown anywhere on Dropfans. You get a 200 with no indication it was dropped. Treat it as a moderation input only.

## Authentication

`Authorization: Bearer dpfn_...` — an API key generated in the creator's dashboard (Vault → API Connect). One key = one creator. Missing or invalid keys return 401 `{"error":"Unauthorized","code":"unauthorized"}`.

## Request body (application/json)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string |  | Drop title, shown at checkout. Falsy values are stored as null. |
| `description` | string |  | Checked for prohibited words, then discarded — never persisted or displayed. |
| `price` | number | yes | USD dollars. 0 = free; otherwise $5–$750. |
| `allowDownload` | boolean |  | Whether buyers may download the files after purchase. |
| `vaultItemIds` | string[] | yes | 1–10 vault item ids, in display order. The first becomes the cover. |

Example — A $25 three-item drop:

```json
{
  "name": "Beach set — 6 photos",
  "price": 25,
  "vaultItemIds": [
    "clxv1a2b30001item",
    "clxv1a2b30002item",
    "clxv1a2b30003item"
  ]
}
```

## Responses

### 200

Created. Keep the productId — sales polling, previews and post attachment all key on it.

| Field | Type | Required | Description |
|---|---|---|---|
| `productId` | string | yes | The new drop’s id — keep it: check-status, GET /drops/{id}, previews and post attachment all key on it. |
| `buyUrl` | string | yes | Web checkout URL to hand to the buyer. For a Telegram Mini App link, substitute the productId into telegram.buyTemplate from GET /api/external/links. |
| `mediaCount` | integer | yes | How many vault items were attached. |

```json
{
  "productId": "clxdr0p000001prod",
  "buyUrl": "https://www.dropfans.io/buy/clxdr0p000001prod",
  "mediaCount": 3
}
```

## Errors

| Status | Body | When |
|---|---|---|
| 400 | `{"error":"Invalid price"}` | `price` missing, not a number, NaN or negative. |
| 400 | `{"error":"The minimum price is $5. Set the price to free or at least $5."}` | Priced above 0 but below $5. |
| 400 | `{"error":"The maximum price on Dropfans is $750. To request an increase, contact support@dropfans.io."}` | Priced above $750. |
| 400 | `{"error":"Field \"name\" contains a prohibited word: \"…\"","field":"name","matchedWord":"…"}` | The name or description tripped the word filter — a three-field envelope unique to this endpoint (posts use a two-field 422 for the same class of failure). |
| 400 | `{"error":"vaultItemIds must be a non-empty array"}` | Missing or empty media list. |
| 400 | `{"error":"Maximum 10 media items allowed per drop"}` | More than 10 ids. |
| 400 | `{"error":"Cannot use hidden vault items"}` | One of the items was deleted (hidden). |
| 401 | `{"error":"Unauthorized","code":"unauthorized"}` | Missing or invalid API key. |
| 403 | `{"error":"You do not own all selected vault items"}` | An id belongs to another creator. |
| 404 | `{"error":"One or more vault items not found"}` | An id does not exist. |
| 500 | `{"error":"Failed to create drop"}` | Write failed — retry later. |

## Notes

The drop's moderation status is computed from its media at creation (REJECTED/FLAGGED wins, else PENDING if any item is pending, else APPROVED). Read it back with [GET /api/external/drops/{id}](https://www.dropfans.io/developers/reference/get-drop.md).

## Rate limiting

Per-key fixed windows by tier (Personal 60/min · 5,000/day; approved apps 300/min · 50,000/day; Dropfans-operated integrations exempt). Read the live values from X-RateLimit-Tier, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and their -Day variants; a 429 carries Retry-After and `{"error":"Rate limit exceeded","code":"rate_limited"}`. See [Rate limits](https://www.dropfans.io/developers/concepts/rate-limits.md).

## Code samples

### curl

```bash
curl -X POST "https://www.dropfans.io/api/external/drops" \
  -H "Authorization: Bearer $DROPFANS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Beach set — 6 photos",
  "price": 25,
  "vaultItemIds": [
    "clxv1a2b30001item",
    "clxv1a2b30002item",
    "clxv1a2b30003item"
  ]
}'
```

### Node

```javascript
const res = await fetch(`https://www.dropfans.io/api/external/drops`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Beach set — 6 photos",
    "price": 25,
    "vaultItemIds": [
      "clxv1a2b30001item",
      "clxv1a2b30002item",
      "clxv1a2b30003item"
    ]
  }),
});
console.log(await res.json());
```

### Python

```python
import os
import requests

res = requests.post(
    "https://www.dropfans.io/api/external/drops",
    headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
    json={
        "name": "Beach set — 6 photos",
        "price": 25,
        "vaultItemIds": [
            "clxv1a2b30001item",
            "clxv1a2b30002item",
            "clxv1a2b30003item",
        ],
    },
)
print(res.json())
```

## OpenAPI

```json
{
  "method": "POST",
  "path": "/api/external/drops",
  "operationId": "createDrop",
  "tags": [
    "drops"
  ],
  "summary": "Create a sellable drop from vault items",
  "description": "Packages up to 10 vault items into a drop and returns a checkout URL.\n\nPrice is USD **dollars**: either `0` (free) or between $5 and $750. Use APPROVED vault items — the drop inherits its moderation status from its media, so a drop built from approved items is sellable (and attachable to a post) immediately, while one containing PENDING items waits for review. Hand the buyer the returned `buyUrl`, or build a Telegram link from [GET /api/external/links](https://www.dropfans.io/developers/reference/get-links.md)' `telegram.buyTemplate`.\n\n> [!WARNING] `description` is validated but NOT stored\n> The `description` field runs through the prohibited-word filter and is then deliberately discarded — it is never shown anywhere on Dropfans. You get a 200 with no indication it was dropped. Treat it as a moderation input only.",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Drop title, shown at checkout. Falsy values are stored as null.",
              "example": "Beach set — 6 photos"
            },
            "description": {
              "type": "string",
              "description": "Checked for prohibited words, then discarded — never persisted or displayed."
            },
            "price": {
              "type": "number",
              "description": "USD dollars. 0 = free; otherwise $5–$750.",
              "example": 25,
              "minimum": 0,
              "maximum": 750
            },
            "allowDownload": {
              "type": "boolean",
              "description": "Whether buyers may download the files after purchase.",
              "default": true
            },
            "vaultItemIds": {
              "type": "array",
              "items": {
                "type": "string",
                "description": "A vault item you own."
              },
              "description": "1–10 vault item ids, in display order. The first becomes the cover.",
              "maxItems": 10
            }
          },
          "required": [
            "price",
            "vaultItemIds"
          ]
        },
        "examples": {
          "paidDrop": {
            "summary": "A $25 three-item drop",
            "value": {
              "name": "Beach set — 6 photos",
              "price": 25,
              "vaultItemIds": [
                "clxv1a2b30001item",
                "clxv1a2b30002item",
                "clxv1a2b30003item"
              ]
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Created. Keep the productId — sales polling, previews and post attachment all key on it.",
      "headers": {
        "X-RateLimit-Tier": {
          "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).",
          "schema": {
            "type": "string",
            "enum": [
              "personal",
              "app",
              "first_party"
            ]
          }
        },
        "X-RateLimit-Limit": {
          "description": "Requests allowed per minute for this key (absent on first_party).",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Remaining": {
          "description": "Requests left in the current minute window.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Reset": {
          "description": "Epoch seconds when the minute window resets.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Limit-Day": {
          "description": "Requests allowed per UTC day for this key (absent on first_party).",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Remaining-Day": {
          "description": "Requests left in the current UTC day window.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Reset-Day": {
          "description": "Epoch seconds when the day window resets.",
          "schema": {
            "type": "integer"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "productId": {
                "type": "string",
                "description": "The new drop’s id — keep it: check-status, GET /drops/{id}, previews and post attachment all key on it.",
                "example": "clxdr0p000001prod"
              },
              "buyUrl": {
                "type": "string",
                "description": "Web checkout URL to hand to the buyer. For a Telegram Mini App link, substitute the productId into telegram.buyTemplate from GET /api/external/links.",
                "format": "uri",
                "example": "https://www.dropfans.io/buy/clxdr0p000001prod"
              },
              "mediaCount": {
                "type": "integer",
                "description": "How many vault items were attached.",
                "example": 3
              }
            },
            "required": [
              "productId",
              "buyUrl",
              "mediaCount"
            ]
          },
          "example": {
            "productId": "clxdr0p000001prod",
            "buyUrl": "https://www.dropfans.io/buy/clxdr0p000001prod",
            "mediaCount": 3
          }
        }
      }
    },
    "400": {
      "description": "`price` missing, not a number, NaN or negative. Also: Priced above 0 but below $5. Also: Priced above $750. Also: The name or description tripped the word filter — a three-field envelope unique to this endpoint (posts use a two-field 422 for the same class of failure). Also: Missing or empty media list. Also: More than 10 ids. Also: One of the items was deleted (hidden).",
      "headers": {
        "X-RateLimit-Tier": {
          "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).",
          "schema": {
            "type": "string",
            "enum": [
              "personal",
              "app",
              "first_party"
            ]
          }
        },
        "X-RateLimit-Limit": {
          "description": "Requests allowed per minute for this key (absent on first_party).",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Remaining": {
          "description": "Requests left in the current minute window.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Reset": {
          "description": "Epoch seconds when the minute window resets.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Limit-Day": {
          "description": "Requests allowed per UTC day for this key (absent on first_party).",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Remaining-Day": {
          "description": "Requests left in the current UTC day window.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Reset-Day": {
          "description": "Epoch seconds when the day window resets.",
          "schema": {
            "type": "integer"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Human-readable message describing what went wrong.",
                "example": "Vault item not found"
              }
            },
            "required": [
              "error"
            ]
          },
          "example": {
            "error": "Invalid price"
          }
        }
      }
    },
    "401": {
      "description": "Missing or invalid API key.",
      "headers": {
        "X-RateLimit-Tier": {
          "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).",
          "schema": {
            "type": "string",
            "enum": [
              "personal",
              "app",
              "first_party"
            ]
          }
        },
        "X-RateLimit-Limit": {
          "description": "Requests allowed per minute for this key (absent on first_party).",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Remaining": {
          "description": "Requests left in the current minute window.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Reset": {
          "description": "Epoch seconds when the minute window resets.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Limit-Day": {
          "description": "Requests allowed per UTC day for this key (absent on first_party).",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Remaining-Day": {
          "description": "Requests left in the current UTC day window.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Reset-Day": {
          "description": "Epoch seconds when the day window resets.",
          "schema": {
            "type": "integer"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Human-readable message.",
                "example": "Rate limit exceeded"
              },
              "code": {
                "type": "string",
                "description": "Machine-readable code: unauthorized, app_suspended, first_party_only, rate_limited, username_required.",
                "example": "rate_limited"
              }
            },
            "required": [
              "error",
              "code"
            ]
          },
          "example": {
            "error": "Unauthorized",
            "code": "unauthorized"
          }
        }
      }
    },
    "403": {
      "description": "An id belongs to another creator.",
      "headers": {
        "X-RateLimit-Tier": {
          "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).",
          "schema": {
            "type": "string",
            "enum": [
              "personal",
              "app",
              "first_party"
            ]
          }
        },
        "X-RateLimit-Limit": {
          "description": "Requests allowed per minute for this key (absent on first_party).",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Remaining": {
          "description": "Requests left in the current minute window.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Reset": {
          "description": "Epoch seconds when the minute window resets.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Limit-Day": {
          "description": "Requests allowed per UTC day for this key (absent on first_party).",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Remaining-Day": {
          "description": "Requests left in the current UTC day window.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Reset-Day": {
          "description": "Epoch seconds when the day window resets.",
          "schema": {
            "type": "integer"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Human-readable message describing what went wrong.",
                "example": "Vault item not found"
              }
            },
            "required": [
              "error"
            ]
          },
          "example": {
            "error": "You do not own all selected vault items"
          }
        }
      }
    },
    "404": {
      "description": "An id does not exist.",
      "headers": {
        "X-RateLimit-Tier": {
          "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).",
          "schema": {
            "type": "string",
            "enum": [
              "personal",
              "app",
              "first_party"
            ]
          }
        },
        "X-RateLimit-Limit": {
          "description": "Requests allowed per minute for this key (absent on first_party).",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Remaining": {
          "description": "Requests left in the current minute window.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Reset": {
          "description": "Epoch seconds when the minute window resets.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Limit-Day": {
          "description": "Requests allowed per UTC day for this key (absent on first_party).",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Remaining-Day": {
          "description": "Requests left in the current UTC day window.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Reset-Day": {
          "description": "Epoch seconds when the day window resets.",
          "schema": {
            "type": "integer"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Human-readable message describing what went wrong.",
                "example": "Vault item not found"
              }
            },
            "required": [
              "error"
            ]
          },
          "example": {
            "error": "One or more vault items not found"
          }
        }
      }
    },
    "429": {
      "description": "Rate limit exceeded for the current minute or day window. Wait Retry-After seconds and retry.",
      "headers": {
        "X-RateLimit-Tier": {
          "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).",
          "schema": {
            "type": "string",
            "enum": [
              "personal",
              "app",
              "first_party"
            ]
          }
        },
        "X-RateLimit-Limit": {
          "description": "Requests allowed per minute for this key (absent on first_party).",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Remaining": {
          "description": "Requests left in the current minute window.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Reset": {
          "description": "Epoch seconds when the minute window resets.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Limit-Day": {
          "description": "Requests allowed per UTC day for this key (absent on first_party).",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Remaining-Day": {
          "description": "Requests left in the current UTC day window.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Reset-Day": {
          "description": "Epoch seconds when the day window resets.",
          "schema": {
            "type": "integer"
          }
        },
        "Retry-After": {
          "description": "Seconds to wait before retrying (sent with 429s).",
          "schema": {
            "type": "integer"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Human-readable message.",
                "example": "Rate limit exceeded"
              },
              "code": {
                "type": "string",
                "description": "Machine-readable code: unauthorized, app_suspended, first_party_only, rate_limited, username_required.",
                "example": "rate_limited"
              }
            },
            "required": [
              "error",
              "code"
            ]
          },
          "example": {
            "error": "Rate limit exceeded",
            "code": "rate_limited"
          }
        }
      }
    },
    "500": {
      "description": "Write failed — retry later.",
      "headers": {
        "X-RateLimit-Tier": {
          "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).",
          "schema": {
            "type": "string",
            "enum": [
              "personal",
              "app",
              "first_party"
            ]
          }
        },
        "X-RateLimit-Limit": {
          "description": "Requests allowed per minute for this key (absent on first_party).",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Remaining": {
          "description": "Requests left in the current minute window.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Reset": {
          "description": "Epoch seconds when the minute window resets.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Limit-Day": {
          "description": "Requests allowed per UTC day for this key (absent on first_party).",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Remaining-Day": {
          "description": "Requests left in the current UTC day window.",
          "schema": {
            "type": "integer"
          }
        },
        "X-RateLimit-Reset-Day": {
          "description": "Epoch seconds when the day window resets.",
          "schema": {
            "type": "integer"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Human-readable message describing what went wrong.",
                "example": "Vault item not found"
              }
            },
            "required": [
              "error"
            ]
          },
          "example": {
            "error": "Failed to create drop"
          }
        }
      }
    }
  },
  "x-codeSamples": [
    {
      "lang": "cURL",
      "label": "curl",
      "source": "curl -X POST \"https://www.dropfans.io/api/external/drops\" \\\n  -H \"Authorization: Bearer $DROPFANS_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"Beach set — 6 photos\",\n  \"price\": 25,\n  \"vaultItemIds\": [\n    \"clxv1a2b30001item\",\n    \"clxv1a2b30002item\",\n    \"clxv1a2b30003item\"\n  ]\n}'"
    },
    {
      "lang": "JavaScript",
      "label": "Node",
      "source": "const res = await fetch(`https://www.dropfans.io/api/external/drops`, {\n  method: 'POST',\n  headers: {\n    Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    \"name\": \"Beach set — 6 photos\",\n    \"price\": 25,\n    \"vaultItemIds\": [\n      \"clxv1a2b30001item\",\n      \"clxv1a2b30002item\",\n      \"clxv1a2b30003item\"\n    ]\n  }),\n});\nconsole.log(await res.json());"
    },
    {
      "lang": "Python",
      "source": "import os\nimport requests\n\nres = requests.post(\n    \"https://www.dropfans.io/api/external/drops\",\n    headers={\"Authorization\": f\"Bearer {os.environ['DROPFANS_API_KEY']}\"},\n    json={\n        \"name\": \"Beach set — 6 photos\",\n        \"price\": 25,\n        \"vaultItemIds\": [\n            \"clxv1a2b30001item\",\n            \"clxv1a2b30002item\",\n            \"clxv1a2b30003item\",\n        ],\n    },\n)\nprint(res.json())"
    }
  ],
  "x-dropfans-docs": "https://www.dropfans.io/developers/reference/create-drop"
}
```

---

Previous: [Check video transcoding status (batch)](https://www.dropfans.io/developers/reference/video-status.md) · Next: [Read back a drop](https://www.dropfans.io/developers/reference/get-drop.md) · All pages: [llms.txt](https://www.dropfans.io/developers/llms.txt)