Applications API

Applications are containerized services that run in your environments. They can be web servers, APIs, databases, or any containerized workload.

Available Endpoints

Method	Endpoint	Description
POST	/environments/{envId}/app	Create a new application
GET	/environments/{envId}/app/{id}	Get application details
GET	/environments/{envId}/app	List applications in environment
GET	/apps	List all applications across environments
PUT	/environments/{envId}/app/{id}	Update application configuration
PATCH	/environments/{envId}/app/{id}/image	Update only application image
DELETE	/environments/{envId}/app/{id}	Delete an application
GET	/environments/{envId}/app/{id}/history	Get application history
POST	/environments/{envId}/app/{id}/restore	Restore previous version
GET	/hostname/generate	Generate unique hostname

Application Object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "my-web-app",
  "envIdRef": "660e8400-e29b-41d4-a716-446655440001",
  "companyIdRef": "770e8400-e29b-41d4-a716-446655440002",
  "source": {
    "image": {
      "name": "nginx",
      "tag": "latest"
    }
  },
  "resources": {
    "cpu": 1000,
    "memory": 512,
    "storage": 10240
  },
  "hostname": "my-web-app-abc123",
  "port": 80,
  "environmentVariables": {
    "NODE_ENV": "production",
    "API_URL": "https://api.example.com"
  },
  "volumes": ["vol-123", "vol-456"],
  "variableSets": ["varset-123"],
  "files": ["file-123"],
  "isDeleted": false,
  "createdBy": "user-123",
  "modifiedBy": "user-123",
  "version": 1
}

Fields

Field	Type	Description
id	string (UUID)	Unique application identifier
name	string	Application name
envIdRef	string (UUID)	Parent environment ID
companyIdRef	string (UUID)	Owner company ID
source.image.name	string	Docker image name
source.image.tag	string	Docker image tag
resources.cpu	integer	CPU allocation in millicores (1000 = 1 core)
resources.memory	integer	Memory allocation in MB
resources.storage	integer	Storage allocation in MB
hostname	string	Unique hostname for the application
port	integer	Application port (1-65535)
environmentVariables	object	Environment variables as key-value pairs
volumes	array	Array of attached volume IDs
variableSets	array	Array of attached variable set IDs
files	array	Array of attached file IDs
isDeleted	boolean	Soft delete flag
createdBy	string	User ID who created the application
modifiedBy	string	User ID who last modified the application
version	integer	Version number for tracking changes

Authentication

All application endpoints require authentication via:

• Session Cookie: For web application access
• API Token: Bearer token with 2FA enabled

Quick Start Example

# Set your credentials
export API_TOKEN="tvn_your_api_token_here"
export ENV_ID="your-environment-id"
export BASE_URL="https://api.thevenin.cloud"

# Create an application
curl -X POST "$BASE_URL/environments/$ENV_ID/app" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-web-app",
    "source": {
      "image": {
        "name": "nginx",
        "tag": "alpine"
      }
    },
    "resources": {
      "cpu": 500,
      "memory": 256,
      "storage": 5120
    },
    "port": 80
  }'

# Get the application
APP_ID="your-app-id"
curl -X GET "$BASE_URL/environments/$ENV_ID/app/$APP_ID" \
  -H "Authorization: Bearer $API_TOKEN"

# Update the image
curl -X PATCH "$BASE_URL/environments/$ENV_ID/app/$APP_ID/image" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "imageName": "nginx",
    "imageTag": "latest"
  }'

# List all applications
curl -X GET "$BASE_URL/environments/$ENV_ID/app" \
  -H "Authorization: Bearer $API_TOKEN"

Version History

All application changes are tracked:

• Every update increments the version number
• History includes all previous configurations
• Restore previous versions via restore endpoint
• Useful for rollbacks and auditing

Hostname Generation

Each application gets a unique hostname:

• Format: {app-name}-{random-string}
• Used for routing and DNS
• Can be generated before creating application
• Automatically assigned if not provided

Notes

• Applications are scoped to environments
• Deleting an application is a soft delete (can be restored)
• Attached resources (volumes, files) are not deleted with application
• Resource allocation is validated against environment quotas
• Image updates trigger redeployment
• Environment variable changes may require restart

Next Steps

• Create Application - Deploy your first application
• Update Application Image - Update to new versions
• Environments API - Learn about environments
• Volumes API - Add persistent storage