# Semver API
> A Semantic Versioning (SemVer 2.0.0) toolkit as an API. Parse a version string into its major, minor, patch, prerelease and build parts; compare two versions; test whether a version satisfies an npm-style range (^1.2.3, ~1.4, >=2 <3, 1.x); increment a version to the next major, minor, patch or prerelease; and filter a list of versions by a range to find which match and the highest and lowest satisfying. Powered by the canonical node-semver. Perfect for dependency and release tooling, CI gates, update checkers, compatibility rules and package dashboards. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 6 endpoints. Distinct from package-registry lookups and vulnerability databases.

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

## Pricing
- **Free** (Free) — 620 calls/Mo, 2 req/s
- **Starter** ($0/Mo) — 4,700 calls/Mo, 8 req/s
- **Pro** ($18/Mo) — 118,000 calls/Mo, 20 req/s
- **Mega** ($54/Mo) — 610,000 calls/Mo, 50 req/s

## Endpoints

### Semver

#### `GET /v1/compare` — Compare two versions

**Parameters:**
- `a` (query, required, string) — First version Example: `1.2.3`
- `b` (query, required, string) — Second version Example: `1.10.0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/semver-api/v1/compare?a=1.2.3&b=1.10.0"
```

**Response:**
```json
{
    "data": {
        "a": "1.2.3",
        "b": "1.10.0",
        "result": -1,
        "relation": "<"
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:47.044Z",
        "request_id": "db0b6cd8-7a71-479b-88cb-d7f82c42e013"
    },
    "status": "ok",
    "message": "Compare two versions",
    "success": true
}
```

#### `GET /v1/inc` — Increment a version

**Parameters:**
- `version` (query, required, string) — Version Example: `1.2.3`
- `release` (query, optional, string) — major|minor|patch|premajor|preminor|prepatch|prerelease Example: `minor`
- `identifier` (query, optional, string) — Prerelease id (e.g. rc)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/semver-api/v1/inc?version=1.2.3&release=minor"
```

**Response:**
```json
{
    "data": {
        "next": "1.3.0",
        "release": "minor",
        "version": "1.2.3"
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:47.154Z",
        "request_id": "d45cc7d3-ed65-4976-b1eb-e8be6dd899ee"
    },
    "status": "ok",
    "message": "Increment a version",
    "success": true
}
```

#### `GET /v1/parse` — Parse a version

**Parameters:**
- `version` (query, required, string) — Version string Example: `1.2.3-beta.1+build5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/semver-api/v1/parse?version=1.2.3-beta.1%2Bbuild5"
```

**Response:**
```json
{
    "data": {
        "build": [
            "build5"
        ],
        "major": 1,
        "minor": 2,
        "patch": 3,
        "version": "1.2.3-beta.1",
        "prerelease": [
            "beta",
            1
        ],
        "is_prerelease": true
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:47.228Z",
        "request_id": "55888825-e000-45e5-9463-3088085aceb2"
    },
    "status": "ok",
    "message": "Parse a version",
    "success": true
}
```

#### `GET /v1/range` — Filter versions by range

**Parameters:**
- `range` (query, required, string) — Range Example: `^1.0.0`
- `versions` (query, required, string) — Comma-separated versions Example: `1.0.0,1.2.0,2.0.0,1.5.3`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/semver-api/v1/range?range=%5E1.0.0&versions=1.0.0%2C1.2.0%2C2.0.0%2C1.5.3"
```

**Response:**
```json
{
    "data": {
        "range": "^1.0.0",
        "satisfying": [
            "1.0.0",
            "1.2.0",
            "1.5.3"
        ],
        "max_satisfying": "1.5.3",
        "min_satisfying": "1.0.0",
        "normalized_range": ">=1.0.0 <2.0.0-0"
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:47.300Z",
        "request_id": "51af3699-eb92-43c2-8b76-7b7193ce7f17"
    },
    "status": "ok",
    "message": "Filter versions by range",
    "success": true
}
```

#### `GET /v1/satisfies` — Version satisfies range

**Parameters:**
- `version` (query, required, string) — Version Example: `1.2.3`
- `range` (query, required, string) — Range Example: `^1.0.0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/semver-api/v1/satisfies?version=1.2.3&range=%5E1.0.0"
```

**Response:**
```json
{
    "data": {
        "range": "^1.0.0",
        "version": "1.2.3",
        "satisfies": true
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:47.394Z",
        "request_id": "b99c93c1-f18c-401d-bbf0-df69302f9f6f"
    },
    "status": "ok",
    "message": "Version satisfies range",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "name": "Semver API",
        "notes": "Implements the SemVer 2.0.0 spec and npm-style ranges. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/parse",
                "params": {
                    "version": "e.g. 1.2.3-beta.1 (required)"
                },
                "returns": "major, minor, patch, prerelease, build"
            },
            {
                "path": "/v1/compare",
                "params": {
                    "a": "required",
                    "b": "required"
                },
                "returns": "-1/0/1 and the relation (< = >)"
            },
            {
                "path": "/v1/satisfies",
                "params": {
                    "range": "e.g. ^1.0.0 (required)",
                    "version": "required"
                },
                "returns": "whether the version is in range"
            },
            {
                "path": "/v1/inc",
                "params": {
                    "release": "major|minor|patch|pre… (default patch)",
                    "version": "required",
                    "identifier": "for prereleases"
                },
                "returns": "the next version"
            },
            {
                "path": "/v1/range",
                "params": {
                    "range": "required",
                    "versions": "comma-separated list (required)"
                },
             
…(truncated, see openapi.json for full schema)
```


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