---
title: API
description: Upload, list and delete drops over HTTP with a bearer token.
---

Send `Authorization: Bearer <token>` with every request. The token can be the admin token or a [named token](/v1.0/tokens) with the right permission.

## Upload

`POST /api/items` with the file as the request body. Needs the **upload** permission.

| Parameter | Where | |
| --- | --- | --- |
| `name` | query | File name, with the extension that picks highlighting. Default `paste.txt` |
| `slug` | query | Readable link path. Default: random |
| `expires` | query | `12h`, `7d` and so on. Default: never |
| `X-Drop-Password` | header | Require a password to open it |
| `Content-Type` | header | The file's type |

Returns `201` with `{ "slug": "k3x9...", "url": "https://drop.example.com/k3x9..." }`.

## List

`GET /api/items` returns every drop: `slug`, `name`, `size`, `type`, `uploaded`, `locked`, `expires`, `url`. Needs the **list** permission.

## Delete

`DELETE /api/items/<slug>` returns `204`. Needs the **delete** permission.

## Tokens

`GET /api/token` returns the calling token's `name`, `sender` and `permissions`.

`POST /api/tokens` creates a named token. It needs the admin token. Send a form with `name`, an optional `sender`, one `permissions` field per permission (`upload`, `list`, `delete`) and an optional `avatar` file. Returns `201` with `{ "token": "jd_…", "name", "sender", "permissions" }`; the token is shown only here.

## Read a drop

`GET /<slug>?format=json` describes any drop without a token: its name, sender, expiry and `raw` URL, plus the files of a folder or the transcript and moments of a recording. A locked drop needs its password in an `X-Drop-Password` header. See [Agents](/v1.0/agents) for the full shape.

## Errors

| Status | Meaning |
| --- | --- |
| `400` | Bad slug or expiry |
| `401` | Missing or wrong token, or a token without the permission |
| `409` | Slug taken |
| `411` | No `Content-Length` |
| `413` | Over the upload limit |
| `429` | More than 60 requests a minute |