# /api/v1/services/[id] (management)

Source-derived management endpoint contract, authentication, request validation, responses, and errors.

Source: https://docs.minds.sh/docs/api/platform/reference/management--api-v1-services-id



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, PUT, DELETE                                                               |
| Path                           | `/api/v1/services/[id]`                                                        |
| Path parameters                | `id`                                                                           |
| 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.

### UpdateServiceRequest [#updateservicerequest]

```typescript
UpdateServiceRequest = z.object({
  name: z.string().min(1).max(100).optional(),
  plan: ServicePlanName.optional(),
  config: z.record(z.unknown()).optional(),
})
```

Source: `minds-ui/apps/api-service/types/service.ts:169`.

### UpdateServiceRequest [#updateservicerequest-1]

```typescript
export type UpdateServiceRequest = z.infer<typeof UpdateServiceRequest>
```

Source: `minds-ui/apps/api-service/types/service.ts:175`.

## 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 }: { params: Promise<{ id: string }> },
) {
  const requestId = generateRequestId()
  let rateLimitInfo: RateLimitMetadata | undefined

  try {
    const authContext = await resolveAuthContext(request)
    const { id } = await params

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

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

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

    const service = await getServiceDetails(authContext, id)

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

Source: `minds-ui/apps/api-service/app/api/v1/services/[id]/route.ts:27`.

### PUT [#put]

```typescript
export async function PUT(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> },
) {
  const requestId = generateRequestId()
  let rateLimitInfo: RateLimitMetadata | undefined

  try {
    const authContext = await resolveAuthContext(request)
    const { id } = await params
    const body = await validateBody(request, UpdateServiceRequest)

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

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

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

    const service = await updateService(authContext, id, body)

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

Source: `minds-ui/apps/api-service/app/api/v1/services/[id]/route.ts:73`.

### DELETE [#delete]

```typescript
export async function DELETE(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> },
) {
  const requestId = generateRequestId()
  let rateLimitInfo: RateLimitMetadata | undefined

  try {
    const authContext = await resolveAuthContext(request)
    const { id } = await params

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

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

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

    const result = await deleteService(authContext, id)

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

Source: `minds-ui/apps/api-service/app/api/v1/services/[id]/route.ts:120`.

## Response and error branches [#response-and-error-branches]

Literal HTTP statuses in the route: 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/services/[id]/route.ts:48`.

```typescript
apiSuccess<ServiceInstance>(service)
```

Source: `minds-ui/apps/api-service/app/api/v1/services/[id]/route.ts:53`.

```typescript
apiError(error, requestId)
```

Source: `minds-ui/apps/api-service/app/api/v1/services/[id]/route.ts:57`.

```typescript
apiError(
      new ApiError(500, 'INTERNAL_ERROR', 'Failed to get service'),
      requestId,
    )
```

Source: `minds-ui/apps/api-service/app/api/v1/services/[id]/route.ts:61`.

```typescript
new ApiError(500, 'INTERNAL_ERROR', 'Failed to get service')
```

Source: `minds-ui/apps/api-service/app/api/v1/services/[id]/route.ts:62`.

```typescript
new RateLimitExceededError(evaluation.retryAfter ?? 60)
```

Source: `minds-ui/apps/api-service/app/api/v1/services/[id]/route.ts:95`.

```typescript
apiSuccess<ServiceInstance>(service)
```

Source: `minds-ui/apps/api-service/app/api/v1/services/[id]/route.ts:100`.

```typescript
apiError(error, requestId)
```

Source: `minds-ui/apps/api-service/app/api/v1/services/[id]/route.ts:104`.

```typescript
apiError(
      new ApiError(500, 'INTERNAL_ERROR', 'Failed to update service'),
      requestId,
    )
```

Source: `minds-ui/apps/api-service/app/api/v1/services/[id]/route.ts:108`.

```typescript
new ApiError(500, 'INTERNAL_ERROR', 'Failed to update service')
```

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

```typescript
new RateLimitExceededError(evaluation.retryAfter ?? 60)
```

Source: `minds-ui/apps/api-service/app/api/v1/services/[id]/route.ts:141`.

```typescript
apiSuccess(result)
```

Source: `minds-ui/apps/api-service/app/api/v1/services/[id]/route.ts:146`.

```typescript
apiError(error, requestId)
```

Source: `minds-ui/apps/api-service/app/api/v1/services/[id]/route.ts:150`.

```typescript
apiError(
      new ApiError(500, 'INTERNAL_ERROR', 'Failed to delete service'),
      requestId,
    )
```

Source: `minds-ui/apps/api-service/app/api/v1/services/[id]/route.ts:154`.

```typescript
new ApiError(500, 'INTERNAL_ERROR', 'Failed to delete service')
```

Source: `minds-ui/apps/api-service/app/api/v1/services/[id]/route.ts:155`.

## Service dependencies [#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/service.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/service-manager.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/services/[id]/route.ts`. SHA-256: `d118dffca0cbef254ef570f6dc5e1305a4ed8e4d90b2c463cfc8f9e0c1e10ff2`.