Documentation

Authentication

API-key endpoints take `Authorization: Bearer agw_…`. Keys are created in the dashboard and carry the scopes of your plan — Free has read+search, Hobby/Pro add memory:read and memory:write.

Session endpoints (browser accounts) use the agw_session cookie set by login/signup. They are listed here for completeness — service integrations use API keys.

POST /auth/signup public #

Create an account and session. A verification link is emailed — key creation requires a verified email.

Request

FieldTypeDescription
emailstringrequired
passwordstring (min 8)required
namestringoptional

Example

curl -X POST https://agw.orcanox.xyz/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"a-real-password"}'

Response

json
{
  "user": {
    "id": "<id>",
    "email": "a@b.c",
    "name": "…",
    "emailVerified": false
  }
}

Errors

StatuscodeExample
400bad_request{"code":"bad_request","message":"invalid email"}
409bad_request{"code":"bad_request","message":"email already registered"}
429rate_limited{"code":"rate_limited","message":"rate limit exceeded"}
POST /auth/login public #

Email + password → session cookie (HttpOnly, Secure, SameSite=Lax).

Request

FieldTypeDescription
emailstringrequired
passwordstringrequired

Example

curl -X POST https://agw.orcanox.xyz/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"a-real-password"}'

Response

json
{
  "user": {
    "id": "<id>",
    "email": "a@b.c",
    "name": "…",
    "emailVerified": true
  }
}

Errors

StatuscodeExample
401unauthorized{"code":"unauthorized","message":"invalid credentials"}
429rate_limited{"code":"rate_limited","message":"rate limit exceeded"}
POST /auth/logout session #

Destroy the current session.

Example

curl -X POST https://agw.orcanox.xyz/auth/logout \
  -H "Cookie: agw_session=…"

Response

json
{
  "ok": true
}
POST /auth/verify-email public #

Consume an emailed verification token.

Request

FieldTypeDescription
tokenstringrequired

Example

curl -X POST https://agw.orcanox.xyz/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{"token":"agwt_…from-email"}'

Response

json
{
  "ok": true,
  "verified": true
}

Errors

StatuscodeExample
400bad_request{"code":"bad_request","message":"invalid or expired token"}
POST /auth/forgot-password public #

Always {"ok":true} — identical for registered and unknown emails. The reset link is emailed, never returned.

Request

FieldTypeDescription
emailstringrequired

Example

curl -X POST https://agw.orcanox.xyz/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

Response

json
{
  "ok": true
}

Errors

StatuscodeExample
429rate_limited{"code":"rate_limited","message":"rate limit exceeded"}
POST /auth/reset-password public #

Consume a reset token and set a new password. All existing sessions are revoked.

Request

FieldTypeDescription
tokenstringrequired
passwordstring (min 8)required

Example

curl -X POST https://agw.orcanox.xyz/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{"token":"agwt_…from-email","password":"new-strong-password"}'

Response

json
{
  "ok": true
}

Errors

StatuscodeExample
400bad_request{"code":"bad_request","message":"invalid or expired token"}
POST /auth/resend-verification session #

Re-send the verification link to your own email.

Example

curl -X POST https://agw.orcanox.xyz/auth/resend-verification \
  -H "Cookie: agw_session=…"

Response

json
{
  "ok": true
}
GET /me session #

Your account: plan, monthly usage, and subscription state.

Example

curl -X GET https://agw.orcanox.xyz/me \
  -H "Cookie: agw_session=…"

Response

json
{
  "user": {
    "id": "<id>",
    "email": "a@b.c",
    "name": "…",
    "emailVerified": true
  },
  "plan": {
    "slug": "free",
    "name": "Free",
    "monthlyQuota": 500,
    "scopes": [
      "read",
      "search"
    ],
    "concurrency": null
  },
  "usage": {
    "month": "2026-10",
    "used": 12,
    "keys": 1
  },
  "subscription": {
    "status": "active",
    "interval": "monthly",
    "currentPeriodEnd": "2026-11-01T00: 00: 00.000Z",
    "expiresAt": null
  }
}

Errors

StatuscodeExample
401unauthorized{"code":"unauthorized","message":"login required"}
POST /keys session #

Create an agw_ API key. The raw key is returned once — store it. Requires a verified email.

Request

FieldTypeDescription
namestringoptional
scopesstring[]optional

Example

curl -X POST https://agw.orcanox.xyz/keys \
  -H "Cookie: agw_session=…" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

json
{
  "key": {
    "id": "<id>",
    "name": "default",
    "keyPrefix": "agw_abcd",
    "scopes": [
      "read",
      "search"
    ],
    "monthlyQuota": 500,
    "rawKey": "agw_… (shown once)"
  }
}

Errors

StatuscodeExample
401unauthorized{"code":"unauthorized","message":"login required"}
403email_not_verified{"code":"email_not_verified","message":"verify your email before creating keys"}
403forbidden_scope{"code":"forbidden_scope","message":"scopes outside your plan: memory:read"}
GET /keys session #

List your keys with live monthly usage.

Example

curl -X GET https://agw.orcanox.xyz/keys \
  -H "Cookie: agw_session=…"

Response

json
{
  "keys": [
    {
      "id": "<id>",
      "name": "default",
      "keyPrefix": "agw_abcd",
      "scopes": [
        "read"
      ],
      "monthlyQuota": 500,
      "used": 3
    }
  ]
}

Errors

StatuscodeExample
401unauthorized{"code":"unauthorized","message":"login required"}
DELETE /keys/:id session #

Disable a key — requests with it return 401 immediately.

Request

FieldTypeDescription
id (path)stringrequired

Example

curl -X DELETE https://agw.orcanox.xyz/keys/<id> \
  -H "Cookie: agw_session=…" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

json
{
  "ok": true
}

Errors

StatuscodeExample
401unauthorized{"code":"unauthorized","message":"login required"}
404not_found{"code":"not_found","message":"key not found"}
POST /billing/checkout session #

Create a Polar checkout for a paid plan (monthly or yearly).

Request

FieldTypeDescription
plan'hobby' | 'pro'required
interval'monthly' | 'yearly'optional

Example

curl -X POST https://agw.orcanox.xyz/billing/checkout \
  -H "Cookie: agw_session=…" \
  -H "Content-Type: application/json" \
  -d '{"plan":"hobby","interval":"monthly"}'

Response

json
{
  "checkoutUrl": "https://polar.sh/checkout/…"
}

Errors

StatuscodeExample
401unauthorized{"code":"unauthorized","message":"login required"}
400bad_request{"code":"bad_request","message":"unknown plan"}
503internal{"code":"internal","message":"billing_not_configured"}
POST /billing/webhook public #

Polar webhook receiver — signature-verified. Not for client use.

Request

FieldTypeDescription
(Polar event payload)objectrequiredThe Polar event envelope; signature headers required.

Example

curl -X POST https://agw.orcanox.xyz/billing/webhook \
  -H "Content-Type: application/json" \
  -d '{}'

Response

json
{
  "ok": true
}

Errors

StatuscodeExample
400bad_request{"code":"bad_request","message":"invalid webhook signature"}