Document Virtual Key Management API with JSON Schemas and Discovery Process

[malikbenkirane]

Overview

Create comprehensive documentation for LiteLLM's virtual key management API endpoints, including request/response JSON schemas and a guide on how to discover API information in the codebase.

Success Criteria

1. Complete API Endpoint Coverage

Document all key management endpoints with the following for each:

Endpoint	Method	Description
/key/generate	POST	Create a new virtual key
/key/update	POST	Update an existing key's parameters
/key/delete	POST	Delete one or more keys
/key/info	GET	Retrieve key information
/key/unblock	POST	Unblock a blocked key
/key/regenerate	POST	Regenerate a key with optional grace period
/key/service-account/generate	POST	Create a service account key

2. JSON Schema Examples for Each Endpoint

Each endpoint should include:

• Request Body Schema: Full JSON structure with field descriptions and types
• Required vs Optional Fields: Clearly marked
• Example Request: curl command with realistic values
• Example Response: Expected response JSON

Example format for /key/generate:

{
  "key": "string (optional) - Custom key value, auto-generated if omitted",
  "key_alias": "string (optional) - User-friendly alias",
  "team_id": "string (optional) - Associated team ID",
  "user_id": "string (optional) - Associated user ID",
  "max_budget": "number (optional) - Maximum budget in USD",
  "models": ["array of strings (optional) - Allowed model names"],
  "duration": "string (optional) - Key validity (e.g., '30d', '24h')",
  "metadata": "object (optional) - Custom metadata key-value pairs"
  // ... additional fields
}

3. API Discovery Process Documentation

Explain how maintainers can discover and verify API information:

• Locating Endpoints: How to find route definitions in key_management_endpoints.py
• Finding Request/Response Types: Tracing Pydantic model inheritance chains in _types.py
• Reading Docstrings: Where to find inline documentation and curl examples
• Quick Reference Table: Endpoint → Method → Request Type → File Location

4. File Locations Reference

Create a reference section mapping:

Content	File Location
Endpoint handlers	litellm/proxy/management_endpoints/key_management_endpoints.py
Request schemas	litellm/proxy/_types.py
Base models	GenerateRequestBase (line 917), KeyRequestBase (line 969)
Specific models	GenerateKeyRequest (line 998), UpdateKeyRequest (line 1056), etc.

Non-Goals

• Documenting internal implementation details
• Creating API client SDKs
• Documenting deprecated/undocumented endpoints

Acceptance Criteria

• All 7 key management endpoints documented
• Each endpoint has request JSON schema with field descriptions
• Each endpoint has response JSON schema
• Each endpoint has working curl example
• Discovery process section explains how to find API information in codebase
• File location reference table included

Related Files

• litellm/proxy/management_endpoints/key_management_endpoints.py
• litellm/proxy/_types.py (lines 917-1090 for key-related schemas)

[malikbenkirane]

litellm v1.83.14-stable.patch.3