# Collatz Sequence API
> The Collatz conjecture (the "3n+1" or hailstone problem) as an API, computed locally and deterministically. Give it any positive integer and the sequence endpoint returns the full hailstone path — at each step an even number is halved and an odd number is tripled and incremented (3n+1) — together with the total stopping time (the number of steps to reach 1) and the peak value the sequence climbs to. Starting from 6 the path is 6, 3, 10, 5, 16, 8, 4, 2, 1 — eight steps, peaking at 16; the notoriously long start 27 takes 111 steps and soars to a peak of 9232 before collapsing. The steps endpoint returns just the stopping time and peak altitude without the whole path, for fast bulk scans of where the big climbs and long tails are. All arithmetic runs in arbitrary-precision integers so the peak stays exact even when a small starting number balloons into the millions, and a safety cap keeps every request bounded. Starting numbers up to one hundred trillion are accepted. Everything is computed locally and deterministically, so it is instant and private. Ideal for maths-education, number-theory, recreational-mathematics and puzzle app developers, sequence-and-hailstone visualisers, and teaching material on the most famous unsolved problem in arithmetic. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 2 compute endpoints. This is the Collatz/3n+1 sequence specifically; for prime factorisation or GCD use a number-theory API.

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

## Pricing
- **Free** (Free) — 4,350 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 43,500 calls/Mo, 6 req/s
- **Pro** ($11/Mo) — 224,000 calls/Mo, 15 req/s
- **Mega** ($36/Mo) — 1,240,000 calls/Mo, 40 req/s

## Endpoints

### Collatz

#### `GET /v1/sequence` — Full Collatz sequence

**Parameters:**
- `number` (query, required, string) — Positive integer start (<= 1e14) Example: `27`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/collatz-api/v1/sequence?number=27"
```

**Response:**
```json
{
    "data": {
        "note": "Collatz sequence: even → n/2, odd → 3n+1, until 1. From 6 it is 6,3,10,5,16,8,4,2,1 — 8 steps, peak 16.",
        "steps": 111,
        "inputs": {
            "number": "27"
        },
        "sequence": [
            "27",
            "82",
            "41",
            "124",
            "62",
            "31",
            "94",
            "47",
            "142",
            "71",
            "214",
            "107",
            "322",
            "161",
            "484",
            "242",
            "121",
            "364",
            "182",
            "91",
            "274",
            "137",
            "412",
            "206",
            "103",
            "310",
            "155",
            "466",
            "233",
            "700",
            "350",
            "175",
            "526",
            "263",
            "790",
            "395",
            "1186",
            "593",
            "1780",
            "890",
            "445",
            "1336",
            "668",
            "334",
            "167",
            "502",
            "251",
            "754",
            "377",
            "1132",
            "566",
            "283",
            "850",
            "425",
            "1276",
            "638",
            "319",
            "958",
            "479",
            "1438",
            "719",
            "2158",
            "1079",
            "3238",
            "1619",
            "4858
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/steps` — Stopping time and peak

**Parameters:**
- `number` (query, required, string) — Positive integer start (<= 1e14) Example: `27`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/collatz-api/v1/steps?number=27"
```

**Response:**
```json
{
    "data": {
        "note": "Total stopping time (steps to reach 1) and the highest value reached. Starting at 27 takes 111 steps and peaks at 9232.",
        "steps": 111,
        "inputs": {
            "number": "27"
        },
        "max_value": "9232"
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:10.554Z",
        "request_id": "47cba793-29ad-4cbf-9a55-e470196e2d0f"
    },
    "status": "ok",
    "message": "Stopping time",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Positive integers up to 100000000000000. BigInt arithmetic keeps the peak exact. The conjecture (unproven) is that every start eventually reaches 1.",
        "service": "collatz-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/steps": "Stopping time and peak altitude without the full path.",
            "GET /v1/sequence": "Full Collatz sequence, step count and peak from a starting number."
        },
        "description": "Collatz conjecture (3n+1 / hailstone) sequences, stopping time and peak value."
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:10.641Z",
        "request_id": "5a54b6d5-d2ff-4bd8-a7e8-ba6facc84121"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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