Cloud REST API
The LingXizhi cloud services expose a REST API used by the IDE core, website and integrations, prefixed with /api/v1. The domain below is an example; use your deployment's configured address. Availability depends on deployment, account permissions, payment channels and resource configuration, not an always-online public-cloud guarantee. Model requests send selected context through the gateway to providers.
Who this is for: developers connecting directly to the server (CI integrations, custom tooling). The client and core call relevant endpoints according to configuration during IDE use; they do not necessarily cover every server API. For the local core, see the Kernel API.
Authentication
Protected user endpoints require a JWT Bearer token. Registration, login, email codes and password resets do not require a user JWT; MFA verification uses a login ticket. Payment callbacks are called by payment platforms and signature-verified server-side, without a user JWT:
curl -H "Authorization: Bearer <access_token>" https://www.lingxizhiai.com/api/v1/membership/current
Obtain the token via /auth/login and renew it with /auth/refresh before it expires. When MFA is enabled and server prerequisites are configured, login returns mfa_required + mfa_ticket; complete the second factor via /auth/mfa/verify to obtain the token. MFA endpoint registration depends on deployment prerequisites.
Auth endpoints
| Method | Path | Description |
|---|---|---|
| POST | /auth/register | Register (email + username + password + code) |
| POST | /auth/login | Sign in; MFA accounts get an intermediate ticket |
| POST | /auth/mfa/verify | MFA second factor (ticket + TOTP/recovery code) |
| POST | /auth/send-code | Send an email verification code |
| POST | /auth/reset-password | Reset password |
| POST | /auth/refresh | Refresh the access token (protected, using the refresh token as Bearer) |
Membership and subscriptions
| Method | Path | Description |
|---|---|---|
| GET | /membership/plans | Plan catalog (public — powers dynamic pricing on the website) |
| GET | /membership/current | Current membership status (incl. credit balance) |
| POST | /membership/subscribe | Create a subscription order (pending payment) |
| POST | /membership/upgrade | Upgrade to a higher tier (remaining credits carry over in full) |
| POST | /membership/cancel | Cancel the subscription (downgrades to Free at period end) |
| GET | /membership/quota | Quota check |
| GET | /membership/usage?days=30 | Subscription usage by day |
| GET | /membership/orders | Order history |
| POST | /membership/orders/:order_no/cancel | Cancel one of your pending orders |
Creating a subscription or upgrade order does not activate benefits. Payment confirmation and entitlement updates are required. Contact support when payment channels are unavailable; cloud resources also require deployed services.
Credits
| Method | Path | Description |
|---|---|---|
| GET | /credits/balance | Purchased-credit balance and plan credit remaining |
| GET | /credits/ledger?limit&offset | Credit ledger (recharge / consume / carry-over) |
| POST | /credits/recharge | Create a credit top-up order (WeChat / Alipay) |
| GET | /credits/orders/:order_no | Credit order status |
| GET | /credits/orders | Credit order history |
Usage statistics
| Method | Path | Description |
|---|---|---|
| GET | /usage/logs?limit&offset | Call log details |
| GET | /usage/stats?days=7 | Usage summary (requests, tokens, cache savings) |
| GET | /usage/daily?days=30 | Daily usage |
| GET | /usage/models?days=30 | Per-model statistics |
| GET | /usage/cost?days=30 | Cost statistics |
| GET | /usage/completions | Completion acceptance rate, last 30 days |
Online payments
| Method | Path | Description |
|---|---|---|
| GET | /payment/config | Payment channel switches (public) |
| POST | /payment/orders | Create a payment order (subscription or upgrade; credit top-ups use /credits/recharge) |
| GET | /payment/orders/:order_no | Poll order status |
| POST | /payment/notify/:channel | Async channel callback (server-to-server, signature verified) |
Hosted LLM gateway (OpenAI-compatible)
The hosted pool exposes an OpenAI-compatible chat endpoint — no BYOK required, billed in credits. Use the user access token as Bearer:
curl https://www.lingxizhiai.com/api/v1/llm/gateway/v1/chat/completions \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"model": "<model-id-from-catalog>", "messages": [{"role": "user", "content": "Hello"}], "stream": true}'
Replace <model-id-from-catalog> with an ID from the current account's model catalog; do not assume a fixed model or permission.
stream enables SSE pass-through. Purchased credits are consumed first, then plan credits; insufficient balance returns 402. The model catalog and retail prices are managed server-side, and available models and minimum plan requirements depend on the current catalog and account permissions (see Plans & quotas).
Cloud tasks and sandboxes
| Method | Path | Description |
|---|---|---|
| POST | /tasks/submit | Submit a cloud task |
| GET | /tasks · /tasks/:id | Task list / status |
| POST | /tasks/:id/cancel | Cancel a task |
| GET | /cloud/vms · /cloud/quotas | Cloud sandbox instances and quotas |
Rate limits
Rate-limit windows and verification requirements depend on deployment configuration and endpoint responses. Limits may return 429, and some endpoints require a CAPTCHA. Use exponential backoff in integrations and avoid tight polling — poll order status at 3-5 second intervals.
Next steps
- Local core endpoints (use the actual connection address): Kernel API.
- Plan tiers and model gating: Plans & quotas.
- Connect your own provider keys: Bring your own API key.