{
  "schema": "948-contract-1",
  "examples": "Contract examples, not evidence of upstream success",
  "routes": [
    {
      "method": "POST",
      "path": "/api/auth/login",
      "auth": "None",
      "request": {
        "username": "Platform username; 3-32 letters/digits/underscore, starts with a letter",
        "password": "Platform password, 8-64 characters",
        "machineCode": "Client-generated persistent identifier; first successful login binds automatically; not shown in UI"
      },
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "token": "TOKEN",
          "nickname": "See response field: value depends on request and actual server result"
        }
      }
    },
    {
      "method": "POST",
      "path": "/api/auth/refresh",
      "auth": "Platform Bearer token",
      "request": {},
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "token": "NEW_TOKEN"
        }
      }
    },
    {
      "method": "POST",
      "path": "/api/auth/logout",
      "auth": "Platform Bearer token",
      "request": {},
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "revokedAllTokens": true
        }
      }
    },
    {
      "method": "GET",
      "path": "/api/account/me",
      "auth": "Platform Bearer token",
      "request": {},
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "username": "See response field: value depends on request and actual server result",
          "nickname": "See response field: value depends on request and actual server result",
          "expires_at": "See response field: value depends on request and actual server result",
          "rpm": 60,
          "daily_quota": 10000,
          "usedToday": 1,
          "quotaTimezone": "UTC"
        }
      }
    },
    {
      "method": "GET",
      "path": "/api/account/calls",
      "auth": "Platform Bearer token",
      "request": {},
      "response": {
        "code": 200,
        "msg": "success",
        "data": [
          {
            "id": "See response field: value depends on request and actual server result",
            "path": "See response field: value depends on request and actual server result",
            "status": 200,
            "code": 200,
            "duration_ms": 20,
            "created_at": "See response field: value depends on request and actual server result"
          }
        ]
      }
    },
    {
      "method": "POST",
      "path": "/api/account/password",
      "auth": "Platform Bearer token",
      "request": {
        "oldPassword": "Current password",
        "newPassword": "New password, 8-64 characters"
      },
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "reloginRequired": true
        }
      }
    },
    {
      "method": "POST",
      "path": "/api/device/create",
      "auth": "Platform Bearer token",
      "request": {
        "model": "Optional iPhone19,2 or iPhone19,7",
        "phone": "Phone number; required for SMS, optional for create",
        "zone": "Country calling code string, e.g. 1 or 86"
      },
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "uniqueId": "See response field: value depends on request and actual server result",
          "phase": "CREATED"
        }
      }
    },
    {
      "method": "GET",
      "path": "/api/device/list",
      "auth": "Platform Bearer token",
      "request": {},
      "response": {
        "code": 200,
        "msg": "success",
        "data": [
          {
            "unique_id": "See response field: value depends on request and actual server result",
            "model": "See response field: value depends on request and actual server result",
            "phone": "See response field: value depends on request and actual server result",
            "zone": "See response field: value depends on request and actual server result",
            "proxy": "See response field: value depends on request and actual server result",
            "phase": "See response field: value depends on request and actual server result",
            "created_at": "See response field: value depends on request and actual server result"
          }
        ]
      }
    },
    {
      "method": "GET",
      "path": "/api/device/by-phone",
      "auth": "Platform Bearer token",
      "request": {
        "phone": "Phone number; required for SMS, optional for create"
      },
      "response": {
        "code": 200,
        "msg": "success",
        "data": [
          {
            "unique_id": "See response field: value depends on request and actual server result",
            "model": "See response field: value depends on request and actual server result",
            "phone": "See response field: value depends on request and actual server result",
            "zone": "See response field: value depends on request and actual server result",
            "proxy": "See response field: value depends on request and actual server result",
            "phase": "See response field: value depends on request and actual server result",
            "created_at": "See response field: value depends on request and actual server result"
          }
        ]
      }
    },
    {
      "method": "POST",
      "path": "/api/device/edit",
      "auth": "Platform Bearer token",
      "request": {
        "uniqueId": "Required device ID owned by this account",
        "proxy": "socks5[h]://[user:pass@]host:port; empty clears"
      },
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "uniqueId": "See response field: value depends on request and actual server result",
          "hasProxy": true
        }
      }
    },
    {
      "method": "POST",
      "path": "/api/device/register",
      "auth": "Platform Bearer token",
      "request": {
        "uniqueId": "Required device ID owned by this account",
        "proxy": "socks5[h]://[user:pass@]host:port; empty clears"
      },
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "uniqueId": "See response field: value depends on request and actual server result",
          "phase": "See response field: value depends on request and actual server result",
          "registrationSteps": "See response field: value depends on request and actual server result",
          "deviceId": "See response field: value depends on request and actual server result",
          "userId": "See response field: value depends on request and actual server result",
          "sid": "See response field: value depends on request and actual server result"
        }
      }
    },
    {
      "method": "POST",
      "path": "/api/device/sign",
      "auth": "Platform Bearer token",
      "request": {
        "uniqueId": "Required device ID owned by this account",
        "method": "GET or POST",
        "path": "Required /api/ path with encoded query",
        "bizParams": {
          "host": "Required allowlisted HTTPS host",
          "body": "Optional already encoded string, not a JSON object",
          "contentType": "Optional content type",
          "extra": "Additional string header fields"
        }
      },
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "url": "target URL",
          "headers": "sensitive signed headers",
          "body": "encoded string",
          "proxy": "sensitive proxy URL",
          "serverSent": false
        }
      }
    },
    {
      "method": "POST",
      "path": "/api/device/send",
      "auth": "Platform Bearer token",
      "request": {
        "uniqueId": "Required device ID owned by this account",
        "method": "GET or POST",
        "path": "Required /api/ path with encoded query",
        "bizParams": {
          "host": "Required allowlisted HTTPS host",
          "body": "Optional already encoded string, not a JSON object",
          "contentType": "Optional content type",
          "extra": "Additional string header fields"
        }
      },
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "httpCode": 200,
          "body": "See response field: value depends on request and actual server result",
          "serverSent": true
        }
      }
    },
    {
      "method": "POST",
      "path": "/api/device/login/code/send",
      "auth": "Platform Bearer token",
      "request": {
        "uniqueId": "Required device ID owned by this account",
        "phone": "Phone number; required for SMS, optional for create",
        "zone": "Country calling code string, e.g. 1 or 86",
        "code": "SMS code, required for login/code",
        "type": "login or register"
      },
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "success": true,
          "phase": "See response field: value depends on request and actual server result",
          "response": "See response field: value depends on request and actual server result"
        }
      }
    },
    {
      "method": "POST",
      "path": "/api/device/login/vfc-code",
      "auth": "Platform Bearer token",
      "request": {
        "uniqueId": "Required device ID owned by this account",
        "phone": "Phone number; required for SMS, optional for create",
        "zone": "Country calling code string, e.g. 1 or 86",
        "code": "SMS code, required for login/code",
        "type": "login or register"
      },
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "success": true,
          "phase": "See response field: value depends on request and actual server result",
          "response": "See response field: value depends on request and actual server result"
        }
      }
    },
    {
      "method": "POST",
      "path": "/api/device/login/code",
      "auth": "Platform Bearer token",
      "request": {
        "uniqueId": "Required device ID owned by this account",
        "phone": "Phone number; required for SMS, optional for create",
        "zone": "Country calling code string, e.g. 1 or 86",
        "code": "SMS code, required for login/code",
        "type": "login or register"
      },
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "success": true,
          "phase": "See response field: value depends on request and actual server result",
          "response": "See response field: value depends on request and actual server result"
        }
      }
    },
    {
      "method": "POST",
      "path": "/api/device/logout",
      "auth": "Platform Bearer token",
      "request": {
        "uniqueId": "Required device ID owned by this account"
      },
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "uniqueId": "device ID",
          "phase": "LOGOUT"
        }
      }
    },
    {
      "method": "POST",
      "path": "/api/device/delete",
      "auth": "Platform Bearer token",
      "request": {
        "uniqueId": "Required device ID owned by this account"
      },
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "uniqueId": "device ID",
          "deleted": true
        }
      }
    },
    {
      "method": "POST",
      "path": "/api/device/login/password",
      "auth": "Platform Bearer token",
      "request": {},
      "response": {
        "code": 501,
        "msg": "Not implemented",
        "data": null
      }
    },
    {
      "method": "POST",
      "path": "/api/device/login/quick",
      "auth": "Platform Bearer token",
      "request": {},
      "response": {
        "code": 501,
        "msg": "Not implemented",
        "data": null
      }
    },
    {
      "method": "POST",
      "path": "/public/apply/info",
      "auth": "None; B domain",
      "request": {},
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "serverUrl": "https://a.ttjian.com",
          "minDays": 1,
          "maxDays": 3
        }
      }
    },
    {
      "method": "POST",
      "path": "/public/captcha",
      "auth": "None; B domain",
      "request": {},
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "captchaId": "See response field: value depends on request and actual server result",
          "image": "See response field: value depends on request and actual server result"
        }
      }
    },
    {
      "method": "POST",
      "path": "/public/apply",
      "auth": "None; B domain",
      "request": {
        "username": "Platform username; 3-32 letters/digits/underscore, starts with a letter",
        "password": "Platform password, 8-64 characters",
        "nickname": "1-32 characters",
        "days": "Integer 1, 2 or 3",
        "captchaId": "Single-use captcha ID, expires in 180 seconds",
        "captchaCode": "Image characters"
      },
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "status": "pending"
        }
      }
    },
    {
      "method": "POST",
      "path": "/public/apply/status",
      "auth": "Application username/password; B domain",
      "request": {
        "username": "Platform username; 3-32 letters/digits/underscore, starts with a letter",
        "password": "Platform password, 8-64 characters"
      },
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "status": "pending/approved/rejected",
          "reason": "See response field: value depends on request and actual server result",
          "expiresAt": "See response field: value depends on request and actual server result",
          "enabled": true
        }
      }
    },
    {
      "method": "POST",
      "path": "/admin/session",
      "auth": "Admin Bearer or session",
      "request": {},
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "expiresIn": 3600
        }
      }
    },
    {
      "method": "POST",
      "path": "/admin/session/logout",
      "auth": "Admin Bearer or session",
      "request": {},
      "response": {
        "code": 200,
        "msg": "success",
        "data": null
      }
    },
    {
      "method": "GET",
      "path": "/admin/applications",
      "auth": "Admin Bearer or session",
      "request": {},
      "response": {
        "code": 200,
        "msg": "success",
        "data": [
          {
            "username": "See response field: value depends on request and actual server result",
            "nickname": "See response field: value depends on request and actual server result",
            "days": 1,
            "status": "pending",
            "machine_code": "See response field: value depends on request and actual server result",
            "reason": "See response field: value depends on request and actual server result"
          }
        ]
      }
    },
    {
      "method": "POST",
      "path": "/admin/applications/decision",
      "auth": "Admin Bearer or session",
      "request": {
        "username": "Platform username; 3-32 letters/digits/underscore, starts with a letter",
        "approve": "Boolean",
        "reason": "Optional approval note/rejection reason, max 256 characters"
      },
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "username": "See response field: value depends on request and actual server result",
          "status": "approved/rejected",
          "expiresAt": "See response field: value depends on request and actual server result"
        }
      }
    },
    {
      "method": "GET",
      "path": "/admin/users",
      "auth": "Admin Bearer or session",
      "request": {
        "q": "Optional GET username search, max 64 characters",
        "page": "Optional GET positive integer, default 1"
      },
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "items": "See response field: value depends on request and actual server result",
          "total": 1,
          "page": 1,
          "pageSize": 50
        }
      }
    },
    {
      "method": "POST",
      "path": "/admin/users/edit",
      "auth": "Admin Bearer or session",
      "request": {
        "username": "Platform username; 3-32 letters/digits/underscore, starts with a letter",
        "action": "extend/enabled/resetBinding/password/rpm/dailyQuota/revoke",
        "value": "Action-specific value; integers 1-100000, password 8-64, machineCode 1-128"
      },
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "username": "See response field: value depends on request and actual server result",
          "action": "See response field: value depends on request and actual server result"
        }
      }
    },
    {
      "method": "GET",
      "path": "/admin/metrics",
      "auth": "Admin Bearer or session",
      "request": {},
      "response": {
        "code": 200,
        "msg": "success",
        "data": {
          "calls": 0,
          "failures": 0,
          "avgMs": 0,
          "users": 1,
          "devices": 0,
          "events": "See response field: value depends on request and actual server result"
        }
      }
    },
    {
      "method": "POST",
      "path": "/public/register",
      "auth": "None",
      "request": {
        "username": "3-32 chars",
        "password": "8-64 chars",
        "nickname": "1-32 chars",
        "captchaId": "single-use",
        "captchaCode": "image characters"
      },
      "response": {
        "code": 200,
        "msg": "ok",
        "data": {
          "status": "active",
          "trialDays": 3,
          "callCredits": 100,
          "expiresAt": "Unix seconds"
        }
      }
    },
    {
      "method": "POST",
      "path": "/api/account/login",
      "auth": "None",
      "request": {
        "username": "platform account",
        "password": "password"
      },
      "response": {
        "code": 200,
        "msg": "ok",
        "data": {
          "token": "website token, expires after 24h",
          "nickname": "nickname"
        }
      }
    },
    {
      "method": "GET",
      "path": "/api/billing/summary",
      "auth": "Website token",
      "request": {},
      "response": {
        "code": 200,
        "msg": "ok",
        "data": {
          "remainingCalls": "integer or null for preexisting unmetered account",
          "expires_at": "Unix seconds",
          "expired": false
        }
      }
    },
    {
      "method": "GET",
      "path": "/api/keys",
      "auth": "Website token",
      "request": {},
      "response": {
        "code": 200,
        "msg": "ok",
        "data": "Key IDs, labels and prefixes; no full secret"
      }
    },
    {
      "method": "POST",
      "path": "/api/keys/create",
      "auth": "Website token",
      "request": {
        "label": "1-64 chars"
      },
      "response": {
        "code": 200,
        "msg": "ok",
        "data": {
          "id": "key ID",
          "apiKey": "one-time secret",
          "shownOnce": true
        }
      }
    },
    {
      "method": "POST",
      "path": "/api/keys/revoke",
      "auth": "Website token",
      "request": {
        "id": "owned key ID"
      },
      "response": {
        "code": 200,
        "msg": "ok",
        "data": {
          "revoked": true
        }
      }
    },
    {
      "method": "GET",
      "path": "/public/plans",
      "auth": "None",
      "request": {},
      "response": {
        "code": 200,
        "msg": "ok",
        "data": {
          "plans": [],
          "trialDays": 3,
          "trialCalls": 100,
          "paymentConfigured": false,
          "automaticPayment": false
        }
      }
    },
    {
      "method": "POST",
      "path": "/api/orders/create",
      "auth": "Website token",
      "request": {
        "planId": "enabled plan ID"
      },
      "response": {
        "code": 200,
        "msg": "ok",
        "data": {
          "orderId": "ID",
          "status": "pending",
          "paymentNote": "configured instructions",
          "automaticPayment": false
        }
      }
    },
    {
      "method": "GET",
      "path": "/api/orders",
      "auth": "Website token",
      "request": {},
      "response": {
        "code": 200,
        "msg": "ok",
        "data": "Last 100 owned orders"
      }
    },
    {
      "method": "GET",
      "path": "/admin/commerce",
      "auth": "Admin",
      "request": {},
      "response": {
        "code": 200,
        "msg": "ok",
        "data": "Settings, plans and last 100 orders"
      }
    },
    {
      "method": "POST",
      "path": "/admin/commerce/settings",
      "auth": "Admin",
      "request": {
        "trialDays": "integer 1-30",
        "trialCalls": "integer 1-100000",
        "paymentNote": "max 1000 chars; empty disables payment"
      },
      "response": {
        "code": 200,
        "msg": "ok",
        "data": {
          "saved": true
        }
      }
    },
    {
      "method": "POST",
      "path": "/admin/plans/save",
      "auth": "Admin",
      "request": {
        "id": "optional existing plan ID",
        "name": "1-64 chars",
        "priceCents": "integer currency cents",
        "calls": "positive integer",
        "days": "1-3650",
        "enabled": "boolean"
      },
      "response": {
        "code": 200,
        "msg": "ok",
        "data": {
          "id": "plan ID"
        }
      }
    },
    {
      "method": "POST",
      "path": "/admin/orders/confirm",
      "auth": "Admin",
      "request": {
        "orderId": "pending order ID",
        "receivedPayment": true
      },
      "response": {
        "code": 200,
        "msg": "ok",
        "data": {
          "activated": true
        }
      }
    }
  ],
  "note": "Current flow: self-service signup, website login, API Key for device business APIs. Legacy machine-binding APIs remain for compatibility. Payment gateway not integrated."
}