# chmod API
> A Unix file-permission calculator as an API. Convert a symbolic permission string (rwxr-xr-x) to its octal mode (755) and back, and explain any mode in plain English with a per-class breakdown (owner / group / others, each read / write / execute). Full support for the special bits — setuid (4), setgid (2) and the sticky bit (1) — so 4755 ↔ rwsr-xr-x and 1777 ↔ rwxrwxrwt are handled correctly, including the capital S/T forms. Perfect for Dockerfiles and CI scripts, deployment and provisioning tooling, teaching, and any time you need to double-check a chmod value. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 4 endpoints. Distinct from anything that touches real files or networking.

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

## Pricing
- **Free** (Free) — 720 calls/Mo, 2 req/s
- **Starter** ($1/Mo) — 5,700 calls/Mo, 8 req/s
- **Pro** ($19/Mo) — 123,000 calls/Mo, 20 req/s
- **Mega** ($55/Mo) — 635,000 calls/Mo, 50 req/s

## Endpoints

### chmod

#### `GET /v1/describe` — Describe a mode

**Parameters:**
- `mode` (query, required, string) — Octal or symbolic Example: `750`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/chmod-api/v1/describe?mode=750"
```

**Response:**
```json
{
    "data": {
        "human": "Owner: read, write, execute; Group: read, execute; Others: none",
        "octal": "0750",
        "special": {
            "setgid": false,
            "setuid": false,
            "sticky": false
        },
        "symbolic": "rwxr-x---",
        "octal_short": "750",
        "permissions": {
            "group": {
                "read": true,
                "write": false,
                "execute": true
            },
            "owner": {
                "read": true,
                "write": true,
                "execute": true
            },
            "others": {
                "read": false,
                "write": false,
                "execute": false
            }
        }
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:49.217Z",
        "request_id": "d13836b2-4dea-4dea-b875-a499e48524ff"
    },
    "status": "ok",
    "message": "Describe a mode",
    "success": true
}
```

#### `GET /v1/to-octal` — Symbolic to octal

**Parameters:**
- `symbolic` (query, required, string) — e.g. rwxr-xr-x Example: `rwxr-xr-x`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/chmod-api/v1/to-octal?symbolic=rwxr-xr-x"
```

**Response:**
```json
{
    "data": {
        "octal": "0755",
        "symbolic": "rwxr-xr-x",
        "octal_short": "755"
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:49.310Z",
        "request_id": "7e5e7108-4046-48ef-8aff-adcfd58f8ecb"
    },
    "status": "ok",
    "message": "Symbolic to octal",
    "success": true
}
```

#### `GET /v1/to-symbolic` — Octal to symbolic

**Parameters:**
- `octal` (query, required, string) — e.g. 755 or 4755 Example: `4755`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/chmod-api/v1/to-symbolic?octal=4755"
```

**Response:**
```json
{
    "data": {
        "octal": "4755",
        "symbolic": "rwsr-xr-x",
        "octal_short": "4755"
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:49.410Z",
        "request_id": "2bdb615d-e9ba-4e05-a281-04de2e724913"
    },
    "status": "ok",
    "message": "Octal to symbolic",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "name": "chmod API",
        "notes": "A 4-digit octal sets special bits: 4=setuid, 2=setgid, 1=sticky (e.g. 4755 = rwsr-xr-x, 1777 = rwxrwxrwt).",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/to-octal",
                "params": {
                    "symbolic": "e.g. rwxr-xr-x (required)"
                },
                "returns": "the octal mode"
            },
            {
                "path": "/v1/to-symbolic",
                "params": {
                    "octal": "e.g. 755 or 4755 (required)"
                },
                "returns": "the symbolic mode"
            },
            {
                "path": "/v1/describe",
                "params": {
                    "mode": "octal or symbolic (or use octal=/symbolic=)"
                },
                "returns": "octal, symbolic, per-class flags, special bits, plain-English"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        "description": "Unix file-permission calculator — convert between symbolic (rwxr-xr-x) and octal (755) modes, including setuid, setgid and the sticky bit, and explain a mode in plain words. Pure local, no key."
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:49.508Z",
        "request_id": "2feb11d1-f4bb-4a40-9457-0844dcaf5e28"
    },
    "status": "ok",
    "message": "Meta",
    
…(truncated, see openapi.json for full schema)
```


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