API Reference
Essential API endpoints for Epic CLI backend integration and license management
Authentication
JWT token generation and validation
License Validation
Check license status and quotas
Usage Tracking
Record API calls and monitor quotas
Rate Limiting
Fair usage and throttling controls
Base URLs & Authentication
API Overview
The Epic CLI backend provides a REST API for license management, quota enforcement, and usage tracking. All endpoints require JWT authentication.
- Production:
https://api.ehrcli.com/api - Development:
http://localhost:3000/api
Authentication: All requests require a JWT token in the Authorization header:
Authorization: Bearer <jwt_token>Content Type: All requests and responses use JSON:
Content-Type: application/jsonAuthentication Endpoints
### Create License Token
Generate a JWT token for license-based authentication.
Endpoint: POST /api/license/token
Request:
{
"licenseKey": "START-2025-A1B2-C3D4",
"email": "user@example.com"
}Response:
{
"success": true,
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": "24h",
"license": {
"tier": "starter",
"status": "active",
"expiresAt": "2025-08-29T05:00:00.000Z"
}
}License Validation
### Validate License
Check license status and remaining quotas.
Endpoint: POST /api/license/validate
Request:
{
"licenseKey": "START-2025-A1B2-C3D4"
}Response:
{
"valid": true,
"tier": "starter",
"status": "active",
"issuedAt": "2024-08-29T05:00:00.000Z",
"expiresAt": "2025-08-29T05:00:00.000Z",
"usage": {
"remainingCalls": 1995,
"monthlyRemainingCalls": 59850,
"resetAt": "2025-08-30T00:00:00.000Z",
"monthlyResetAt": "2025-09-28T00:00:00.000Z"
}
}Usage Tracking
### Record API Usage
Track API call usage against license quotas.
Endpoint: POST /api/usage/record
Request:
{
"licenseKey": "START-2025-A1B2-C3D4",
"callCount": 1,
"endpoint": "patients/search",
"timestamp": "2025-01-15T10:30:00.000Z"
}Response:
{
"success": true,
"remainingCalls": 1994,
"monthlyRemainingCalls": 59849,
"quotaExceeded": false
}Error Handling
The API uses standard HTTP status codes and returns detailed error information:
Common Error Responses:
401 Unauthorized:
{
"error": "Invalid or expired token",
"code": "INVALID_TOKEN"
}403 Forbidden (Quota Exceeded):
{
"error": "Daily API quota exceeded",
"code": "QUOTA_EXCEEDED",
"resetAt": "2025-01-16T00:00:00.000Z"
}404 Not Found (Invalid License):
{
"error": "License not found or inactive",
"code": "LICENSE_NOT_FOUND"
}Rate Limiting
API endpoints are rate-limited to ensure fair usage:
- Authentication endpoints: 100 requests/minute
- License validation: 1000 requests/minute
- Usage tracking: 10000 requests/minute
Rate Limit Headers:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642694400When rate limits are exceeded, the API returns a 429 status code with retry information.
HTTP Status Codes
Success Codes
Error Codes
Integration Examples
The Epic CLI handles all API interactions automatically. For custom integrations, use these endpoints to build your own license management system.