Environments API

The Environment Service provides methods for creating, managing, and monitoring environments.

Service Definition

service EnvironmentService {
  rpc CreateEnvironment(CreateEnvironmentRequest) returns (Environment);
  rpc GetEnvironment(GetEnvironmentRequest) returns (Environment);
  rpc ListEnvironments(ListEnvironmentsRequest) returns (ListEnvironmentsResponse);
  rpc UpdateEnvironment(UpdateEnvironmentRequest) returns (Environment);
  rpc DeleteEnvironment(DeleteEnvironmentRequest) returns (google.protobuf.Empty);
  rpc StartEnvironment(StartEnvironmentRequest) returns (Environment);
  rpc StopEnvironment(StopEnvironmentRequest) returns (Environment);
  rpc WatchEnvironment(WatchEnvironmentRequest) returns (stream EnvironmentEvent);
}

CreateEnvironment

Create a new environment from a blueprint.

Request

message CreateEnvironmentRequest {
  string name = 1;                    // Environment name
  string blueprint_id = 2;            // Blueprint to instantiate
  string project_id = 3;              // Target project
  map<string, string> variables = 4;  // Blueprint variable values
  Duration ttl = 5;                   // Time to live (optional)
}

Example

curl -X POST 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "my-workshop",
    "blueprintId": "bp_gitlab-cicd",
    "projectId": "proj_training",
    "variables": {
      "participant_count": "10",
      "region": "eu-central"
    },
    "ttl": "48h"
  }' 
  https://api.teabar.dev/teabar.v1.EnvironmentService/CreateEnvironment

Response

{
  "id": "env_abc123",
  "name": "my-workshop",
  "status": "PROVISIONING",
  "blueprintId": "bp_gitlab-cicd",
  "projectId": "proj_training",
  "createdAt": "2024-03-10T14:30:00Z",
  "ttl": "48h",
  "expiresAt": "2024-03-12T14:30:00Z"
}

GetEnvironment

Retrieve details of a specific environment.

Request

message GetEnvironmentRequest {
  string environment_id = 1;
}

Example

curl -X POST 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"environmentId": "env_abc123"}' 
  https://api.teabar.dev/teabar.v1.EnvironmentService/GetEnvironment

Response

{
  "id": "env_abc123",
  "name": "my-workshop",
  "status": "RUNNING",
  "blueprintId": "bp_gitlab-cicd",
  "projectId": "proj_training",
  "createdAt": "2024-03-10T14:30:00Z",
  "startedAt": "2024-03-10T14:35:00Z",
  "resources": {
    "pods": 15,
    "services": 8,
    "pvcs": 3
  },
  "endpoints": [
    {
      "name": "gitlab",
      "url": "https://gitlab.my-workshop.acme.teabar.dev"
    },
    {
      "name": "argocd",
      "url": "https://argocd.my-workshop.acme.teabar.dev"
    }
  ],
  "metrics": {
    "cpuUsage": 2.5,
    "memoryUsageGb": 8.2,
    "storageUsageGb": 45.0
  }
}

ListEnvironments

List environments with optional filtering.

Request

message ListEnvironmentsRequest {
  string project_id = 1;              // Filter by project (optional)
  string status = 2;                  // Filter by status (optional)
  int32 page_size = 3;                // Results per page
  string page_token = 4;              // Pagination token
}

Example

curl -X POST 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "projectId": "proj_training",
    "status": "RUNNING",
    "pageSize": 20
  }' 
  https://api.teabar.dev/teabar.v1.EnvironmentService/ListEnvironments

Response

{
  "environments": [
    {
      "id": "env_abc123",
      "name": "workshop-march",
      "status": "RUNNING",
      "createdAt": "2024-03-10T14:30:00Z"
    },
    {
      "id": "env_def456",
      "name": "workshop-april",
      "status": "RUNNING",
      "createdAt": "2024-03-15T09:00:00Z"
    }
  ],
  "nextPageToken": "cursor_xyz789",
  "totalCount": 45
}

StartEnvironment

Start a stopped or sleeping environment.

Request

message StartEnvironmentRequest {
  string environment_id = 1;
}

Example

curl -X POST 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"environmentId": "env_abc123"}' 
  https://api.teabar.dev/teabar.v1.EnvironmentService/StartEnvironment

StopEnvironment

Stop a running environment.

Request

message StopEnvironmentRequest {
  string environment_id = 1;
  bool hibernate = 2;         // True for deep sleep (save state)
}

Example

curl -X POST 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"environmentId": "env_abc123", "hibernate": false}' 
  https://api.teabar.dev/teabar.v1.EnvironmentService/StopEnvironment

DeleteEnvironment

Permanently delete an environment.

Request

message DeleteEnvironmentRequest {
  string environment_id = 1;
  bool force = 2;              // Force delete running environment
}

Example

curl -X POST 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"environmentId": "env_abc123", "force": true}' 
  https://api.teabar.dev/teabar.v1.EnvironmentService/DeleteEnvironment

WatchEnvironment

Stream real-time updates for an environment.

Request

message WatchEnvironmentRequest {
  string environment_id = 1;
}

Response Stream

message EnvironmentEvent {
  string event_type = 1;       // status_changed, resource_updated, log
  Environment environment = 2;
  Timestamp timestamp = 3;
}

Example (TypeScript)

const stream = client.watchEnvironment({ environmentId: "env_abc123" });

for await (const event of stream) {
  console.log(`Event: ${event.eventType}`);
  console.log(`Status: ${event.environment.status}`);
}

Environment Status Values

Error Codes

See Also

• Blueprints API - Blueprint management
• CLI env Commands - CLI environment operations
• Environments Concept - Understanding environments