/api/v1/tenants/[id] (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	GET, PATCH, DELETE
Path	`/api/v1/tenants/[id]`
Path parameters	`id`
Query parameters read in route	`force`
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.

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.

UpdateTenantRequest

UpdateTenantRequest = z.object({
  name: z.string().min(1).max(100).optional(),
  plan: TenantPlan.optional(),
  product_type: ProductType.optional(),
  config: TenantConfig.optional(),
  plan_memory_limit: z.number().int().min(0).nullable().optional(),
  plan_retrieval_quota: z.number().int().min(0).nullable().optional(),
  plan_graph_enabled: z.boolean().optional(),
  plan_node_partitioning: z.boolean().optional(),
})

Source: minds-ui/apps/api-service/types/tenant.ts:173.

UpdateTenantRequest

export type UpdateTenantRequest = z.infer<typeof UpdateTenantRequest>

Source: minds-ui/apps/api-service/types/tenant.ts:184.

RouteContext

interface RouteContext {
  params: Promise<{ id: string }>
}

Source: minds-ui/apps/api-service/app/api/v1/tenants/[id]/route.ts:22.

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

export async function GET(request: NextRequest, context: RouteContext) {
  const requestId = generateRequestId()
  const { id } = await context.params
  let rateLimitInfo: RateLimitMetadata | undefined

  try {
    const tenantId = validateTenantId(id)
    const authContext = await resolveAuthContext(request)
    const tenant = await getTenantDetails(authContext, tenantId)

    const evaluation = await enforceRateLimit({
      context: authContext,
      tenantId,
      tenantPlan: tenant.plan,
    })

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

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

    const response = apiSuccess<Tenant>(tenant)
    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 tenant:', error)
    const response = apiError(
      new ApiError(500, 'INTERNAL_ERROR', 'Failed to get tenant'),
      requestId,
    )
    return withRequestMetadata(response, requestId, rateLimitInfo)
  }
}

Source: minds-ui/apps/api-service/app/api/v1/tenants/[id]/route.ts:26.

PATCH

export async function PATCH(request: NextRequest, context: RouteContext) {
  const requestId = generateRequestId()
  const { id } = await context.params
  let rateLimitInfo: RateLimitMetadata | undefined

  try {
    const tenantId = validateTenantId(id)
    const authContext = await resolveAuthContext(request)
    const updates = await validateBody(request, UpdateTenantRequest)

    const evaluation = await enforceRateLimit({
      context: authContext,
      tenantId,
      tenantPlan: updates.plan,
    })

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

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

    const response = await updateTenant(authContext, tenantId, updates)
    const payload = apiSuccess(response)
    return withRequestMetadata(payload, requestId, rateLimitInfo)
  } catch (error) {
    if (error instanceof ApiError) {
      const response = apiError(error, requestId)
      return withRequestMetadata(response, requestId, rateLimitInfo)
    }
    console.error('Failed to update tenant:', error)
    const response = apiError(
      new ApiError(500, 'INTERNAL_ERROR', 'Failed to update tenant'),
      requestId,
    )
    return withRequestMetadata(response, requestId, rateLimitInfo)
  }
}

Source: minds-ui/apps/api-service/app/api/v1/tenants/[id]/route.ts:67.

DELETE

export async function DELETE(request: NextRequest, context: RouteContext) {
  const requestId = generateRequestId()
  const { id } = await context.params
  let rateLimitInfo: RateLimitMetadata | undefined

  try {
    const tenantId = validateTenantId(id)
    const force = request.nextUrl.searchParams.get('force') === 'true'
    const authContext = await resolveAuthContext(request)

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

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

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

    const response = await deleteTenant(authContext, tenantId, { force })
    const payload = apiSuccess(response, 202)
    return withRequestMetadata(payload, requestId, rateLimitInfo)
  } catch (error) {
    if (error instanceof ApiError) {
      const response = apiError(error, requestId)
      return withRequestMetadata(response, requestId, rateLimitInfo)
    }
    console.error('Failed to delete tenant:', error)
    const response = apiError(
      new ApiError(500, 'INTERNAL_ERROR', 'Failed to delete tenant'),
      requestId,
    )
    return withRequestMetadata(response, requestId, rateLimitInfo)
  }
}

Source: minds-ui/apps/api-service/app/api/v1/tenants/[id]/route.ts:109.

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/tenants/[id]/route.ts:48.

apiSuccess<Tenant>(tenant)

Source: minds-ui/apps/api-service/app/api/v1/tenants/[id]/route.ts:51.

apiError(error, requestId)

Source: minds-ui/apps/api-service/app/api/v1/tenants/[id]/route.ts:55.

apiError(
      new ApiError(500, 'INTERNAL_ERROR', 'Failed to get tenant'),
      requestId,
    )

Source: minds-ui/apps/api-service/app/api/v1/tenants/[id]/route.ts:59.

new ApiError(500, 'INTERNAL_ERROR', 'Failed to get tenant')

Source: minds-ui/apps/api-service/app/api/v1/tenants/[id]/route.ts:60.

new RateLimitExceededError(evaluation.retryAfter ?? 60)

Source: minds-ui/apps/api-service/app/api/v1/tenants/[id]/route.ts:89.

apiSuccess(response)

Source: minds-ui/apps/api-service/app/api/v1/tenants/[id]/route.ts:93.

apiError(error, requestId)

Source: minds-ui/apps/api-service/app/api/v1/tenants/[id]/route.ts:97.

apiError(
      new ApiError(500, 'INTERNAL_ERROR', 'Failed to update tenant'),
      requestId,
    )

Source: minds-ui/apps/api-service/app/api/v1/tenants/[id]/route.ts:101.

new ApiError(500, 'INTERNAL_ERROR', 'Failed to update tenant')

Source: minds-ui/apps/api-service/app/api/v1/tenants/[id]/route.ts:102.

new RateLimitExceededError(evaluation.retryAfter ?? 60)

Source: minds-ui/apps/api-service/app/api/v1/tenants/[id]/route.ts:130.

apiSuccess(response, 202)

Source: minds-ui/apps/api-service/app/api/v1/tenants/[id]/route.ts:134.

apiError(error, requestId)

Source: minds-ui/apps/api-service/app/api/v1/tenants/[id]/route.ts:138.

apiError(
      new ApiError(500, 'INTERNAL_ERROR', 'Failed to delete tenant'),
      requestId,
    )

Source: minds-ui/apps/api-service/app/api/v1/tenants/[id]/route.ts:142.

new ApiError(500, 'INTERNAL_ERROR', 'Failed to delete tenant')

Source: minds-ui/apps/api-service/app/api/v1/tenants/[id]/route.ts:143.

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/tenant.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/tenant-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/tenants/[id]/route.ts. SHA-256: 97b361397a8d4fabba0b1e21e12efe4c7c5186be8f88aa50db289864da5da370.

/api/v1/tenants/[id] (management)

On this page