# Bencode API
> Encode and decode Bencode (BEP 3) — the serialization format BitTorrent uses for .torrent metainfo files and tracker responses. The encode endpoint turns a JSON value into Bencode: objects become dictionaries with their keys sorted in raw byte order exactly as the spec demands, arrays become lists, whole numbers become integers, and strings become length-prefixed byte strings. The decode endpoint parses Bencode back into a JSON value and enforces the spec strictly — no leading zeros in integers, no negative zero, dictionary keys must be sorted and unique, and no trailing data is tolerated — so malformed input is rejected rather than silently mangled. Binary byte strings that are not valid UTF-8 are represented losslessly as a {"_bytes_hex":"…"} object, so encode and decode round-trip exactly even for the binary "pieces" field of a real torrent. Decode accepts the data either as text or, for genuinely binary payloads, as hex; encode returns both the Bencode text (when printable) and its hex bytes. Everything is computed locally and deterministically, so it is instant and private. Ideal for building and parsing .torrent files, tracker tooling, BitTorrent clients and DHT messages, and teaching how the format works. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is BitTorrent's Bencode specifically; for base64, hex, URL or HTML encoding use a general encoding API, and for JSON, YAML, TOML or XML use those format APIs.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/bencode-api/..."
```

## Pricing
- **Free** (Free) — 5,335 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 14,850 calls/Mo, 8 req/s
- **Pro** ($27/Mo) — 199,500 calls/Mo, 20 req/s
- **Mega** ($65/Mo) — 1,040,000 calls/Mo, 50 req/s

## Endpoints

### Bencode

#### `GET /v1/decode` — Decode Bencode to a JSON value

**Parameters:**
- `bencode` (query, optional, string) — The Bencode text Example: `d3:cow3:moo4:spam4:eggse`
- `hex` (query, optional, string) — Or the raw Bencode bytes as hex (binary .torrent data)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bencode-api/v1/decode?bencode=d3%3Acow3%3Amoo4%3Aspam4%3Aeggse"
```

**Response:**
```json
{
    "data": {
        "bytes": 24,
        "value": {
            "cow": "moo",
            "spam": "eggs"
        }
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:17.858Z",
        "request_id": "221cb14e-c7c8-4ec2-ab41-53f3e78e6f12"
    },
    "status": "ok",
    "message": "Decode from Bencode",
    "success": true
}
```

#### `GET /v1/encode` — Encode a JSON value to Bencode

**Parameters:**
- `json` (query, required, string) — A JSON value to encode Example: `{"cow":"moo","spam":"eggs"}`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bencode-api/v1/encode?json=%7B%22cow%22%3A%22moo%22%2C%22spam%22%3A%22eggs%22%7D"
```

**Response:**
```json
{
    "data": {
        "hex": "64333a636f77333a6d6f6f343a7370616d343a6567677365",
        "bytes": 24,
        "bencode": "d3:cow3:moo4:spam4:eggse"
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:17.955Z",
        "request_id": "58d1290b-e355-4dba-9b32-2fed678518b3"
    },
    "status": "ok",
    "message": "Encode to Bencode",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bencode-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "name": "Bencode API",
        "notes": "Bencode has four types: byte strings, integers, lists and dictionaries. There is no boolean, null or float — torrents use 0/1 and integers. Dictionary keys are always emitted sorted by raw byte order. This is BitTorrent's format; for base64/hex/URL/HTML use a general encoding API and for JSON/YAML/TOML/XML use those format APIs. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/encode",
                "params": {
                    "json": "a JSON value to encode (string)"
                },
                "returns": "the Bencode text (when printable), its hex, and byte length"
            },
            {
                "path": "/v1/decode",
                "params": {
                    "hex": "or the raw Bencode bytes as hex (for binary .torrent data)",
                    "bencode": "the Bencode text"
                },
                "returns": "the decoded JSON value"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        "description": "Encode and decode Bencode (BEP 3) — the serialization format used by BitTorrent for .torrent metainfo files and tracker responses. The encode endpoint turns a JSON value into Bencode (objects become dictionaries with keys sorted in raw byte order as the spec requires, arrays become lists,
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/bencode-api
OpenAPI spec: https://www.oanor.com/api/bencode-api/openapi.json