# Bytes API
> Humanize, parse and convert byte sizes. Turn a raw byte count into a human-readable string (1610612736 → 1.5 GiB or 1.61 GB), parse a human size back into bytes ("1.5 GiB", "2GB", "500 kB" → the exact integer), and convert an amount between any two units. Handles both the IEC binary units (KiB, MiB, GiB, TiB — powers of 1024) and the SI decimal units (kB, MB, GB, TB — powers of 1000), with configurable decimal places and case-insensitive unit names. Perfect for dashboards and admin UIs, file-upload limits, storage and bandwidth reporting, logs and CLI output. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 4 endpoints. Distinct from file-type detection and from number/unit measurement conversion.

## 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/bytes-api/..."
```

## Pricing
- **Free** (Free) — 880 calls/Mo, 2 req/s
- **Starter** ($2/Mo) — 7,300 calls/Mo, 8 req/s
- **Pro** ($20/Mo) — 131,000 calls/Mo, 20 req/s
- **Mega** ($56/Mo) — 675,000 calls/Mo, 50 req/s

## Endpoints

### Bytes

#### `GET /v1/convert` — Convert between units

**Parameters:**
- `value` (query, required, string) — Amount Example: `1`
- `from` (query, optional, string) — Source unit (default B) Example: `GiB`
- `to` (query, required, string) — Target unit Example: `MiB`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bytes-api/v1/convert?value=1&from=GiB&to=MiB"
```

**Response:**
```json
{
    "data": {
        "to": "mib",
        "from": "gib",
        "bytes": 1073741824,
        "value": 1,
        "result": 1024
    },
    "meta": {
        "timestamp": "2026-06-02T16:51:45.645Z",
        "request_id": "0eac6448-1643-4553-a9f5-1d5d5a8fa3f2"
    },
    "status": "ok",
    "message": "Convert between units",
    "success": true
}
```

#### `GET /v1/format` — Humanize a byte count

**Parameters:**
- `bytes` (query, required, string) — Byte count Example: `1610612736`
- `system` (query, optional, string) — si|iec (default iec) Example: `iec`
- `decimals` (query, optional, string) — 0-10 (default 2) Example: `2`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bytes-api/v1/format?bytes=1610612736&system=iec&decimals=2"
```

**Response:**
```json
{
    "data": {
        "si": "1.61 GB",
        "iec": "1.5 GiB",
        "bytes": 1610612736,
        "human": "1.5 GiB",
        "system": "iec"
    },
    "meta": {
        "timestamp": "2026-06-02T16:51:45.752Z",
        "request_id": "e07695d6-434e-4db7-83df-99494fe49d27"
    },
    "status": "ok",
    "message": "Humanize a byte count",
    "success": true
}
```

#### `GET /v1/parse` — Parse a size string to bytes

**Parameters:**
- `value` (query, required, string) — e.g. 1.5 GiB, 2GB, 500 kB Example: `1.5 GiB`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bytes-api/v1/parse?value=1.5+GiB"
```

**Response:**
```json
{
    "data": {
        "bytes": 1610612736,
        "input": "1.5 GiB",
        "system": "iec"
    },
    "meta": {
        "timestamp": "2026-06-02T16:51:45.871Z",
        "request_id": "bb00821f-683c-4183-997f-15ba1994e9ed"
    },
    "status": "ok",
    "message": "Parse a size string to bytes",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "name": "Bytes API",
        "notes": "SI uses powers of 1000 (kB, MB, GB); IEC uses powers of 1024 (KiB, MiB, GiB). Unit names are case-insensitive.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/format",
                "params": {
                    "bytes": "a byte count (required)",
                    "system": "si|iec (default iec)",
                    "decimals": "0-10 (default 2)"
                },
                "returns": "human string + both si and iec forms"
            },
            {
                "path": "/v1/parse",
                "params": {
                    "value": "\"1.5 GiB\", \"2GB\", \"500 kB\" (required)"
                },
                "returns": "the size in bytes"
            },
            {
                "path": "/v1/convert",
                "params": {
                    "to": "target unit (required)",
                    "from": "source unit (default B)",
                    "value": "amount (required)"
                },
                "returns": "converted value + bytes"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        "description": "Humanize, parse and convert byte sizes in both SI (kB, MB, GB — 1000) and IEC (KiB, MiB, GiB — 1024) units. Pure local, no key."
    },
    "meta": {
        "timestamp": "2026-06-02T16:51:45.983Z",
 
…(truncated, see openapi.json for full schema)
```


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