# HTTP Reference API
> A clean, programmatic reference for HTTP semantics, built on the official IANA registries. Look up any status code with its reason phrase and class (404 → Not Found, Client Error; 503 → Service Unavailable, Server Error), list a whole class (4xx, 5xx…); look up any method with its safe/idempotent flags (GET → safe + idempotent, POST → neither, DELETE → idempotent); or look up / search the 255 registered HTTP header fields (Content-Type, Authorization, …) with their registration status. Ideal for API tooling, HTTP clients, documentation, linters, learning resources and error pages.

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

## Pricing
- **Free** (Free) — 20,000 calls/Mo, 2 req/s
- **Starter** ($2/Mo) — 150,000 calls/Mo, 8 req/s
- **Pro** ($6/Mo) — 700,000 calls/Mo, 20 req/s
- **Mega** ($18/Mo) — 3,500,000 calls/Mo, 50 req/s

## Endpoints

### HTTP

#### `GET /v1/header` — A header field, search, or all

**Parameters:**
- `name` (query, optional, string) — Header field, e.g. Content-Type Example: `Content-Type`
- `q` (query, optional, string) — Substring search of field names
- `limit` (query, optional, string) — Max results when listing (1-255) Example: `50`
- `offset` (query, optional, string) — Pagination offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/http-api/v1/header?name=Content-Type&limit=50&offset=0"
```

**Response:**
```json
{
    "data": {
        "name": "Content-Type",
        "status": "permanent",
        "reference": "[RFC 9110, Section 8.3: HTTP Semantics]",
        "structured_type": null
    },
    "meta": {
        "timestamp": "2026-05-31T05:48:02.245Z",
        "request_id": "6b848203-dd1c-4e7a-874c-58ec00eef7be"
    },
    "status": "ok",
    "message": "Header field retrieved",
    "success": true
}
```

#### `GET /v1/method` — An HTTP method (safe/idempotent), or all

**Parameters:**
- `name` (query, optional, string) — Method, e.g. GET (omit to list all) Example: `GET`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/http-api/v1/method?name=GET"
```

**Response:**
```json
{
    "data": {
        "safe": true,
        "method": "GET",
        "reference": "[RFC9110, Section 9.3.1]",
        "idempotent": true
    },
    "meta": {
        "timestamp": "2026-05-31T05:48:02.315Z",
        "request_id": "1000c756-0a59-4095-8d52-cd9240d258a5"
    },
    "status": "ok",
    "message": "Method retrieved",
    "success": true
}
```

#### `GET /v1/status` — A status code, a class, or all

**Parameters:**
- `code` (query, optional, string) — Status code, e.g. 404 Example: `404`
- `class` (query, optional, string) — Class, e.g. 4xx or "Client Error" (omit to list all)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/http-api/v1/status?code=404"
```

**Response:**
```json
{
    "data": {
        "code": 404,
        "message": "Not Found",
        "category": "Client Error",
        "reference": "[RFC9110, Section 15.5.5]"
    },
    "meta": {
        "timestamp": "2026-05-31T05:48:02.395Z",
        "request_id": "d9ab6da1-443e-4a5f-8ec4-f1506eb75934"
    },
    "status": "ok",
    "message": "Status code retrieved",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Totals & status-class breakdown

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

**Response:**
```json
{
    "data": {
        "note": "Registered HTTP semantics from IANA. Methods carry safe/idempotent flags; status codes carry their class.",
        "source": "IANA HTTP registries (status codes, methods, field names)",
        "methods": 41,
        "endpoints": [
            "/v1/status",
            "/v1/method",
            "/v1/header",
            "/v1/meta"
        ],
        "status_codes": 63,
        "header_fields": 255,
        "status_by_class": [
            {
                "class": "Informational",
                "count": 5
            },
            {
                "class": "Success",
                "count": 10
            },
            {
                "class": "Redirection",
                "count": 8
            },
            {
                "class": "Client Error",
                "count": 29
            },
            {
                "class": "Server Error",
                "count": 11
            }
        ]
    },
    "meta": {
        "timestamp": "2026-05-31T05:48:02.465Z",
        "request_id": "9823c09e-6b09-4845-b8b3-0d5f1f980215"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


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