# Content-Disposition API
> Parse and build HTTP Content-Disposition headers (RFC 6266, with RFC 5987 filename* encoding). The parse endpoint reads a header into its disposition type (attachment, inline or form-data), its filename — correctly decoding the extended filename*=UTF-8''… form and preferring it over a plain filename exactly as the specification requires — the form-data field name, and any remaining parameters. The build endpoint assembles a correct header from simple fields and, when a filename contains non-ASCII characters (accents, emoji, CJK), automatically emits both an ASCII fallback filename and the percent-encoded filename*, so every browser shows the right download name while older clients still work. Everything is computed locally and deterministically, so it is instant and private — no file is ever fetched or stored. Ideal for file-download and upload endpoints, object storage and CDNs, content gateways and proxies, email and multipart handling, and debugging why a download is mis-named. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This builds and parses the header string itself; it does not serve a file.

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

## Pricing
- **Free** (Free) — 2,935 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 12,450 calls/Mo, 8 req/s
- **Pro** ($24/Mo) — 175,500 calls/Mo, 20 req/s
- **Mega** ($62/Mo) — 920,000 calls/Mo, 50 req/s

## Endpoints

### Disposition

#### `GET /v1/build` — Build a Content-Disposition header

**Parameters:**
- `type` (query, optional, string) — attachment (default), inline or form-data Example: `attachment`
- `filename` (query, optional, string) — The download filename (any Unicode) Example: `report.pdf`
- `name` (query, optional, string) — The form field name (for form-data)
- `ascii_only` (query, optional, string) — true to force a plain ASCII filename

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/contentdisposition-api/v1/build?type=attachment&filename=report.pdf"
```

**Response:**
```json
{
    "data": {
        "content_disposition": "attachment; filename=\"report.pdf\""
    },
    "meta": {
        "timestamp": "2026-06-03T09:25:02.265Z",
        "request_id": "a720162b-b9cc-4b1d-af47-1cc01fe72f70"
    },
    "status": "ok",
    "message": "Build a Content-Disposition header",
    "success": true
}
```

#### `GET /v1/parse` — Parse a Content-Disposition header

**Parameters:**
- `header` (query, required, string) — A Content-Disposition header value Example: `attachment; filename="report.pdf"`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/contentdisposition-api/v1/parse?header=attachment%3B+filename%3D%22report.pdf%22"
```

**Response:**
```json
{
    "data": {
        "name": null,
        "type": "attachment",
        "filename": "report.pdf",
        "parameters": {
            "filename": "report.pdf"
        }
    },
    "meta": {
        "timestamp": "2026-06-03T09:25:02.379Z",
        "request_id": "97b027d2-45aa-4170-a450-7d941e55790d"
    },
    "status": "ok",
    "message": "Parse a Content-Disposition header",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "name": "Content-Disposition API",
        "notes": "Per RFC 6266, filename* (extended, Unicode) takes precedence over a plain filename when both are present. Non-ASCII filenames are emitted as both filename (ASCII fallback) and filename*. This builds and parses the header string — it does not serve a file. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/parse",
                "params": {
                    "header": "a Content-Disposition header value (required)"
                },
                "returns": "the disposition type, filename, form field name and parameters"
            },
            {
                "path": "/v1/build",
                "params": {
                    "name": "the form field name (for form-data)",
                    "type": "attachment (default), inline or form-data",
                    "filename": "the download filename (any Unicode)",
                    "ascii_only": "true to force a plain ASCII filename"
                },
                "returns": "the Content-Disposition header string"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        "description": "Parse and build HTTP Content-Disposition headers (RFC 6266 with RFC 5987 filename* encoding). The parse endpoint reads a header into its disposition type (attachment, inline or 
…(truncated, see openapi.json for full schema)
```


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