/api/v1/regions/select (management)

This is the management service route. Its origin and authentication are described in Platform API overview and Authentication. A path shared by another service is a different endpoint.

Property	Contract
Methods	POST
Path	`/api/v1/regions/select`
Path parameters	None
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

Management auth context: validated x-api-key or configured session authentication; trusted gateway integration may select its auth pipeline. Organization/tenant checks are separate.

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.

POST

export async function POST(request: NextRequest) {
  const requestId = generateRequestId()
  let rateLimitInfo: RateLimitMetadata | undefined

  try {
    const authContext = await resolveAuthContext(request)

    const body = await validateBody(request, SelectRegionRequest)

    const evaluation = await enforceRateLimit({
      context: authContext,
    })

    rateLimitInfo = {
      ...evaluation.metadata,
      retryAfter: evaluation.retryAfter,
    }

    if (evaluation.blocked) {
      throw new RateLimitExceededError(evaluation.retryAfter ?? 60)
    }

    // Get the best region slug
    const selectedSlug = await selectBestRegion(
      body.preferredRegion,
      body.latitude,
      body.longitude
    )

    // Get full region details
    const region = await getRegionBySlug(authContext, selectedSlug)

    const response = apiSuccess({
      selectedRegion: region,
      selectionReason: body.preferredRegion
        ? body.preferredRegion === selectedSlug
          ? 'preferred_region_available'
          : 'preferred_region_unavailable_fallback'
        : body.latitude !== undefined && body.longitude !== undefined
          ? 'geo_proximity'
          : 'default_primary',
    })
    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 select region:', error)
    const response = apiError(
      new ApiError(500, 'INTERNAL_ERROR', 'Failed to select region'),
      requestId
    )
    return withRequestMetadata(response, requestId, rateLimitInfo)
  }
}

Source: minds-ui/apps/api-service/app/api/v1/regions/select/route.ts:26.

Response and error branches

Literal HTTP statuses in the route: 500. Shared management error classes are defined in Errors and responses.

new RateLimitExceededError(evaluation.retryAfter ?? 60)

Source: minds-ui/apps/api-service/app/api/v1/regions/select/route.ts:45.

apiSuccess({
      selectedRegion: region,
      selectionReason: body.preferredRegion
        ? body.preferredRegion === selectedSlug
          ? 'preferred_region_available'
          : 'preferred_region_unavailable_fallback'
        : body.latitude !== undefined && body.longitude !== undefined
          ? 'geo_proximity'
          : 'default_primary',
    })

Source: minds-ui/apps/api-service/app/api/v1/regions/select/route.ts:58.

apiError(error, requestId)

Source: minds-ui/apps/api-service/app/api/v1/regions/select/route.ts:71.

apiError(
      new ApiError(500, 'INTERNAL_ERROR', 'Failed to select region'),
      requestId
    )

Source: minds-ui/apps/api-service/app/api/v1/regions/select/route.ts:75.

new ApiError(500, 'INTERNAL_ERROR', 'Failed to select region')

Source: minds-ui/apps/api-service/app/api/v1/regions/select/route.ts:76.

Service dependencies

minds-ui/apps/api-service/lib/api-response.ts
minds-ui/apps/api-service/lib/validation.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

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/select/route.ts. SHA-256: aa6500d3a58eec2750c64ecb057fa94f2bbbd2ef58ca99bc6ba7aea52f45affb.