The Beta Enrollment API allows you to enable the managed-resources beta (Managed VPS and Static Hosting) for your account programmatically. This is used by the DeployHQ CLI (`dhq launch`) to enable the beta before provisioning managed infrastructure.

**Tip**: You can explore and test this endpoint interactively using our [OpenAPI documentation](https://api.deployhq.com/docs).

## Authorization

Beta enrollment requires an account administrator only when the beta is not yet enabled on the account. If the account already has the beta enabled, any authenticated member can call this endpoint successfully (idempotent).

| Caller | Account not enrolled | Account enrolled |
|--------|---------------------|------------------|
| Account administrator | Enrolls and returns success | Returns success (no-op) |
| Non-admin member | Returns 403 with `admin_required` | Returns success (no-op) |

## Enroll in beta

### URL

```
/beta/enrollments
```

### HTTP Method

```
POST
```

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| protocol | String | No | The protocol you intend to use: `static_hosting` or `managed_vps`. Defaults to `managed_vps` if omitted. |

### Example cURL request

```
curl -X POST \
-H "Content-type: application/json" \
-H "Accept: application/json" \
--user adam@atechmedia.com:my-api-key \
-d '{"protocol": "static_hosting"}' \
https://test.deployhq.com/beta/enrollments
```

### Success response (200)

```json
{
  "enrolled": true,
  "beta_features": true
}
```

### Admin required response (403)

Returned when the account does not have the beta enabled and the authenticated user is not an account administrator.

```json
{
  "error": "admin_required",
  "message": "Only the account administrator can enable beta features. Ask your administrator or visit the beta features page.",
  "beta_url": "https://test.deployhq.com/beta_features"
}
```

Use `beta_url` to deep-link the user to the beta features page where an administrator can enable it manually.

### Unsupported protocol response (422)

```json
{
  "error": "unsupported_protocol",
  "message": "Protocol 'ftp' is not supported. Supported protocols: static_hosting, managed_vps."
}
```

## Checking beta and capability status

To check whether the managed-resources beta is currently enabled before attempting enrollment, use the profile endpoint which is readable by all authenticated account members:

```
GET /profile
```

The response includes an `account` object with capability flags:

```json
{
  "first_name": "Jane",
  "last_name": "Developer",
  "email_address": "jane@example.com",
  "account": {
    "name": "My Company",
    "permalink": "my-company",
    "beta_features": false,
    "static_hosting_eligible": false,
    "managed_vps_eligible": false
  }
}
```

When `beta_features` is `false`, use the enrollment endpoint to enable it. Both `static_hosting_eligible` and `managed_vps_eligible` mirror `beta_features` for now and indicate whether the respective managed protocol can be provisioned.

## Polling provisioning state

Once a managed server is created (`POST /projects/:id/servers`), poll its provisioning state using the project-scoped server show endpoint:

```
GET /projects/:project_id/servers/:id
```

For static hosting servers the response includes a `static_hosting` block:

```json
{
  "identifier": "abc123",
  "name": "my-site",
  "protocol_type": "static_hosting",
  "static_hosting": {
    "hosted_website_identifier": "xyz789",
    "subdomain": "my-site",
    "url": "https://my-site.deployhq-sites.com",
    "spa_mode": false,
    "status": "provisioning",
    "active_deployment_uuid": null
  }
}
```

For Managed VPS servers the response includes a `managed_vps` block:

```json
{
  "identifier": "def456",
  "name": "web-server",
  "protocol_type": "managed_vps",
  "managed_vps": {
    "hosted_resource_identifier": "ghi012",
    "status": "provisioning",
    "ip_address": null,
    "region": "lon1",
    "size": "s-1vcpu-1gb"
  }
}
```

Poll until `status` is `active`. Possible values are `provisioning`, `active`, `suspended`, `disabled`, `error`, and `destroying`.