Admin APIs
Admin APIs live under /api/v1/admin/** and are intended for operational tooling and admin-only product surfaces.
Access model
All documented admin routes currently require:
- a valid bearer token
- a principal with
ADMINrole
In practice:
- missing or invalid auth returns
401 - authenticated non-admin users should expect
403 - write-heavy admin routes are also subject to normal API rate limiting
Invitations
Invitation management routes live under /api/v1/admin/invitations.
| Endpoint | Purpose | Current response shape |
|---|---|---|
POST /api/v1/admin/invitations?createdBy=... | Generate one invitation code | raw string |
POST /api/v1/admin/invitations/batch?createdBy=...&count=... | Generate multiple invitation codes | raw string array |
GET /api/v1/admin/invitations?page=...&size=...&status=... | List invitation codes | raw Page<InvitationCode> |
GET /api/v1/admin/invitations/{code} | Read one invitation | raw InvitationCode |
DELETE /api/v1/admin/invitations/{code} | Revoke invitation | 204 No Content |
Notable contract details:
createdByis passed as a query parameter, not JSON body content- invitation routes currently return raw entities and strings, not
ApiResponse<T> - the list route supports optional filtering by invitation status
User administration
User management routes live under /api/v1/admin/users.
| Endpoint | Purpose | Current response shape |
|---|---|---|
GET /api/v1/admin/users | Paginated user list with filters | raw Page<UserAdminDto> |
GET /api/v1/admin/users/{userId} | Read one user | raw UserAdminDto |
PATCH /api/v1/admin/users/{userId} | Update username, email, full name, status, role, or tier | raw UserAdminDto |
POST /api/v1/admin/users/{userId}/suspend | Suspend account | raw UserAdminDto |
POST /api/v1/admin/users/{userId}/activate | Activate account | raw UserAdminDto |
GET /api/v1/admin/users/stats | Aggregate user stats | raw stats object |
Supported list filters:
pagesizerolestatusmembershipTiersearch
Notable behavior:
- list size defaults to
20 - list size is capped at
200 - attempts to suspend or demote the last remaining admin are rejected with
400 - that guardrail currently returns the unchanged user DTO body, not a dedicated error object
Billing and quota configuration
Admin configuration routes use the shared response envelope more consistently.
Billing config
Routes under /api/v1/admin/billing:
| Endpoint | Purpose | Current response shape |
|---|---|---|
GET /api/v1/admin/billing/config | Read billing and expert review config | ApiResponse<AdminBillingConfigResponse> |
PUT /api/v1/admin/billing/plans/{tier} | Update one membership tier plan | ApiResponse<SubscriptionPlanDto> |
PUT /api/v1/admin/billing/expert-review | Update one-time expert review pricing | ApiResponse<ExpertReviewOfferingDto> |
Quota config
Routes under /api/v1/admin/quotas:
| Endpoint | Purpose | Current response shape |
|---|---|---|
GET /api/v1/admin/quotas/config | Read full quota config | ApiResponse<AdminQuotaConfigResponse> |
PUT /api/v1/admin/quotas/tiers/{tier} | Update one tier quota policy | ApiResponse<TierQuotaDto> |
PUT /api/v1/admin/quotas/global | Update global quota policy | ApiResponse<GlobalQuotaDto> |
Both config groups key off the existing membership tiers:
FREESTARTERPROFESSIONALENTERPRISE
Expert review operations
Manual expert review operations live under /api/v1/admin/expert-reviews.
| Endpoint | Purpose | Current response shape |
|---|---|---|
GET /api/v1/admin/expert-reviews/orders | Paginated order list | ApiResponse<Page<...>> |
GET /api/v1/admin/expert-reviews/orders/{orderId} | Order details | ApiResponse<...> |
PATCH /api/v1/admin/expert-reviews/orders/{orderId}/status | Update order status | ApiResponse<...> |
GET /api/v1/admin/expert-reviews/orders/{orderId}/files/download | Download project files as ZIP | streaming application/zip |
GET /api/v1/admin/expert-reviews/orders/{orderId}/t661/latest | Latest T661 payload for the order project | ApiResponse<...> |
Operational caveats:
- the file download endpoint is not JSON and should be treated as a binary stream
- order filtering currently supports optional
status - status updates are rate-limited like other admin mutations
Contract caveats
The admin surface is not fully normalized yet:
- invitation and user-management routes mostly return raw DTOs or entities
- billing, quota, and most expert-review routes return
ApiResponse<T> - expert-review file export returns a ZIP stream
If you build admin clients or scripts, handle response shapes per endpoint group instead of assuming one uniform parser.