# URI Schemes API
> The IANA Uniform Resource Identifier (URI) Schemes registry as an API — all 413 registered schemes (http, https, mailto, tel, ftp, ssh, magnet, bitcoin, geo, did, …). Look up any scheme to get its description, registration status (Permanent, Provisional or Historical) and defining reference; search by name or description; or list all schemes filtered by status. Ideal for URL parsers and validators, link handlers, deep-linking, security allow-lists and developer tooling that needs to recognise or vet URI schemes.

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

## Pricing
- **Free** (Free) — 25,000 calls/Mo, 2 req/s
- **Starter** ($2/Mo) — 200,000 calls/Mo, 8 req/s
- **Pro** ($5/Mo) — 900,000 calls/Mo, 20 req/s
- **Mega** ($15/Mo) — 4,000,000 calls/Mo, 50 req/s

## Endpoints

### URI Schemes

#### `GET /v1/list` — All schemes (optionally by status)

**Parameters:**
- `status` (query, optional, string) — Filter by status
- `limit` (query, optional, string) — Max results (1-413, default 50) Example: `50`
- `offset` (query, optional, string) — Pagination offset Example: `0`

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

**Response:**
```json
{
    "data": {
        "count": 50,
        "limit": 50,
        "total": 413,
        "offset": 0,
        "status": null,
        "results": [
            {
                "scheme": "aaa",
                "status": "Permanent",
                "template": null,
                "reference": "[RFC6733]",
                "description": "Diameter Protocol",
                "well_known_support": "-"
            },
            {
                "scheme": "aaas",
                "status": "Permanent",
                "template": null,
                "reference": "[RFC6733]",
                "description": "Diameter Protocol with Secure Transport",
                "well_known_support": "-"
            },
            {
                "scheme": "about",
                "status": "Permanent",
                "template": null,
                "reference": "[RFC6694]",
                "description": null,
                "well_known_support": "-"
            },
            {
                "scheme": "acap",
                "status": "Permanent",
                "template": null,
                "reference": "[RFC2244]",
                "description": "application configuration access protocol",
                "well_known_support": "-"
            },
            {
                "scheme": "acct",
                "status": "Permanent",
                "template": null,
                "reference": "[RFC7565]",
                "description": null,
                "well_known_support
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/scheme` — A single URI scheme

**Parameters:**
- `scheme` (query, required, string) — Scheme name, e.g. mailto (a trailing ":" is accepted) Example: `mailto`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/urischemes-api/v1/scheme?scheme=mailto"
```

**Response:**
```json
{
    "data": {
        "scheme": "mailto",
        "status": "Permanent",
        "template": null,
        "reference": "[RFC6068]",
        "description": "Electronic mail address",
        "well_known_support": "-"
    },
    "meta": {
        "timestamp": "2026-05-31T05:48:02.000Z",
        "request_id": "0ae5e821-4d9b-444f-9232-570eefe0fba4"
    },
    "status": "ok",
    "message": "Scheme retrieved",
    "success": true
}
```

#### `GET /v1/search` — Search schemes by name or description

**Parameters:**
- `q` (query, required, string) — Keyword, e.g. mail Example: `mail`
- `status` (query, optional, string) — Permanent | Provisional | Historical
- `limit` (query, optional, string) — Results per page (1-100, default 20) Example: `20`
- `offset` (query, optional, string) — Pagination offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/urischemes-api/v1/search?q=mail&limit=20&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 4,
        "limit": 20,
        "query": "mail",
        "total": 4,
        "offset": 0,
        "status": null,
        "results": [
            {
                "scheme": "mailserver",
                "status": "Historical",
                "template": null,
                "reference": "[RFC6196]",
                "description": "Access to data available from mail servers",
                "well_known_support": "-"
            },
            {
                "scheme": "mailto",
                "status": "Permanent",
                "template": null,
                "reference": "[RFC6068]",
                "description": "Electronic mail address",
                "well_known_support": "-"
            },
            {
                "scheme": "ms-settings-emailandaccounts",
                "status": "Provisional",
                "template": "prov/ms-settings-emailandaccounts",
                "reference": "[urischemeowners_at_microsoft.com]",
                "description": null,
                "well_known_support": "-"
            },
            {
                "scheme": "mupdate",
                "status": "Permanent",
                "template": null,
                "reference": "[RFC3656]",
                "description": "Mailbox Update (MUPDATE) Protocol",
                "well_known_support": "-"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-05-31T05:48:02.074Z",
        "request_id": "40b4567d-c6f0-45
…(truncated, see openapi.json for full schema)
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "Permanent = standardised; Provisional = registered but not standardised; Historical = deprecated.",
        "total": 413,
        "fields": [
            "scheme",
            "description",
            "status",
            "template",
            "well_known_support",
            "reference"
        ],
        "source": "IANA Uniform Resource Identifier (URI) Schemes registry",
        "by_status": [
            {
                "count": 99,
                "status": "Permanent"
            },
            {
                "count": 296,
                "status": "Provisional"
            },
            {
                "count": 18,
                "status": "Historical"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-05-31T05:48:02.147Z",
        "request_id": "e7c364a3-14d9-4a12-9f2c-68882055a55c"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


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