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.
Create an account and session. A verification link is emailed — key creation requires a verified email.
Request
| Field | Type | Description | |
|---|---|---|---|
email | string | required | |
password | string (min 8) | required | |
name | string | optional |
Example
curl -X POST https://agw.orcanox.xyz/auth/signup \ -H "Content-Type: application/json" \ -d '{"email":"you@example.com","password":"a-real-password"}'
import requests r = requests.post("https://agw.orcanox.xyz/auth/signup", json={"email":"you@example.com","password":"a-real-password"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/auth/signup", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({"email":"you@example.com","password":"a-real-password"}) }); console.log(r.status, await r.json());
Response
{
"user": {
"id": "<id>",
"email": "a@b.c",
"name": "…",
"emailVerified": false
}
}Errors
| Status | code | Example |
|---|---|---|
| 400 | bad_request | {"code":"bad_request","message":"invalid email"} |
| 409 | bad_request | {"code":"bad_request","message":"email already registered"} |
| 429 | rate_limited | {"code":"rate_limited","message":"rate limit exceeded"} |
Email + password → session cookie (HttpOnly, Secure, SameSite=Lax).
Request
| Field | Type | Description | |
|---|---|---|---|
email | string | required | |
password | string | required |
Example
curl -X POST https://agw.orcanox.xyz/auth/login \ -H "Content-Type: application/json" \ -d '{"email":"you@example.com","password":"a-real-password"}'
import requests r = requests.post("https://agw.orcanox.xyz/auth/login", json={"email":"you@example.com","password":"a-real-password"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/auth/login", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({"email":"you@example.com","password":"a-real-password"}) }); console.log(r.status, await r.json());
Response
{
"user": {
"id": "<id>",
"email": "a@b.c",
"name": "…",
"emailVerified": true
}
}Errors
| Status | code | Example |
|---|---|---|
| 401 | unauthorized | {"code":"unauthorized","message":"invalid credentials"} |
| 429 | rate_limited | {"code":"rate_limited","message":"rate limit exceeded"} |
Destroy the current session.
Example
curl -X POST https://agw.orcanox.xyz/auth/logout \ -H "Cookie: agw_session=…"
import requests r = requests.post("https://agw.orcanox.xyz/auth/logout", cookies={"agw_session": "…"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/auth/logout", { method: "POST", headers: { "Cookie": "agw_session=…" } }); console.log(r.status, await r.json());
Response
{
"ok": true
}Consume an emailed verification token.
Request
| Field | Type | Description | |
|---|---|---|---|
token | string | required |
Example
curl -X POST https://agw.orcanox.xyz/auth/verify-email \ -H "Content-Type: application/json" \ -d '{"token":"agwt_…from-email"}'
import requests r = requests.post("https://agw.orcanox.xyz/auth/verify-email", json={"token":"agwt_…from-email"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/auth/verify-email", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({"token":"agwt_…from-email"}) }); console.log(r.status, await r.json());
Response
{
"ok": true,
"verified": true
}Errors
| Status | code | Example |
|---|---|---|
| 400 | bad_request | {"code":"bad_request","message":"invalid or expired token"} |
Always {"ok":true} — identical for registered and unknown emails. The reset link is emailed, never returned.
Request
| Field | Type | Description | |
|---|---|---|---|
email | string | required |
Example
curl -X POST https://agw.orcanox.xyz/auth/forgot-password \ -H "Content-Type: application/json" \ -d '{"email":"you@example.com"}'
import requests r = requests.post("https://agw.orcanox.xyz/auth/forgot-password", json={"email":"you@example.com"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/auth/forgot-password", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({"email":"you@example.com"}) }); console.log(r.status, await r.json());
Response
{
"ok": true
}Errors
| Status | code | Example |
|---|---|---|
| 429 | rate_limited | {"code":"rate_limited","message":"rate limit exceeded"} |
Consume a reset token and set a new password. All existing sessions are revoked.
Request
| Field | Type | Description | |
|---|---|---|---|
token | string | required | |
password | string (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"}'
import requests r = requests.post("https://agw.orcanox.xyz/auth/reset-password", json={"token":"agwt_…from-email","password":"new-strong-password"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/auth/reset-password", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({"token":"agwt_…from-email","password":"new-strong-password"}) }); console.log(r.status, await r.json());
Response
{
"ok": true
}Errors
| Status | code | Example |
|---|---|---|
| 400 | bad_request | {"code":"bad_request","message":"invalid or expired token"} |
Re-send the verification link to your own email.
Example
curl -X POST https://agw.orcanox.xyz/auth/resend-verification \ -H "Cookie: agw_session=…"
import requests r = requests.post("https://agw.orcanox.xyz/auth/resend-verification", cookies={"agw_session": "…"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/auth/resend-verification", { method: "POST", headers: { "Cookie": "agw_session=…" } }); console.log(r.status, await r.json());
Response
{
"ok": true
}Your account: plan, monthly usage, and subscription state.
Example
curl -X GET https://agw.orcanox.xyz/me \ -H "Cookie: agw_session=…"
import requests r = requests.get("https://agw.orcanox.xyz/me", cookies={"agw_session": "…"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/me", { method: "GET", headers: { "Cookie": "agw_session=…" } }); console.log(r.status, await r.json());
Response
{
"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
| Status | code | Example |
|---|---|---|
| 401 | unauthorized | {"code":"unauthorized","message":"login required"} |
Create an agw_ API key. The raw key is returned once — store it. Requires a verified email.
Request
| Field | Type | Description | |
|---|---|---|---|
name | string | optional | |
scopes | string[] | optional |
Example
curl -X POST https://agw.orcanox.xyz/keys \ -H "Cookie: agw_session=…" \ -H "Content-Type: application/json" \ -d '{}'
import requests r = requests.post("https://agw.orcanox.xyz/keys", cookies={"agw_session": "…"}, json={}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/keys", { method: "POST", headers: { "Cookie": "agw_session=…", "Content-Type": "application/json" }, body: JSON.stringify({}) }); console.log(r.status, await r.json());
Response
{
"key": {
"id": "<id>",
"name": "default",
"keyPrefix": "agw_abcd",
"scopes": [
"read",
"search"
],
"monthlyQuota": 500,
"rawKey": "agw_… (shown once)"
}
}Errors
| Status | code | Example |
|---|---|---|
| 401 | unauthorized | {"code":"unauthorized","message":"login required"} |
| 403 | email_not_verified | {"code":"email_not_verified","message":"verify your email before creating keys"} |
| 403 | forbidden_scope | {"code":"forbidden_scope","message":"scopes outside your plan: memory:read"} |
List your keys with live monthly usage.
Example
curl -X GET https://agw.orcanox.xyz/keys \ -H "Cookie: agw_session=…"
import requests r = requests.get("https://agw.orcanox.xyz/keys", cookies={"agw_session": "…"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/keys", { method: "GET", headers: { "Cookie": "agw_session=…" } }); console.log(r.status, await r.json());
Response
{
"keys": [
{
"id": "<id>",
"name": "default",
"keyPrefix": "agw_abcd",
"scopes": [
"read"
],
"monthlyQuota": 500,
"used": 3
}
]
}Errors
| Status | code | Example |
|---|---|---|
| 401 | unauthorized | {"code":"unauthorized","message":"login required"} |
Disable a key — requests with it return 401 immediately.
Request
| Field | Type | Description | |
|---|---|---|---|
id (path) | string | required |
Example
curl -X DELETE https://agw.orcanox.xyz/keys/<id> \ -H "Cookie: agw_session=…" \ -H "Content-Type: application/json" \ -d '{}'
import requests
r = requests.delete("https://agw.orcanox.xyz/keys/<id>", cookies={"agw_session": "…"}, json={})
print(r.status_code, r.json())const r = await fetch("https://agw.orcanox.xyz/keys/<id>", {
method: "DELETE",
headers: { "Cookie": "agw_session=…", "Content-Type": "application/json" },
body: JSON.stringify({})
});
console.log(r.status, await r.json());
Response
{
"ok": true
}Errors
| Status | code | Example |
|---|---|---|
| 401 | unauthorized | {"code":"unauthorized","message":"login required"} |
| 404 | not_found | {"code":"not_found","message":"key not found"} |
Create a Polar checkout for a paid plan (monthly or yearly).
Request
| Field | Type | Description | |
|---|---|---|---|
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"}'
import requests r = requests.post("https://agw.orcanox.xyz/billing/checkout", cookies={"agw_session": "…"}, json={"plan":"hobby","interval":"monthly"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/billing/checkout", { method: "POST", headers: { "Cookie": "agw_session=…", "Content-Type": "application/json" }, body: JSON.stringify({"plan":"hobby","interval":"monthly"}) }); console.log(r.status, await r.json());
Response
{
"checkoutUrl": "https://polar.sh/checkout/…"
}Errors
| Status | code | Example |
|---|---|---|
| 401 | unauthorized | {"code":"unauthorized","message":"login required"} |
| 400 | bad_request | {"code":"bad_request","message":"unknown plan"} |
| 503 | internal | {"code":"internal","message":"billing_not_configured"} |
Polar webhook receiver — signature-verified. Not for client use.
Request
| Field | Type | Description | |
|---|---|---|---|
(Polar event payload) | object | required | The Polar event envelope; signature headers required. |
Example
curl -X POST https://agw.orcanox.xyz/billing/webhook \ -H "Content-Type: application/json" \ -d '{}'
import requests
r = requests.post("https://agw.orcanox.xyz/billing/webhook", json={})
print(r.status_code, r.json())const r = await fetch("https://agw.orcanox.xyz/billing/webhook", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({}) }); console.log(r.status, await r.json());
Response
{
"ok": true
}Errors
| Status | code | Example |
|---|---|---|
| 400 | bad_request | {"code":"bad_request","message":"invalid webhook signature"} |