# Management resource workflows

Work with tenants, services, instances, backups, and region records without confusing resource IDs or lifecycle states.

Source: https://docs.minds.sh/docs/api/platform/management



The management service exposes resources used to operate deployed Minds. It is a separate application from the signed-in dashboard. Set `MINDS_MANAGEMENT_URL` to the origin supplied for your deployment and use its configured authentication.

## Tenants [#tenants]

A tenant is the management record that owns an instance's endpoint, plan, region, configuration, and lifecycle. An organization ID scopes access; it is not interchangeable with the tenant ID.

| Task                    | Method and path                   | Result                                                                                                            |
| ----------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| List accessible records | `GET /api/v1/tenants`             | Validated list response; query fields include organization, filters, and pagination defined by `ListTenantsQuery` |
| Create                  | `POST /api/v1/tenants`            | 202 accepted with `CreateTenantResponse`; provisioning can still be in progress                                   |
| Read                    | `GET /api/v1/tenants/[id]`        | Tenant record                                                                                                     |
| Change configuration    | `PATCH /api/v1/tenants/[id]`      | Updated record following schema validation                                                                        |
| Inspect state           | `GET /api/v1/tenants/[id]/status` | Status and health response                                                                                        |
| Request scaling         | `POST /api/v1/tenants/[id]/scale` | Deployment-specific scaling operation                                                                             |
| Remove                  | `DELETE /api/v1/tenants/[id]`     | Deletion operation; inspect its endpoint response and retention behavior before use                               |

A management create request requires `org_id`, `name`, and `plan`. The schema also accepts optional `project_id`, `slug`, `region`, `config`, `service_type`, `bundle`, and `service_config`.

```json
{
  "org_id": "<accessible-organization-id>",
  "name": "Research memory",
  "plan": "free",
  "region": "<region-returned-by-your-catalog>"
}
```

Use [the tenant endpoint contract](/docs/api/platform/reference/management--api-v1-tenants) for all required fields, default values, and result types. Older schema enum values such as `starter` and legacy storage fields remain visible in the reference for compatibility; they are not current packaging recommendations.

## Services and instances [#services-and-instances]

A service record represents a provisioned service type. An instance is the running deployment to which services may be bound. Keep their IDs separate.

* `/api/v1/services`: list or create service records.
* `/api/v1/services/[id]`: read, update with PUT, or delete a service.
* `/api/v1/services/[id]/bind`: bind a service to an instance.
* `/api/v1/services/[id]/status`: read service status.
* `/api/v1/instances`: create an instance or list by required `tenant_id` query.
* `/api/v1/instances/[instanceId]`: inspect or delete an instance.
* `/api/v1/instances/[instanceId]/services/{enable,disable,status}`: control or inspect enabled services.
* `/api/v1/tenants/[id]/services/{enable,disable}`: tenant-scoped service controls.
* `/api/v1/bundles/expand`: resolve a bundle definition into its configured service selection.

The instance-create route uses `tenantId`, `instanceType`, and `tier` in its JSON body. This differs from the snake-case tenant-create contract. The list-instances route returns a raw array; do not assume every list has a `{data:...}` wrapper.

## Backups and restore [#backups-and-restore]

List existing backups before making a recovery decision:

```bash
curl --fail-with-body \
  --header "x-api-key: $MINDS_MANAGEMENT_API_KEY" \
  "$MINDS_MANAGEMENT_URL/api/v1/tenants/$MINDS_TENANT_ID/backups"
```

POST to that collection requests a backup and returns 202. Restore uses `POST /api/v1/tenants/[id]/backups/[backupId]/restore`; deleting a backup uses DELETE on its resource path. A queued backup or restore is not a completed recovery. Inspect the returned operation and later state before depending on it.

The complete backup request and response schemas appear in [Schema reference](/docs/api/platform/schemas). These management backups are different from local engine backup commands and HMR recovery-material confirmation.

## Region catalog and health [#region-catalog-and-health]

Read regions through `/api/v1/regions`; use `/api/v1/regions/select` to apply the deployment's selection logic. Region resources also expose read/update/delete and health-check routes. Region mutations are operational administration, not a customer provisioning shortcut.

Current region-health source derives several booleans from stored region status. The dashboard may additionally return a catalog fallback. Do not treat these flags as proof of a live Kubernetes, ingress, or certificate probe. See [proxy behavior](/docs/api/platform/proxies).

## Complete contracts [#complete-contracts]

The [endpoint catalog](/docs/api/platform/endpoints) includes all management routes, auth resolution, request schemas, status branches, and helper dependencies. Read [Errors and responses](/docs/api/platform/errors) for retry and asynchronous-operation handling.