/api/v1/instances/[instanceId] (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, DELETE
Path	`/api/v1/instances/[instanceId]`
Path parameters	`instanceId`
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.

GET

export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ instanceId: string }> }
) {
  try {
    const authContext = await resolveAuthContext(request, {
      allowApiKey: true,
      allowSession: true,
    });

    const { instanceId } = await params;

    // Get instance with tenant info
    const instance = await prisma.serviceInstance.findUnique({
      where: { id: instanceId },
      include: { tenant: true },
    });

    if (!instance || !instance.tenant) {
      return NextResponse.json({ error: 'Instance not found' }, { status: 404 });
    }

    // Ensure tenant access
    await ensureTenantAccess(
      authContext,
      instance.tenant.orgId,
      instance.tenant.ownerId,
      {
        action: 'instance:read',
        tenantId: instance.tenantId ?? undefined,
        resourceId: instance.id,
      }
    );

    return NextResponse.json(instance);
  } catch (error) {
    if (error instanceof ApiError) {
      return NextResponse.json(
        { error: error.message },
        { status: error.statusCode }
      );
    }

    console.error('[API] Error getting instance:', error);
    return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
  }
}

Source: minds-ui/apps/api-service/app/api/v1/instances/[instanceId]/route.ts:13.

DELETE

export async function DELETE(
  request: NextRequest,
  { params }: { params: Promise<{ instanceId: string }> }
) {
  try {
    const authContext = await resolveAuthContext(request, {
      allowApiKey: true,
      allowSession: true,
    });

    const { instanceId } = await params;

    // Get instance with tenant info
    const instance = await prisma.serviceInstance.findUnique({
      where: { id: instanceId },
      include: { tenant: true },
    });

    if (!instance || !instance.tenant) {
      return NextResponse.json({ error: 'Instance not found' }, { status: 404 });
    }

    // Ensure tenant access
    await ensureTenantAccess(
      authContext,
      instance.tenant.orgId,
      instance.tenant.ownerId,
      {
        action: 'instance:delete',
        tenantId: instance.tenantId ?? undefined,
        resourceId: instance.id,
      }
    );

    // Delete instance
    await instanceProvisioningService.deleteInstance(instanceId);

    return NextResponse.json({ message: 'Instance deleted successfully' });
  } catch (error) {
    if (error instanceof ApiError) {
      return NextResponse.json(
        { error: error.message },
        { status: error.statusCode }
      );
    }

    console.error('[API] Error deleting instance:', error);
    return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
  }
}

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

Response and error branches

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

NextResponse.json({ error: 'Instance not found' }, { status: 404 })

Source: minds-ui/apps/api-service/app/api/v1/instances/[instanceId]/route.ts:32.

NextResponse.json(instance)

Source: minds-ui/apps/api-service/app/api/v1/instances/[instanceId]/route.ts:47.

NextResponse.json(
        { error: error.message },
        { status: error.statusCode }
      )

Source: minds-ui/apps/api-service/app/api/v1/instances/[instanceId]/route.ts:50.

NextResponse.json({ error: 'Internal server error' }, { status: 500 })

Source: minds-ui/apps/api-service/app/api/v1/instances/[instanceId]/route.ts:57.

NextResponse.json({ error: 'Instance not found' }, { status: 404 })

Source: minds-ui/apps/api-service/app/api/v1/instances/[instanceId]/route.ts:86.

NextResponse.json({ message: 'Instance deleted successfully' })

Source: minds-ui/apps/api-service/app/api/v1/instances/[instanceId]/route.ts:104.

NextResponse.json(
        { error: error.message },
        { status: error.statusCode }
      )

Source: minds-ui/apps/api-service/app/api/v1/instances/[instanceId]/route.ts:107.

NextResponse.json({ error: 'Internal server error' }, { status: 500 })

Source: minds-ui/apps/api-service/app/api/v1/instances/[instanceId]/route.ts:114.

Service dependencies

minds-ui/apps/api-service/lib/services/auth-context.ts
minds-ui/apps/api-service/lib/services/instance-provisioning-service.ts
minds-ui/apps/api-service/types/errors.ts
minds-ui/apps/api-service/lib/db.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/instances/[instanceId]/route.ts. SHA-256: dcbe789903adc0de5e951b4f09c3f27f593410cd5a59cfdffae8df80eaaa405d.