/ docs

REST API

HTTP API for the Hypex worker — auth, billing, sync, Discord, and IDE auto-update endpoints.

Base URL: https://hypex.pages.dev. All endpoints return JSON. Authenticated routes require a Bearer token issued by the worker after sign-in (Authorization: Bearer <token>). Tokens are device-scoped — revoke them from /account.

On this page

Quick start
Authentication
Rate limits
Errors
Public endpoints
Account
Billing
Discord
Cloud sync
OAuth flow
Auto-update

Quick start

Three flavors — same endpoint, three SDKs:

curl

curl -X POST https://hypex.pages.dev/api/billing/checkout \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan":"pro"}'

JavaScript (fetch)

const res = await fetch('https://hypex.pages.dev/api/account/me', {
  headers: { 'Authorization': `Bearer ${token}` },
});
const data = await res.json();
console.log(data);

Python (requests)

import requests

r = requests.get(
    'https://hypex.pages.dev/api/account/me',
    headers={'Authorization': f'Bearer {token}'},
)
print(r.json())

Authentication

All authenticated endpoints expect a Bearer token in the Authorization header. Tokens are obtained via the IDE sign-in flow (OAuth or magic link). They look like session:<opaque> and are stored locally encrypted by the extension.

Missing or invalid tokens return 401 Unauthorized. Tokens that don't match the required plan return 403 Forbidden.

Rate limits

Limits are enforced per IP or per user, sliding window 60s:

Route prefix	Limit	Scope
`/api/auth/*`	5 / min	per IP
`/api/billing/*`	10 / min	per user
`/api/sync/push`	30 / min	per user
`/api/discord/*`	60 / min	per user

Exceeded limits return 429 Too Many Requests with a Retry-After header.

Errors

Standard JSON error shape:

{
  "error": "string_code",
  "message": "Human-readable explanation"
}

Code	Meaning
400	Bad request — invalid body or query
401	Missing / invalid Bearer token
402	Insufficient balance (billing)
403	Plan does not include this feature
404	Resource not found
429	Rate limit hit
5xx	Worker / upstream error

Public endpoints

No auth required. Safe to call from a browser.

GET /api/v2/health

Liveness probe. Returns build SHA and uptime.

curl https://hypex.pages.dev/api/v2/health

{
  "ok": true,
  "version": "v2",
  "commit": "abcd1234",
  "ts": 1714000000
}

GET /api/billing/v2/catalog

The active pricing catalog (plans, prices, features). Used by the extension to render the upgrade UI.

curl https://hypex.pages.dev/api/billing/v2/catalog

{
  "plans": [
    { "id": "pro",    "price_cents": 2000, "interval": "month", "features": [...] },
    { "id": "pro_plus","price_cents": 4000, "interval": "month", "features": [...] },
    { "id": "team",   "price_cents": 3500, "interval": "month", "features": [...] },
    { "id": "lifetime","price_cents": 39900,"interval": "once", "features": [...] }
  ],
  "topups": [ { "id": "topup_10", "price_cents": 1000, "credits_cents": 1000 } ]
}

GET /api/counter/founding

Number of Founding member spots remaining (out of 1000).

curl https://hypex.pages.dev/api/counter/founding

{ "remaining": 873, "total": 1000 }

GET /api/v2/status/public

Public status page payload — degraded components, ongoing incidents.

curl https://hypex.pages.dev/api/v2/status/public

{
  "status": "ok",
  "components": {
    "worker": "ok",
    "anthropic_proxy": "ok",
    "stripe": "ok",
    "discord": "ok"
  },
  "incidents": []
}

Account

Bearer token required.

GET /api/account/me

Current user profile, plan, balance.

curl https://hypex.pages.dev/api/account/me \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "id": "usr_...",
  "email": "you@example.com",
  "plan": "pro",
  "balance_cents": 1234,
  "topup_balance_cents": 0,
  "overage_enabled": false,
  "founding": false,
  "created_at": 1700000000
}

GET /api/account/orders

Order history (subscription renewals, top-ups, lifetime purchase).

curl https://hypex.pages.dev/api/account/orders \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "orders": [
    { "id":"ord_...", "kind":"subscription", "amount_cents":2000, "status":"paid", "ts":1713900000 },
    { "id":"ord_...", "kind":"topup",        "amount_cents":1000, "status":"paid", "ts":1713800000 }
  ]
}

GET /api/account/sessions

List active device sessions for the current user.

curl https://hypex.pages.dev/api/account/sessions \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "sessions": [
    { "id":"sess_...", "device":"win32-x64", "ip":"1.2.3.4", "last_seen":1714000000 }
  ]
}

Billing

POST /api/billing/checkout

Start a Stripe Checkout session for a plan or top-up.

Body:

{
  "plan": "pro" | "pro_plus" | "team" | "lifetime" | "topup_10",
  "founding": false   // optional, applies Founding pricing if eligible
}

curl -X POST https://hypex.pages.dev/api/billing/checkout \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan":"pro"}'

{ "url": "https://checkout.stripe.com/c/pay/cs_..." }

POST /api/billing/portal

Returns a Stripe Customer Portal URL to manage subscription / payment method.

curl -X POST https://hypex.pages.dev/api/billing/portal \
  -H "Authorization: Bearer YOUR_TOKEN"

{ "url": "https://billing.stripe.com/p/session/..." }

Discord

GET /api/discord/status

Whether the Hypex account is linked to a Discord account, and which roles are synced.

curl https://hypex.pages.dev/api/discord/status \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "linked": true,
  "discord_id": "1234...",
  "username": "alex",
  "roles": ["pro", "founding"]
}

Cloud sync

Bearer token required, plan must be Pro+ or higher. Operations are CRDT ops over chat history, profiles, and skills.

POST /api/sync/push

Push a batch of ops from the local device.

Body:

{
  "device_id": "uuid",
  "ops": [
    { "id":"op_...", "kind":"chat.append", "ts":1714000000, "payload": {...} }
  ]
}

curl -X POST https://hypex.pages.dev/api/sync/push \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d @ops.json

{ "accepted": 4, "rejected": 0, "cursor": "1714000000.4" }

GET /api/sync/pull?since=<cursor>

Fetch ops produced since a cursor.

curl "https://hypex.pages.dev/api/sync/pull?since=1713900000.0" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "ops": [ ... ],
  "cursor": "1714000000.7",
  "has_more": false
}

GET /api/sync/status

Devices currently syncing + quota usage.

curl https://hypex.pages.dev/api/sync/status \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "devices": [
    { "id":"dev_...", "name":"laptop", "last_push":1714000000 }
  ],
  "quota": { "used_bytes": 123456, "limit_bytes": 104857600 }
}

OAuth flow (Discord)

Used by the extension to link a Discord account. Two endpoints, server-to-server callback.

GET /api/discord/oauth/start?hypex_token=<token>

Redirects (302) to the Discord authorization URL. The hypex_token query param identifies which Hypex account the future Discord identity should bind to; it is HMAC-signed into the OAuth state.

open "https://hypex.pages.dev/api/discord/oauth/start?hypex_token=YOUR_TOKEN"

GET /api/discord/oauth/callback?code=&state=

Discord redirects the browser here with a one-shot code and the signed state. The worker exchanges the code, verifies state, links the accounts, and renders a success page. Not meant to be called manually.

Auto-update (IDE)

GET /api/update/{platform}/{quality}/{commit}

Used by the Hypex IDE on launch. Returns either 204 No Content (you're current) or 200 with an update manifest.

platform — win32-x64, darwin-x64, darwin-arm64, linux-x64
quality — stable or insider
commit — current build commit SHA

curl "https://hypex.pages.dev/api/update/win32-x64/stable/abcd1234"

{
  "url": "https://...hypex-update.zip",
  "name": "v1.0-beta.37",
  "version": "deadbeef",
  "productVersion": "1.0.37",
  "hash": "sha256:...",
  "timestamp": 1714000000,
  "sha256hash": "..."
}

Spotted an inconsistency or want an endpoint added? Open an issue on GitHub.