Skip to content

claude.md

Latest commit

 

History

History
103 lines (82 loc) · 2.63 KB

claude.md

File metadata and controls

103 lines (82 loc) · 2.63 KB

Claude Code

Reverse-engineered, undocumented API. May change without notice.

Overview

  • Protocol: REST (plain JSON)
  • Base URL: https://api.anthropic.com
  • Auth provider: platform.claude.com (OAuth 2.0)
  • Client ID: 9d1c250a-e61b-44d9-88ed-5944d1962f5e
  • Beta header required: anthropic-beta: oauth-2025-04-20
  • Utilization: integer percentage (0-100)
  • Credits: cents (divide by 100 for dollars)
  • Timestamps: ISO 8601 (response), unix milliseconds (credentials file)

Endpoints

GET /api/oauth/usage

Returns rate limit windows and optional extra credits.

Headers

Header Required Value
Authorization yes Bearer <access_token>
Accept yes application/json
Content-Type yes application/json
anthropic-beta yes oauth-2025-04-20

Response

{
  "five_hour": {
    "utilization": 25,              // % used in 5h rolling window
    "resets_at": "2026-01-28T15:00:00Z"
  },
  "seven_day": {
    "utilization": 40,              // % used in 7-day window
    "resets_at": "2026-02-01T00:00:00Z"
  },
  "seven_day_opus": {               // separate weekly Opus limit (optional, plan-dependent)
    "utilization": 0,
    "resets_at": "2026-02-01T00:00:00Z"
  },
  "extra_usage": {                  // on-demand overage credits (optional)
    "is_enabled": true,
    "used_credits": 500,            // cents spent
    "monthly_limit": 10000,         // cents cap (0 = unlimited)
    "currency": "USD"
  }
}

All windows are enforced simultaneously — hitting any limit throttles the user.

Authentication

Token Location

Primary: ~/.claude/.credentials.json

{
  "claudeAiOauth": {
    "accessToken": "<jwt>",          // OAuth access token (Bearer)
    "refreshToken": "<token>",
    "expiresAt": 1738300000000,      // unix ms
    "scopes": ["..."],
    "subscriptionType": "pro",
    "rateLimitTier": "..."
  }
}

Fallback: macOS Keychain, service name Claude Code-credentials (same JSON structure).

Token Refresh

Access tokens are short-lived JWTs. Refreshed proactively 5 minutes before expiration, or reactively on 401/403.

POST https://platform.claude.com/v1/oauth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "<refresh_token>",
  "client_id": "9d1c250a-e61b-44d9-88ed-5944d1962f5e",
  "scope": "user:profile user:inference user:sessions:claude_code user:mcp_servers"
}
{
  "access_token": "<new_jwt>",
  "refresh_token": "<new_refresh_token>",  // may be same as previous
  "expires_in": 3600                       // seconds
}