# Site · Dev environments

Part of AppEngine API Documentation. Full index: https://appengine.appmint.io/documentation.md
## POST /dev-env/create

**Create a development environment**

`operationId: DevEnvironmentController_createDevEnvironment`

Provisions a dev environment — a container running a copy of a site where changes can be made without touching production. Hosting and domains are attached separately after creation.

#### Signature

```http
POST /dev-env/create (body) -> The created environment
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ContentAdmin`, `ConfigAdmin`.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `400` | DEV_ENV_DATA_REQUIRED | Dev environment data is required | The body is empty. | Supply the environment definition. |
| `500` | SPINFORGE_UNCONFIGURED | SPINFORGE_PARTNER_KEY is not configured | The hosting partner key is missing from the server environment. | A deployment configuration problem — not fixable by the caller. |
| `503` | ORG_UNREADABLE | Could not read organization '<orgId>' | The org record could not be read — an infrastructure problem, not a client one. | Retry; escalate if it persists. |

Plus the standard platform errors: `401`, `403`, `429`.

#### See also

- `POST /dev-env/enable-hosting/{envName}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Request body

The environment to create.

```json
{
  "envName": "acme-dev",
  "siteName": "acme-shop"
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The created environment |
| `400` | Dev environment data is required — The body is empty. |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | SPINFORGE_PARTNER_KEY is not configured — The hosting partner key is missing from the server environment. |
| `503` | Could not read organization '<orgId>' — The org record could not be read — an infrastructure problem, not a client one. |

## POST /dev-env/convert/{siteName}

**Convert a site to a development environment**

`operationId: DevEnvironmentController_convertSiteToDevEnv`

Turns an existing site into a dev environment. The site is converted in place rather than copied — the production site becomes the dev environment, so clone it first if it needs to keep serving.

#### Signature

```http
POST /dev-env/convert/{siteName} (siteName: string, body) -> The converted environment
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ContentAdmin`, `ConfigAdmin`.

#### Notes

- Converts in place — clone the site first if production must keep running.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `422` | SITE_NOT_FOUND | Site not found <siteName> | No site with that name exists in the org. Returned as 422, not 404. | List the org's sites with `GET /site/org-sites/{siteOrgId}`. |
| `400` | SITE_NAME_REQUIRED | site name is required | The path segment is empty. | Supply the site name. |

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /site/clone-site`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `siteName` | path | string | yes | Site to convert. |

### Request body

Conversion options.

```json
{
  "envName": "acme-dev"
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The converted environment |
| `400` | site name is required — The path segment is empty. |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `422` | Site not found <siteName> — No site with that name exists in the org. Returned as 422, not 404. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## DELETE /dev-env/{envName}

**Delete a development environment**

`operationId: DevEnvironmentController_deleteDevEnvironment`

Destroys a dev environment and its container. Anything that lives only inside the container — uncommitted work, local data — goes with it.

#### Signature

```http
DELETE /dev-env/{envName} (envName: string) -> The delete result
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ContentAdmin`, `ConfigAdmin`.

#### Notes

- Container-local state is not recoverable afterwards.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /dev-env/create`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `envName` | path | string | yes | Dev environment name. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The delete result |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Dev environment <envName> not found — No dev environment has that name in this org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /dev-env/enable-hosting/{envName}

**Enable hosting for an environment**

`operationId: DevEnvironmentController_enableDevEnvHosting`

Puts a dev environment on the network so it can be reached over HTTP. Until this runs the container exists but serves nothing.

#### Signature

```http
POST /dev-env/enable-hosting/{envName} (envName: string) -> The result
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`). Required role(s): `ContentAdmin`, `ConfigAdmin`.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |
| `500` | SPINFORGE_UNCONFIGURED | SPINFORGE_PARTNER_KEY is not configured | The hosting partner key is missing from the server environment. | A deployment configuration problem — not fixable by the caller. |

Plus the standard platform errors: `401`, `403`, `429`.

#### See also

- `POST /dev-env/attach-domain/{envName}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `envName` | path | string | yes | Dev environment name. |

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The result |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Dev environment <envName> not found — No dev environment has that name in this org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | SPINFORGE_PARTNER_KEY is not configured — The hosting partner key is missing from the server environment. |

## POST /dev-env/attach-domain/{envName}

**Attach a custom domain to an environment**

`operationId: DevEnvironmentController_attachCustomDomainToDevEnv`

Routes a custom hostname to a dev environment. DNS must point at the platform separately — this creates the mapping only.

#### Signature

```http
POST /dev-env/attach-domain/{envName} (envName: string, body) -> The result
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |
| `400` | CUSTOM_DOMAIN_REQUIRED | Custom domain is required | `domain` is missing. | Supply the hostname. |

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /dev-env/detach-domain/{envName}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `envName` | path | string | yes | Dev environment name. |

### Request body

The domain.

```json
{
  "domain": "dev.example.com"
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The result |
| `400` | Custom domain is required — `domain` is missing. |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Dev environment <envName> not found — No dev environment has that name in this org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /dev-env/detach-domain/{envName}

**Detach a custom domain from an environment**

`operationId: DevEnvironmentController_detachCustomDomainFromDevEnv`

Removes a custom hostname from a dev environment; the environment stays reachable on its container domain.

#### Signature

```http
POST /dev-env/detach-domain/{envName} (envName: string, body) -> The result
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |
| `400` | CUSTOM_DOMAIN_REQUIRED | Custom domain is required | `domain` is missing. | Supply the hostname. |

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /dev-env/attach-domain/{envName}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `envName` | path | string | yes | Dev environment name. |

### Request body

The domain to detach.

```json
{
  "domain": "dev.example.com"
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The result |
| `400` | Custom domain is required — `domain` is missing. |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Dev environment <envName> not found — No dev environment has that name in this org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /dev-env/get/{envName}

**Get a development environment**

`operationId: DevEnvironmentController_getDevEnv`

Fetches one environment with its configuration and hosting state.

#### Signature

```http
GET /dev-env/get/{envName} (envName: string) -> The environment
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |
| `503` | DEV_ENVS_UNREADABLE | Could not read dev environments for organization '<orgId>' | The org's environments could not be read. | Retry; escalate if it persists. |

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /dev-env/{envName}/status`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `envName` | path | string | yes | Dev environment name. |

### Request body

Custom domain details

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The environment |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Dev environment <envName> not found — No dev environment has that name in this org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |
| `503` | Could not read dev environments for organization '<orgId>' — The org's environments could not be read. |

## GET /dev-env/get-spinforge/{devEnvName}

**Get SpinForge details for an environment**

`operationId: DevEnvironmentController_getDevEnvsAndUser`

Returns the environment along with the hosting-partner (SpinForge) session detail a client needs to open it. Requires the partner key to be configured server-side.

#### Signature

```http
GET /dev-env/get-spinforge/{devEnvName} (devEnvName: string) -> The environment and hosting session detail
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `400` | DEV_ENV_NAME_REQUIRED | devEnvName path parameter is required | The path segment is empty. | Supply the environment name. |
| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |
| `500` | SPINFORGE_UNCONFIGURED | SPINFORGE_PARTNER_KEY is not configured | The hosting partner key is missing from the server environment. | A deployment configuration problem — not fixable by the caller. |
| `502` | SPINFORGE_NO_TOKEN | SpinForge partner auth returned no token | The hosting partner authenticated but issued no token. | An upstream failure — retry, then escalate. |

Plus the standard platform errors: `401`, `403`, `429`.

#### See also

- `POST /dev-env/send-session-invitation`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `devEnvName` | path | string | yes | Dev environment name. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The environment and hosting session detail |
| `400` | devEnvName path parameter is required — The path segment is empty. |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Dev environment <envName> not found — No dev environment has that name in this org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | SPINFORGE_PARTNER_KEY is not configured — The hosting partner key is missing from the server environment. |
| `502` | SpinForge partner auth returned no token — The hosting partner authenticated but issued no token. |

## GET /dev-env/{envName}/status

**Get container status**

`operationId: DevEnvironmentController_getContainerStatus`

Whether the environment's container is running, and its current state.

#### Signature

```http
GET /dev-env/{envName}/status (envName: string) -> The container status
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /dev-env/{envName}/logs`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `envName` | path | string | yes | Dev environment name. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The container status |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Dev environment <envName> not found — No dev environment has that name in this org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /dev-env/{envName}/logs

**Get container logs**

`operationId: DevEnvironmentController_getContainerLogs`

Recent log output from the environment's container — the first place to look when a dev environment misbehaves. Logs can carry whatever the running application printed, so treat the output as potentially sensitive.

#### Signature

```http
GET /dev-env/{envName}/logs (envName: string) -> The container logs
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Log content is not filtered.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /dev-env/{envName}/status`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `envName` | path | string | yes | Dev environment name. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The container logs |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Dev environment <envName> not found — No dev environment has that name in this org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /dev-env/{envName}/start

**Start a container**

`operationId: DevEnvironmentController_startContainer`

Starts the environment's container.

#### Signature

```http
POST /dev-env/{envName}/start (envName: string) -> The result
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /dev-env/{envName}/stop`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `envName` | path | string | yes | Dev environment name. |

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The result |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Dev environment <envName> not found — No dev environment has that name in this org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /dev-env/{envName}/stop

**Stop a container**

`operationId: DevEnvironmentController_stopContainer`

Stops the environment's container. Anyone using the environment loses it immediately, and it stops serving on its domains.

#### Signature

```http
POST /dev-env/{envName}/stop (envName: string) -> The result
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Takes the environment offline.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /dev-env/{envName}/start`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `envName` | path | string | yes | Dev environment name. |

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The result |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Dev environment <envName> not found — No dev environment has that name in this org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /dev-env/{envName}/restart

**Restart a container**

`operationId: DevEnvironmentController_restartContainer`

Stops and starts the container. Brief downtime, and in-container process state is lost — the filesystem is kept.

#### Signature

```http
POST /dev-env/{envName}/restart (envName: string) -> The result
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /dev-env/{envName}/rebuild`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `envName` | path | string | yes | Dev environment name. |

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The result |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Dev environment <envName> not found — No dev environment has that name in this org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /dev-env/{envName}/rebuild

**Rebuild a container**

`operationId: DevEnvironmentController_rebuildContainer`

Rebuilds the container image and replaces the running container. Heavier than a restart: anything written inside the container that is not part of the image or a mounted volume does not survive.

#### Signature

```http
POST /dev-env/{envName}/rebuild (envName: string) -> The result
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Discards container-local filesystem changes.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `404` | DEV_ENV_NOT_FOUND | Dev environment <envName> not found | No dev environment has that name in this org. | Check the name with `GET /dev-env/get/{envName}`. |

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /dev-env/{envName}/restart`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `envName` | path | string | yes | Dev environment name. |

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The result |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Dev environment <envName> not found — No dev environment has that name in this org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /dev-env/send-session-invitation

**Send a session invitation**

`operationId: DevEnvironmentController_sendSessionInvitation`

Emails someone an invitation to join a dev-environment session. This sends real mail to the address given — check it before calling.

#### Signature

```http
POST /dev-env/send-session-invitation (body) -> The send result
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Sends an email — outward-facing.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `400` | EMAIL_REQUIRED | Email is required | `email` is missing. | Supply the recipient address. |

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /dev-env/get-spinforge/{devEnvName}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Request body

Who to invite.

```json
{
  "email": "dev@example.com",
  "envName": "acme-dev"
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The send result |
| `400` | Email is required — `email` is missing. |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |