CodeGrex REST API v1

JSON over HTTPS. The CodeGrex IDE and web portal use this API for AI routing, billing, and authentication. Base URL:

https://codegrex-api.onrender.com

Overview

All versioned routes live under /v1/…
Request and response bodies are JSON unless noted (SSE for chat streaming).
Send Content-Type: application/json on POST/PATCH bodies.
Optional X-Request-Id header — echoed as x-request-id for support.
Breaking changes ship as a new major path (e.g. /v2) with deprecation headers on old routes.

Authentication

Protected routes require an Authorization header:

Authorization: Bearer <token>

Supabase JWT — three dot-separated segments. Used by the web portal after sign-in.
IDE token — opaque session token from the device or IDE login flow. Used by the desktop client.

Obtain an IDE token via the device login endpoints below.

Rate limits

Per-IP limits (Redis-backed in production). Standard rate-limit headers are included on responses.

Scope	Limit
Global	200 req / min
AI (chat + completions)	30 req / min
Auth	20 req / min
Telemetry / feedback	10 req / min

AI

Chat and inline completions. Requests consume credits from the authenticated user's balance.

POST/v1/chat/completionsAuth required

OpenAI-compatible chat completion. Supports streaming (SSE), tools, and agent/plan modes.

Request body

{
  "model": "claude-sonnet-4-6",
  "messages": [
    { "role": "system", "content": "You are a helpful coding assistant." },
    { "role": "user", "content": "Explain this function." }
  ],
  "stream": true,
  "max_tokens": 4096,
  "temperature": 0.7,
  "mode": "chat"
}

Response

// Non-streaming
{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "choices": [{ "message": { "role": "assistant", "content": "…" } }],
  "usage": { "inputTokens": 120, "outputTokens": 340 }
}

// Streaming: Content-Type text/event-stream
data: {"choices":[{"delta":{"content":"Hello"}}]}
data: [DONE]

mode may be chat, plan, or agent — affects stream timeout budgets.
Roles: system, user, assistant, tool. Tool calls follow the OpenAI shape.
402 when credits are insufficient; 429 when rate-limited.

https://codegrex-api.onrender.com/v1/chat/completions

POST/v1/completionsAuth required

Low-latency FIM-style code completion for the Tab model.

Request body

{
  "model": "codegrex-tab",
  "prefix": "function add(a, b) {\n  return ",
  "suffix": "\n}",
  "language": "typescript",
  "max_tokens": 128,
  "temperature": 0.2
}

Response

{
  "id": "cmpl-…",
  "choices": [{ "text": "a + b" }],
  "usage": { "inputTokens": 42, "outputTokens": 6 }
}

https://codegrex-api.onrender.com/v1/completions

Models

Discover models enabled for your account or the public catalog.

GET/v1/models

List models (OpenAI-style list object). Auth optional — signed-in users see entitlements.

Response

{
  "object": "list",
  "data": [
    {
      "id": "claude-sonnet-4-6",
      "object": "model",
      "name": "Claude Sonnet 4.6",
      "provider": "anthropic",
      "tier": "balanced",
      "context_window": 200000,
      "capabilities": ["chat", "tools"],
      "pricing": { "input_per_mtok": 3, "output_per_mtok": 15 }
    }
  ]
}

https://codegrex-api.onrender.com/v1/models

GET/v1/models/:id

Model metadata for a single catalog key.

https://codegrex-api.onrender.com/v1/models/:id

GET/v1/models/tiers/:tier

Models filtered by tier (e.g. efficient, balanced, flagship).

https://codegrex-api.onrender.com/v1/models/tiers/:tier

Catalog

Public pricing and plan data served from the admin-configured catalog.

GET/v1/catalog/manifest

Full catalog manifest (models, providers, plans). Auth optional.

https://codegrex-api.onrender.com/v1/catalog/manifest

GET/v1/catalog/plans

Subscription plans with monthly/yearly pricing.

https://codegrex-api.onrender.com/v1/catalog/plans

GET/v1/catalog/models

Model entries as exposed in the catalog (admin source of truth).

https://codegrex-api.onrender.com/v1/catalog/models

GET/v1/catalog/addon-credit-packs

One-time credit packs available for purchase.

https://codegrex-api.onrender.com/v1/catalog/addon-credit-packs

Account

Profile, usage history, credits, and self-service account actions.

GET/v1/account/meAuth required

Current user profile, tier, and credit balance.

https://codegrex-api.onrender.com/v1/account/me

GET/v1/accountAuth required

Alias of /me for backward compatibility.

https://codegrex-api.onrender.com/v1/account

GET/v1/account/usageAuth required

Usage summary for the billing period.

https://codegrex-api.onrender.com/v1/account/usage

GET/v1/account/usage/activityAuth required

Per-request activity log (paginated).

https://codegrex-api.onrender.com/v1/account/usage/activity

GET/v1/account/transactionsAuth required

Credit purchases and adjustments.

https://codegrex-api.onrender.com/v1/account/transactions

GET/v1/account/creditsAuth required

Current credit balance and limits.

https://codegrex-api.onrender.com/v1/account/credits

POST/v1/account/credits/purchaseAuth required

Start a Stripe checkout session for a credit pack.

Request body

{ "packId": "pack_50k", "successUrl": "…", "cancelUrl": "…" }

https://codegrex-api.onrender.com/v1/account/credits/purchase

GET/v1/account/tiers

Available subscription tiers (public).

https://codegrex-api.onrender.com/v1/account/tiers

POST/v1/account/upgradeAuth required

Start a Stripe checkout for a subscription tier.

Request body

{ "tier": "pro", "interval": "monthly", "successUrl": "…", "cancelUrl": "…" }

https://codegrex-api.onrender.com/v1/account/upgrade

PATCH/v1/account/profileAuth required

Update display name.

Request body

{ "displayName": "Alex Developer" }

https://codegrex-api.onrender.com/v1/account/profile

GET/v1/account/exportAuth required

Export account data (GDPR-style bundle).

https://codegrex-api.onrender.com/v1/account/export

DELETE/v1/accountAuth required

Permanently delete account (requires confirmEmail).

Request body

{ "confirmEmail": "you@example.com" }

https://codegrex-api.onrender.com/v1/account

Billing

Stripe-backed subscriptions and credit purchases for individual accounts.

GET/v1/billing/plans

Active plans from catalog (public).

https://codegrex-api.onrender.com/v1/billing/plans

GET/v1/billing/credit-packs

Credit packs (public).

https://codegrex-api.onrender.com/v1/billing/credit-packs

GET/v1/billing/statusAuth required

Subscription status, renewal date, and Stripe customer id.

https://codegrex-api.onrender.com/v1/billing/status

POST/v1/billing/subscribeAuth required

Create a subscription checkout session.

Request body

{ "tier": "pro", "interval": "monthly" }

https://codegrex-api.onrender.com/v1/billing/subscribe

POST/v1/billing/purchase-creditsAuth required

Create a one-time credit pack checkout session.

https://codegrex-api.onrender.com/v1/billing/purchase-credits

POST/v1/billing/portalAuth required

Stripe Customer Portal URL for invoices and payment methods.

https://codegrex-api.onrender.com/v1/billing/portal

POST/v1/billing/cancelAuth required

Cancel subscription at period end.

https://codegrex-api.onrender.com/v1/billing/cancel

POST/v1/billing/resumeAuth required

Resume a cancelled subscription.

https://codegrex-api.onrender.com/v1/billing/resume

POST/v1/billing/webhook

Stripe webhook (server-only — verified with STRIPE_WEBHOOK_SECRET).

Not for client use. Configure in Stripe Dashboard or Stripe CLI for local dev.

https://codegrex-api.onrender.com/v1/billing/webhook

Device login

OAuth-style device flow used by the desktop IDE to obtain a long-lived IDE token.

POST/v1/auth/device/start

Begin device authorization. Returns device_code and user_code.

Request body

{ "client_info": { "platform": "win32", "version": "1.0.0" } }

Response

{
  "device_code": "…",
  "user_code": "ABCD-EFGH",
  "verification_uri": "https://codegrex.com/device",
  "expires_in": 600,
  "interval": 2
}

https://codegrex-api.onrender.com/v1/auth/device/start

POST/v1/auth/device/poll

Poll until approved. Returns ide_token when status is approved.

Request body

{ "device_code": "…" }

https://codegrex-api.onrender.com/v1/auth/device/poll

POST/v1/auth/device/approveAuth required

Approve a pending device code (browser, after user sign-in).

Request body

{ "user_code": "ABCD-EFGH" }

https://codegrex-api.onrender.com/v1/auth/device/approve

POST/v1/auth/device/denyAuth required

Deny a pending device code.

https://codegrex-api.onrender.com/v1/auth/device/deny

POST/v1/auth/device/revoke

Revoke an IDE session by token.

https://codegrex-api.onrender.com/v1/auth/device/revoke

POST/v1/auth/ide/start

Alternative IDE browser login — returns a short-lived approval code.

https://codegrex-api.onrender.com/v1/auth/ide/start

POST/v1/auth/ide/approveAuth required

Approve IDE browser login from an authenticated session.

https://codegrex-api.onrender.com/v1/auth/ide/approve

POST/v1/auth/ide/token

Exchange approval code for IDE token.

https://codegrex-api.onrender.com/v1/auth/ide/token

Updates

Desktop auto-update metadata (electron-updater compatible).

GET/v1/updates/latest

Latest release version and download URLs.

https://codegrex-api.onrender.com/v1/updates/latest

GET/v1/updates/check

Check for updates (?version= current semver).

https://codegrex-api.onrender.com/v1/updates/check

GET/v1/updates/RELEASES

Release notes feed for the updater.

https://codegrex-api.onrender.com/v1/updates/RELEASES

GET/v1/updates/latest-mac.yml

macOS update manifest (YAML).

https://codegrex-api.onrender.com/v1/updates/latest-mac.yml

GET/v1/updates/latest-linux.yml

Linux update manifest (YAML).

https://codegrex-api.onrender.com/v1/updates/latest-linux.yml

Health

Liveness and readiness probes for operators and load balancers.

GET/health

Basic liveness — returns { status: "ok" }.

https://codegrex-api.onrender.com/health

GET/health/ready

Readiness — verifies database and Redis connectivity.

https://codegrex-api.onrender.com/health/ready

GET/health/detailed

Extended dependency status (internal ops).

https://codegrex-api.onrender.com/health/detailed

Errors

Errors return JSON with an error string. Common status codes:

Code	Meaning
400	Validation failed — check request body
401	Missing or invalid Bearer token
402	Insufficient credits
403	Policy or permission denied
404	Resource not found
408	Request timeout (long streams have extended idle limits)
429	Rate limit exceeded
500	Server error

{ "error": "Insufficient credits" }

The CodeGrex IDE is the primary API consumer. Third-party integrations are supported on individual plans; contact us if you need higher rate limits or a dedicated key.