Download OpenAPI specification:Download
OpenAPI specification for admin-only rate limiting controls.
This module exposes endpoints to manage allowlist entries and reset rate limit counters. Rate limiting itself is enforced by middleware on public and authenticated endpoints.
Rate Limit Headers:
X-RateLimit-Limit: max requests per windowX-RateLimit-Remaining: remaining requests in the windowX-RateLimit-Reset: Unix timestamp when the window resetsRetry-After: seconds until retry (on 429/503 responses)Rate Limit Errors (non-admin endpoints):
rate_limit_exceededuser_rate_limit_exceededclient_rate_limit_exceededservice_unavailableAdds an IP address or user ID to the rate limit allowlist. Allowlisted identifiers bypass rate limiting until expiry.
| type required | string (AllowlistEntryType) Enum: "ip" "user_id" Identifier type for allowlist entries |
| identifier required | string IP address or user ID |
| reason required | string Reason for allowlisting |
| expires_at | string or null <date-time> Optional expiry for the allowlist entry |
{- "type": "ip",
- "identifier": "192.168.1.100",
- "reason": "Monitoring service",
- "expires_at": "2025-12-31T00:00:00Z"
}{- "allowlisted": true,
- "identifier": "192.168.1.100",
- "expires_at": "2025-12-31T00:00:00Z"
}Removes an IP address or user ID from the allowlist.
| type required | string (AllowlistEntryType) Enum: "ip" "user_id" Identifier type for allowlist entries |
| identifier required | string IP address or user ID |
{- "type": "ip",
- "identifier": "192.168.1.100"
}{- "error": "bad_request",
- "error_description": "Invalid JSON in request body"
}Returns all active allowlist entries (non-expired).
[- {
- "id": "alw_123",
- "type": "ip",
- "identifier": "192.168.1.100",
- "reason": "Monitoring service",
- "expires_at": "2025-12-31T00:00:00Z",
- "created_at": "2025-01-01T12:00:00Z",
- "created_by": "550e8400-e29b-41d4-a716-446655440000"
}
]Clears the rate limit counters for a specific identifier. The optional class restricts the reset to a specific endpoint class.
| type required | string (AllowlistEntryType) Enum: "ip" "user_id" Identifier type for allowlist entries |
| identifier required | string IP address or user ID |
| class | string (EndpointClass) Enum: "auth" "sensitive" "read" "write" Endpoint class for rate limiting |
{- "type": "ip",
- "identifier": "192.168.1.100",
- "class": "auth"
}{- "error": "bad_request",
- "error_description": "Invalid JSON in request body"
}Returns the current quota usage for a specific API key (PRD-017 FR-5). Shows usage, limit, remaining requests, and reset time.
| api_key required | string <uuid> API key identifier |
{- "api_key_id": "550e8400-e29b-41d4-a716-446655440000",
- "tier": "starter",
- "usage": 450,
- "limit": 1000,
- "remaining": 550,
- "reset_at": "2025-02-01T00:00:00Z"
}Resets the quota usage counter for a specific API key to zero (PRD-017 FR-5). Optionally accepts a reason for audit purposes.
| api_key required | string <uuid> API key identifier |
| reason | string <= 500 characters Optional reason for resetting the quota (for audit) |
{- "reason": "Customer support escalation"
}{- "status": "reset"
}Returns quota usage for all registered API keys (PRD-017 FR-5).
[- {
- "api_key_id": "550e8400-e29b-41d4-a716-446655440000",
- "tier": "starter",
- "usage": 450,
- "limit": 1000,
- "remaining": 550,
- "reset_at": "2025-02-01T00:00:00Z"
}, - {
- "api_key_id": "660e8400-e29b-41d4-a716-446655440001",
- "tier": "business",
- "usage": 5000,
- "limit": 10000,
- "remaining": 5000,
- "reset_at": "2025-02-01T00:00:00Z"
}
]Updates the quota tier for a specific API key (PRD-017 FR-5). The new tier's limits take effect immediately.
| api_key required | string <uuid> API key identifier |
| tier required | string (QuotaTier) Enum: "free" "starter" "business" "enterprise" API quota tier determining monthly request limits |
{- "tier": "business"
}{- "status": "updated",
- "tier": "business"
}