# API Requests

### Base URL

```
https://your-domain.com/api/v1
```

***

### Rate Limits

* **POST /pastes** → 20 req/min per IP
* **GET /pastes** → 10 req/min per IP

Headers in every response:

* `X-RateLimit-Limit`
* `X-RateLimit-Remaining`
* `X-RateLimit-Reset`

***

### Authentication

No authentication required. All endpoints are public (with rate limits).

***

### Endpoints

#### 1. Create Paste

**POST** `/pastes`

<table><thead><tr><th>Field</th><th>Type</th><th width="173">Required</th><th>Notes</th></tr></thead><tbody><tr><td><code>content</code></td><td>string</td><td>✅</td><td>Paste text (1MB)</td></tr><tr><td><code>title</code></td><td>string</td><td>❌</td><td>Max 100 chars</td></tr><tr><td><code>language</code></td><td>string</td><td>❌</td><td>Syntax highlighting</td></tr><tr><td><code>visibility</code></td><td>string</td><td>❌</td><td><code>public</code>, <code>unlisted</code>, <code>private</code></td></tr><tr><td><code>burnAfterRead</code></td><td>boolean</td><td>❌</td><td>Delete after first view</td></tr><tr><td><code>expiration</code></td><td>string</td><td>❌</td><td><code>never</code>, <code>1hour</code>, <code>1day</code>, <code>1week</code>, <code>1month</code></td></tr><tr><td><code>password</code></td><td>string</td><td>❌</td><td>Protect paste</td></tr><tr><td><code>maxViews</code></td><td>number</td><td>❌</td><td>1–1000 views</td></tr></tbody></table>

**Example:**

```bash
curl -X POST https://your-domain.com/api/v1/pastes \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Hello World",
    "content": "console.log(\"Hello, World!\");",
    "language": "javascript",
    "visibility": "public",
    "expiration": "1week"
  }'
```

***

#### 2. Retrieve Paste

**GET** `/pastes?id={pasteId}`

| Param | Type   | Required | Description |
| ----- | ------ | -------- | ----------- |
| `id`  | string | ✅        | Paste ID    |

**Example:**

```bash
curl "https://your-domain.com/api/v1/pastes?id=abc123def"
```

***

### Error Codes

| Code                  | Meaning                   |
| --------------------- | ------------------------- |
| `INVALID_JSON`        | Bad JSON body             |
| `EMPTY_BODY`          | Request body missing      |
| `VALIDATION_ERROR`    | Missing/invalid fields    |
| `CONTENT_TOO_LARGE`   | Exceeds 1MB               |
| `TITLE_TOO_LONG`      | Title >100 chars          |
| `INVALID_EXPIRATION`  | Wrong expiration value    |
| `RATE_LIMIT_EXCEEDED` | Too many requests         |
| `MISSING_ID`          | Paste ID required         |
| `PASTE_NOT_FOUND`     | Paste does not exist      |
| `PASTE_EXPIRED`       | Paste expired             |
| `PASTE_BURNED`        | Burn-after-read triggered |
| `MAX_VIEWS_REACHED`   | View limit hit            |
| `DATABASE_ERROR`      | DB issue                  |

***

### Examples

#### Simple text

```bash
curl -X POST https://your-domain.com/api/v1/pastes \
  -H "Content-Type: application/json" \
  -d '{"content": "My notes"}'
```

#### Code snippet

```bash
-d '{
  "title": "React Component",
  "content": "function App(){return <div>Hello</div>}",
  "language": "javascript"
}'
```

#### Private + password

```bash
-d '{
  "content": "api_key=secret123",
  "visibility": "private",
  "password": "mypassword"
}'
```

#### Burn after read

```bash
-d '{
  "content": "One-time secret",
  "burnAfterRead": true
}'
```

#### Limited views

```bash
-d '{
  "content": "5-view paste",
  "maxViews": 5
}'
```

***

### Supported Languages

DrakoPaste supports **90+ languages and formats**.

* **Web**: `javascript`, `typescript`, `jsx`, `tsx`, `html`, `css`, `scss`
* **General**: `python`, `java`, `csharp`, `cpp`, `c`, `go`, `rust`, `php`, `ruby`, `swift`
* **Functional**: `haskell`, `clojure`, `elixir`, `erlang`, `fsharp`, `ocaml`
* **Shell & Scripts**: `bash`, `zsh`, `powershell`, `batch`
* **Data/Config**: `json`, `yaml`, `toml`, `ini`, `xml`, `csv`
* **Database**: `sql`, `plsql`, `mongodb`
* **Docs**: `markdown`, `latex`, `asciidoc`
* **DevOps**: `docker`, `terraform`, `kubernetes`, `nginx`, `apache`
* **Other**: `regex`, `diff`, `git`, `protobuf`, `graphql`, `solidity`, `wasm`, `assembly`
* **Scientific/Legacy**: `r`, `matlab`, `julia`, `fortran`, `cobol`, `pascal`

👉 For plain text, use `text` or leave `language` empty.

***

### Client Examples

#### Node.js

```javascript
const res = await fetch("https://your-domain.com/api/v1/pastes", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ content: "console.log('Hello')" })
});
console.log(await res.json());
```

#### Python

```python
import requests
res = requests.post("https://your-domain.com/api/v1/pastes", json={
  "content": "print('Hello')"
})
print(res.json())
```