# /api/v1/regions/[slug]/health (management) Source-derived management endpoint contract, authentication, request validation, responses, and errors. Source: https://docs.minds.sh/docs/api/platform/reference/management--api-v1-regions-slug-health This is the **management** service route. Its origin and authentication are described in [Platform API overview](/docs/api/platform) and [Authentication](/docs/api/platform/authentication). A path shared by another service is a different endpoint. | Property | Contract | | ------------------------------ | ------------------------------------------------------------------------------ | | Methods | GET, POST | | Path | `/api/v1/regions/[slug]/health` | | Path parameters | `slug` | | Query parameters read in route | None read directly; schema validation below may define additional fields | | Headers read in route | No additional direct header reads; authentication helpers may read credentials | ## Authentication and access [#authentication-and-access] Management auth context: validated x-api-key or configured session authentication; trusted gateway integration may select its auth pipeline. Organization/tenant checks are separate. ## Request and response definitions [#request-and-response-definitions] The following named definitions are imported or declared by this route. Optional markers, defaults, bounds, and enum values are shown exactly as implemented. A response type is a source contract, not an example populated with real account data. ### RegionHealthResponse [#regionhealthresponse] ```typescript RegionHealthResponse = z.object({ regionId: z.string(), slug: z.string(), status: RegionStatus, healthy: z.boolean(), lastCheck: z.string(), message: z.string().nullable(), capacity: RegionCapacity, kubernetesConnected: z.boolean(), ingressHealthy: z.boolean(), certificatesValid: z.boolean(), }) ``` Source: `minds-ui/apps/api-service/types/region.ts:120`. ### RegionHealthResponse [#regionhealthresponse-1] ```typescript export type RegionHealthResponse = z.infer ``` Source: `minds-ui/apps/api-service/types/region.ts:132`. ### RouteParams [#routeparams] ```typescript interface RouteParams { params: Promise<{ slug: string }> } ``` Source: `minds-ui/apps/api-service/app/api/v1/regions/[slug]/health/route.ts:18`. ## Method behavior [#method-behavior] The handler excerpt preserves field validation, response envelopes, cookie changes, and exception branches. Values returned by service helpers retain their named response type above; for passthrough routes, the upstream response is authoritative. ### GET [#get] ```typescript export async function GET(request: NextRequest, { params }: RouteParams) { const requestId = generateRequestId() let rateLimitInfo: RateLimitMetadata | undefined const { slug } = await params try { const authContext = await resolveAuthContext(request) const evaluation = await enforceRateLimit({ context: authContext, }) rateLimitInfo = { ...evaluation.metadata, retryAfter: evaluation.retryAfter, } if (evaluation.blocked) { throw new RateLimitExceededError(evaluation.retryAfter ?? 60) } const health = await getRegionHealth(authContext, slug) const response = apiSuccess(health) return withRequestMetadata(response, requestId, rateLimitInfo) } catch (error) { if (error instanceof ApiError) { const response = apiError(error, requestId) return withRequestMetadata(response, requestId, rateLimitInfo) } console.error('Failed to get region health:', error) const response = apiError( new ApiError(500, 'INTERNAL_ERROR', 'Failed to get region health'), requestId ) return withRequestMetadata(response, requestId, rateLimitInfo) } } ``` Source: `minds-ui/apps/api-service/app/api/v1/regions/[slug]/health/route.ts:26`. ### POST [#post] ```typescript export async function POST(request: NextRequest, { params }: RouteParams) { const requestId = generateRequestId() let rateLimitInfo: RateLimitMetadata | undefined const { slug } = await params try { const authContext = await resolveAuthContext(request) // TODO: Add admin check here // if (!authContext.isAdmin) { // throw new ApiError(403, 'FORBIDDEN', 'Only admins can trigger health checks') // } const evaluation = await enforceRateLimit({ context: authContext, }) rateLimitInfo = { ...evaluation.metadata, retryAfter: evaluation.retryAfter, } if (evaluation.blocked) { throw new RateLimitExceededError(evaluation.retryAfter ?? 60) } const health = await triggerHealthCheck(authContext, slug) const response = apiSuccess(health) return withRequestMetadata(response, requestId, rateLimitInfo) } catch (error) { if (error instanceof ApiError) { const response = apiError(error, requestId) return withRequestMetadata(response, requestId, rateLimitInfo) } console.error('Failed to trigger health check:', error) const response = apiError( new ApiError(500, 'INTERNAL_ERROR', 'Failed to trigger health check'), requestId ) return withRequestMetadata(response, requestId, rateLimitInfo) } } ``` Source: `minds-ui/apps/api-service/app/api/v1/regions/[slug]/health/route.ts:69`. ## Response and error branches [#response-and-error-branches] Literal HTTP statuses in the route: 403, 500. Shared management error classes are defined in [Errors and responses](/docs/api/platform/errors). ```typescript new RateLimitExceededError(evaluation.retryAfter ?? 60) ``` Source: `minds-ui/apps/api-service/app/api/v1/regions/[slug]/health/route.ts:44`. ```typescript apiSuccess(health) ``` Source: `minds-ui/apps/api-service/app/api/v1/regions/[slug]/health/route.ts:49`. ```typescript apiError(error, requestId) ``` Source: `minds-ui/apps/api-service/app/api/v1/regions/[slug]/health/route.ts:53`. ```typescript apiError( new ApiError(500, 'INTERNAL_ERROR', 'Failed to get region health'), requestId ) ``` Source: `minds-ui/apps/api-service/app/api/v1/regions/[slug]/health/route.ts:57`. ```typescript new ApiError(500, 'INTERNAL_ERROR', 'Failed to get region health') ``` Source: `minds-ui/apps/api-service/app/api/v1/regions/[slug]/health/route.ts:58`. ```typescript new RateLimitExceededError(evaluation.retryAfter ?? 60) ``` Source: `minds-ui/apps/api-service/app/api/v1/regions/[slug]/health/route.ts:92`. ```typescript apiSuccess(health) ``` Source: `minds-ui/apps/api-service/app/api/v1/regions/[slug]/health/route.ts:97`. ```typescript apiError(error, requestId) ``` Source: `minds-ui/apps/api-service/app/api/v1/regions/[slug]/health/route.ts:101`. ```typescript apiError( new ApiError(500, 'INTERNAL_ERROR', 'Failed to trigger health check'), requestId ) ``` Source: `minds-ui/apps/api-service/app/api/v1/regions/[slug]/health/route.ts:105`. ```typescript new ApiError(500, 'INTERNAL_ERROR', 'Failed to trigger health check') ``` Source: `minds-ui/apps/api-service/app/api/v1/regions/[slug]/health/route.ts:106`. ## Service dependencies [#service-dependencies] * `minds-ui/apps/api-service/lib/api-response.ts` * `minds-ui/apps/api-service/types/region.ts` * `minds-ui/apps/api-service/types/errors.ts` * `minds-ui/apps/api-service/lib/services/auth-context.ts` * `minds-ui/apps/api-service/lib/services/region-service.ts` * `minds-ui/apps/api-service/lib/services/rate-limit.ts` ## Evidence [#evidence] Generated from the local source snapshot on 2026-09-12. This page documents implemented code and does not certify a deployed service, permissions configuration, or successful provider operation. Source file: `minds-ui/apps/api-service/app/api/v1/regions/[slug]/health/route.ts`. SHA-256: `e34c385ec8cb11a45d92d04ad892c7ee686610b8394883802aeeceea7df74376`.