# yeet.md API

Two endpoints. Plain JSON over HTTPS. No keys, no accounts.

There is also a read shortcut that needs no API call at all: append
`.md` to any snapshot URL. `https://yeet.md/s/abc123.md` returns the raw
Markdown source as `text/markdown`, exactly as the author wrote it.

> **Always send `Content-Type: application/json`.** Both endpoints reject requests without it with `403 Cross-site form submissions are forbidden`, which is the framework's CSRF protection rather than anything to do with your token.

## Publish a snapshot

POST your Markdown to `/api/share`. On success you get `201 Created` with the snapshot id, public URL, and a delete token. Save the delete token somewhere safe if you ever want to unpublish; it is the only way.

```
POST https://yeet.md/api/share
Content-Type: application/json

{"content": "# Hello\n\nFrom curl."}
```

Response:

```json
{
  "id": "abc123",
  "url": "https://yeet.md/s/abc123",
  "deleteToken": "long-opaque-string"
}
```

### Curl examples

Inline string:

```bash
curl -X POST https://yeet.md/api/share \
  -H "Content-Type: application/json" \
  -d '{"content":"# Hello\n\nFrom curl."}'
```

From a file (needs [jq](https://jqlang.github.io/jq/) for safe JSON encoding):

```bash
jq -Rs '{content: .}' < notes.md \
  | curl -X POST https://yeet.md/api/share \
      -H "Content-Type: application/json" -d @-
```

Print just the URL:

```bash
curl -s -X POST https://yeet.md/api/share \
  -H "Content-Type: application/json" \
  -d "$(jq -Rs '{content: .}' < notes.md)" \
  | jq -r .url
```

## Delete a snapshot

Send a DELETE to `/api/delete/<id>` with the delete token from the publish response. Pass it in a JSON body as `token`, or as a `?token=` query parameter. The link stops working immediately.

```
DELETE https://yeet.md/api/delete/abc123
Content-Type: application/json

{"token": "<deleteToken>"}
```

Curl:

```bash
curl -X DELETE https://yeet.md/api/delete/abc123 \
  -H "Content-Type: application/json" \
  -d '{"token":"YOUR_DELETE_TOKEN"}'
```

The token can also go in a `?token=` query parameter, but the `Content-Type` header is still required and the body must be empty:

```bash
curl -X DELETE "https://yeet.md/api/delete/abc123?token=YOUR_DELETE_TOKEN" \
  -H "Content-Type: application/json" -d ''
```

The JSON body form above is simpler; prefer it.

## Limits

- Content length: 3 characters minimum, 500 KB maximum
- Rate limit: 100 publishes per IP per hour
- HTTPS only. Plain HTTP requests are rejected
- Snapshots published anonymously cannot be edited. Publish a new one and (optionally) delete the old one. Snapshots published while signed in can be edited from your dashboard; the API itself does not expose editing

## Status codes

- `201`: snapshot published (publish only)
- `200`: snapshot deleted (delete only)
- `400`: missing `content`, or content shorter than 3 characters
- `401`: no delete token supplied (delete only)
- `403`: wrong delete token or snapshot not found. Also returned for any request missing `Content-Type: application/json`, as noted above
- `413`: payload too large (over 500 KB)
- `429`: rate limit hit (publish only)
- `503`: storage temporarily unavailable

## OpenAPI

Machine-readable spec: <https://yeet.md/openapi.yaml>
Plugin discovery card: <https://yeet.md/.well-known/ai-plugin.json>

## Acceptable use

Same as the [privacy policy and terms](https://yeet.md/privacy): don't publish illegal, harmful, infringing, or harassing content. Don't use the API to bulk-spam snapshots. The rate limit is generous for human use; if you need higher throughput, get in touch first.