Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Soju06/codex-lb/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Account Management API allows you to manage ChatGPT accounts used by Codex-LB for load balancing. You can import accounts, list them with usage statistics, pause/reactivate accounts, and view usage trends.
All Account Management endpoints require dashboard authentication via session cookie.

​
List Accounts

​
GET /api/accounts
endpoint
Returns all accounts with their status, usage statistics, and reset times.

​
Response

​
accounts
array
Array of account objects

​
Example Request

curl -X GET "https://your-instance.com/api/accounts" \
  -H "Cookie: dashboard_session=your-session-token"

​
Example Response

{
  "accounts": [
    {
      "account_id": "acc_123abc",
      "email": "user@example.com",
      "display_name": "Production Account",
      "plan_type": "pro",
      "status": "active",
      "usage": {
        "primary_remaining_percent": 75.5,
        "secondary_remaining_percent": 90.2
      },
      "reset_at_primary": "2026-03-04T00:00:00Z",
      "reset_at_secondary": "2026-03-10T00:00:00Z",
      "window_minutes_primary": 1440,
      "window_minutes_secondary": 10080,
      "capacity_credits_primary": 1000.0,
      "remaining_credits_primary": 755.0,
      "capacity_credits_secondary": 5000.0,
      "remaining_credits_secondary": 4510.0,
      "last_refresh_at": "2026-03-03T18:30:00Z",
      "deactivation_reason": null
    }
  ]
}

​
Import Account

​
POST /api/accounts/import
endpoint
Import a ChatGPT account using an auth.json file from the official OpenAI CLI.

​
Request

​
auth_json
file
required
The auth.json file containing ChatGPT session tokens. Must be uploaded as multipart/form-data.

​
Response

​
account_id
string
required
The imported account ID
​
email
string
required
Account email address
​
plan_type
string
required
ChatGPT plan type
​
status
string
required
Initial account status (typically “active”)

​
Example Request

curl -X POST "https://your-instance.com/api/accounts/import" \
  -H "Cookie: dashboard_session=your-session-token" \
  -F "auth_json=@/path/to/auth.json"

​
Example Response

{
  "account_id": "acc_456def",
  "email": "newuser@example.com",
  "plan_type": "pro",
  "status": "active"
}

​
Error Responses

​
400
error
invalid_auth_json: The auth.json file is malformed or missing required fields
​
409
error
duplicate_identity_conflict: An account with this identity already exists
​
GET /api/accounts/{account_id}/trends
endpoint
Retrieve historical usage trends for a specific account.

​
Path Parameters

​
account_id
string
required
The account ID to fetch trends for

​
Response

​
account_id
string
required
The account ID
​
primary
array
required
Array of usage trend points for primary window
​
secondary
array
required
Array of usage trend points for secondary window

​
Example Request

curl -X GET "https://your-instance.com/api/accounts/acc_123abc/trends" \
  -H "Cookie: dashboard_session=your-session-token"

​
Example Response

{
  "account_id": "acc_123abc",
  "primary": [
    { "t": "2026-03-03T00:00:00Z", "v": 850.5 },
    { "t": "2026-03-03T01:00:00Z", "v": 820.3 },
    { "t": "2026-03-03T02:00:00Z", "v": 755.0 }
  ],
  "secondary": [
    { "t": "2026-03-03T00:00:00Z", "v": 4800.0 },
    { "t": "2026-03-03T01:00:00Z", "v": 4650.0 },
    { "t": "2026-03-03T02:00:00Z", "v": 4510.0 }
  ]
}

​
Error Responses

​
404
error
account_not_found: No account exists with the specified ID

​
Pause Account

​
POST /api/accounts/{account_id}/pause
endpoint
Temporarily pause an account, preventing it from being used for requests.

​
Path Parameters

​
account_id
string
required
The account ID to pause

​
Response

​
status
string
required
Always returns “paused” on success

​
Example Request

curl -X POST "https://your-instance.com/api/accounts/acc_123abc/pause" \
  -H "Cookie: dashboard_session=your-session-token"

​
Example Response

{
  "status": "paused"
}

​
Error Responses

​
404
error
account_not_found: No account exists with the specified ID

​
Reactivate Account

​
POST /api/accounts/{account_id}/reactivate
endpoint
Reactivate a paused account, making it available for load balancing again.

​
Path Parameters

​
account_id
string
required
The account ID to reactivate

​
Response

​
status
string
required
Always returns “reactivated” on success

​
Example Request

curl -X POST "https://your-instance.com/api/accounts/acc_123abc/reactivate" \
  -H "Cookie: dashboard_session=your-session-token"

​
Example Response

{
  "status": "reactivated"
}

​
Error Responses

​
404
error
account_not_found: No account exists with the specified ID

​
Delete Account

​
DELETE /api/accounts/{account_id}
endpoint
Permanently delete an account from the system.

​
Path Parameters

​
account_id
string
required
The account ID to delete

​
Response

​
status
string
required
Always returns “deleted” on success

​
Example Request

curl -X DELETE "https://your-instance.com/api/accounts/acc_123abc" \
  -H "Cookie: dashboard_session=your-session-token"

​
Example Response

{
  "status": "deleted"
}

​
Error Responses

​
404
error
account_not_found: No account exists with the specified ID
Account deletion is permanent and cannot be undone. The account will immediately stop being used for load balancing.

​
Authentication

All account management endpoints require dashboard authentication. You must be logged in to the dashboard and include your session cookie in requests.

​
Common Error Codes

CodeDescription
account_not_foundThe specified account ID does not exist
invalid_auth_jsonThe auth.json file is invalid or malformed
duplicate_identity_conflictAn account with this identity already exists