/api/v1/instances (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, GET
Path	`/api/v1/instances`
Path parameters	None
Query parameters read in route	`tenant_id`
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.

CreateInstanceRequest

export interface CreateInstanceRequest {
  tenantId: string;
  instanceType: InstanceType;
  tierName: string; // "Starter", "Professional", etc.
  name?: string;
  region?: string;
  tags?: Record<string, string>;
}

Source: minds-ui/apps/api-service/lib/services/instance-provisioning-service.ts:29.

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.

POST

export async function POST(request: NextRequest) {
  try {
    const authContext = await resolveAuthContext(request, {
      allowApiKey: true,
      allowSession: true,
    });

    const body = await request.json();

    // Validate required fields
    if (!body.tenantId) {
      throw new InvalidRequestError('tenantId required');
    }

    if (!body.instanceType) {
      throw new InvalidRequestError('instanceType required');
    }

    if (!body.tier) {
      throw new InvalidRequestError('tier required');
    }

    // Verify tenant access
    const tenant = await prisma.tenant.findUnique({
      where: { id: body.tenantId },
    });

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

    await ensureTenantAccess(authContext, tenant.orgId, tenant.ownerId, {
      action: 'instance:create',
      tenantId: tenant.id,
      resourceId: tenant.id,
    });

    const createRequest: CreateInstanceRequest = {
      tenantId: body.tenantId,
      instanceType: body.instanceType as InstanceType,
      tierName: body.tier,
      name: body.name,
      region: body.region,
      tags: body.tags,
    };

    const result = await instanceProvisioningService.createInstance(
      createRequest,
      authContext.userId
    );

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

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

Source: minds-ui/apps/api-service/app/api/v1/instances/route.ts:14.

GET

export async function GET(request: NextRequest) {
  try {
    const authContext = await resolveAuthContext(request, {
      allowApiKey: true,
      allowSession: true,
    });

    const url = new URL(request.url);
    const tenantId = url.searchParams.get('tenant_id');

    if (!tenantId) {
      return NextResponse.json({ error: 'tenant_id query parameter required' }, { status: 400 });
    }

    // Verify tenant access
    const tenant = await prisma.tenant.findUnique({
      where: { id: tenantId },
    });

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

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

    // Get instances for the tenant
    const instances = await prisma.serviceInstance.findMany({
      where: { tenantId },
      include: {
        serviceType: true,
      },
    });

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

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

Source: minds-ui/apps/api-service/app/api/v1/instances/route.ts:84.

Response and error branches

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

request.json()

Source: minds-ui/apps/api-service/app/api/v1/instances/route.ts:21.

new InvalidRequestError('tenantId required')

Source: minds-ui/apps/api-service/app/api/v1/instances/route.ts:25.

new InvalidRequestError('instanceType required')

Source: minds-ui/apps/api-service/app/api/v1/instances/route.ts:29.

new InvalidRequestError('tier required')

Source: minds-ui/apps/api-service/app/api/v1/instances/route.ts:33.

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

Source: minds-ui/apps/api-service/app/api/v1/instances/route.ts:42.

NextResponse.json(result, { status: 201 })

Source: minds-ui/apps/api-service/app/api/v1/instances/route.ts:65.

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

Source: minds-ui/apps/api-service/app/api/v1/instances/route.ts:68.

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

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

NextResponse.json({ error: 'tenant_id query parameter required' }, { status: 400 })

Source: minds-ui/apps/api-service/app/api/v1/instances/route.ts:95.

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

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

NextResponse.json(instances)

Source: minds-ui/apps/api-service/app/api/v1/instances/route.ts:121.

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

Source: minds-ui/apps/api-service/app/api/v1/instances/route.ts:124.

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

Source: minds-ui/apps/api-service/app/api/v1/instances/route.ts:131.

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/route.ts. SHA-256: 800e96ec9a25ee72ee02f89e0a24d4dfb5b2f3bdf5425feb2aca5a612fd14fb3.

/api/v1/instances (management)

On this page