Environments

This guide explains how to view Environments, inspect metrics, and delete an Environment.

Why this matters

• An Environment represents a running agent or a logical grouping deployed behind a Frontdoor.
• Metrics let you understand traffic, error rates, and capacity per environment.
• Deletion removes the environment, along with any shares hosted on it, the Frontdoor Agent would have to be enrolled again to bring it back.

Assumptions

• The examples assume you have a valid Bearer token. If you need help obtaining a token, see [./auth](Auth Guide).
• Base URL for all API calls is https://gateway.production.netfoundry.io/frontdoor
• Expected headers for all API calls:

- Authorization: Bearer YOUR_ACCESS_TOKEN
- Accept: application/hal+json or application/json

Operations

List environments

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  "https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/environments?page=0&size=20"

Response example

{
  "content": [
    {"id": "env-1", "name": "dev", "status": "ACTIVE"},
    {"id": "env-2", "name": "prod", "status": "ACTIVE"}
  ],
  "pageable": {"pageNumber": 0, "pageSize": 20}
}

Get an environment by ID

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/environments/env-1

Response example

{
  "id": "env-1",
  "name": "dev",
  "status": "ACTIVE",
  "createdAt": "2025-07-10T09:30:00Z"
}

Delete an environment

Request example

curl -s -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/environments/env-1

The delete request has an empty response.

Technical Notes

Metrics

All environments track data metrics, see Metrics for more information.

Paths

- GET /frontdoor/\{frontdoorId\}/environments[?page=0&size=20]
- GET /frontdoor/\{frontdoorId\}/environments/{id}
- GET /frontdoor/\{frontdoorId\}/environments/{id}/metrics?duration=PT1H
- GET /frontdoor/\{frontdoorId\}/metrics?duration=PT1H
- DELETE /frontdoor/\{frontdoorId\}/environments/{id}

Common errors

400 Bad Request (client error)

{
  "error": "invalid_request",
  "message": "Value for <property> must be of <type>"
}

Possible reasons include:

• Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
• Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

401 Unauthorized (missing/expired token)

{
  "error": "unauthorized",
  "message": "Bearer token is missing or invalid"
}

Possible reasons include:

• Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
• Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

403 Forbidden (not_authorized)

{
  "error": "not_found",
  "message": "Frontdoor 3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c not found"
}

Possible reasons include:

• Invalid token: The token is not valid.
• The token does not grant access to the requested resource.
• Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
• Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.