Send to Kindle by API or from the command line

How do I send to my Kindle by API?

curl -X POST https://dropkind.app/api/v1/drops \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F url=https://example.com/article

The API replies with the drop it just created. Poll it while the status is processing; stop on sent (delivered), needs_action, or failed — the last two carry a detail sentence saying what to do next:

{
  "id": 42,
  "status": "processing",
  "title": "Example article",
  "web_url": "https://dropkind.app/uploads/42",
  "created_at": "2026-07-30T09:15:00Z"
}

Send a document instead of a URL:

curl -X POST https://dropkind.app/api/v1/drops \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F file=@paper.pdf

Or push plain text — notes, a draft, anything:

curl -X POST https://dropkind.app/api/v1/drops \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --form-string "text=Some notes to read on paper" \
  --form-string "title=My notes"

How do I send to Kindle from the terminal?

The CLI is a single bash file with no dependencies beyond curl. Install it and paste your token once:

curl -fsSL https://dropkind.app/install.sh | sh
dropkind login

Then send URLs, files, or whatever is in your clipboard:

dropkind send https://example.com/article
dropkind send paper.pdf --title "Attention Is All You Need"
pbpaste | dropkind send - --title "Clipboard notes"
dropkind status 42

The token is stored in ~/.config/dropkind/token. Scripts and CI can set the DROPKIND_TOKEN environment variable instead.

The installer puts a single file into /usr/local/bin or ~/.local/bin, nothing else. Prefer to do it by hand? Download https://dropkind.app/cli/dropkind, make it executable, and put it on your PATH.

Works on macOS and Linux; on Windows, use WSL.

API reference

Authentication

Every request carries your token in the Authorization header. Tokens start with dk_ and belong to one account; regenerating a token revokes the previous one.

Authorization: Bearer dk_your_token_here

Endpoints

Drop statuses

A needs_action drop explains itself — the numbers, the smallest credit pack that covers the gap, and a ready-made sentence to show your user:

{
  "id": 42,
  "status": "needs_action",
  "title": "Two-column paper",
  "web_url": "https://dropkind.app/uploads/42",
  "created_at": "2026-07-30T09:15:00Z",
  "action": {
    "reason": "pdf_credits_required",
    "credits_required": 12,
    "credits_available": 2,
    "credits_missing": 10,
    "suggested_pack_credits": 20,
    "suggested_pack_price_usd": "2.99"
  },
  "detail": "Converting this PDF costs 12 credits and 2 are available. Buy at least 10 more (smallest covering pack: 20 credits for $2.99) at https://dropkind.app/uploads/42."
}

Errors

Every error is JSON with a stable, machine-readable code:

{ "error": "Invalid or missing API token", "code": "invalid_token" }

Limits and formats

The rate limit is 30 requests per minute per account.

Accepted files: PDF, EPUB, DOC, DOCX, TXT, RTF, HTML, Markdown, and images (PNG, JPG, GIF, BMP).

Notes for LLM agents

This API is designed to be driven by agents: every state and error carries a stable code, and a needs_action response includes exact numbers plus a detail sentence you can relay to your user verbatim. To send something to a person's Kindle, ask them for a token from https://dropkind.app/settings/api and POST as shown above — plain multipart, no SDK required.

Frequently asked questions