Configs

Configs store application configuration as key-value pairs. Your services can access config values as environment variables.

Config Endpoints

Method	Endpoint	Description
GET	/api/configs/	List all your configs
POST	/api/configs/	Create a new config
GET	/api/configs/{id}/	Get config details
PATCH	/api/configs/{id}/	Update a config
DELETE	/api/configs/{id}/	Delete a config

Config Item Endpoints

Method	Endpoint	Description
GET	/api/configs/{config_id}/items/	List config items
POST	/api/configs/{config_id}/items/	Add a config item
GET	/api/configs/{config_id}/items/{id}/	Get a config item
PATCH	/api/configs/{config_id}/items/{id}/	Update a config item
DELETE	/api/configs/{config_id}/items/{id}/	Delete a config item

Config Object

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "production-config",
  "is_default": false,
  "status": "ready",
  "deploy_successful": true,
  "created_at": "2024-10-15T10:00:00Z"
}

Fields

Field	Type	Description
id	UUID	Unique identifier (read-only)
name	string	Config name
is_default	boolean	Whether this is the default config (read-only)
status	string	Current status (read-only)
deploy_successful	boolean	Whether synced successfully (read-only)

Config Item Object

{
  "id": "abc123...",
  "config": "config-uuid",
  "key": "DATABASE_URL",
  "value": "postgresql://localhost/mydb",
  "created_at": "2024-10-15T10:00:00Z",
  "updated_at": "2024-10-15T12:00:00Z"
}

Fields

Field	Type	Description
id	UUID	Unique identifier (read-only)
config	UUID	Parent config ID (read-only)
key	string	Configuration key name
value	string	Configuration value

List Configs

GET /api/configs/

Example:

curl -H "Authorization: Bearer gob_your_key" \
  https://api.example.com/api/configs/

Response:

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "abc123...",
      "name": "Default",
      "is_default": true,
      "status": "ready"
    },
    {
      "id": "def456...",
      "name": "production-config",
      "is_default": false,
      "status": "ready"
    }
  ]
}

Create Config

POST /api/configs/

Request Body:

{
  "name": "production-config"
}

Example:

curl -X POST https://api.example.com/api/configs/ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "production-config"}'

Delete Config

DELETE /api/configs/{id}/

Restrictions

• Default configs cannot be deleted - Every account has a default config that cannot be removed
• Configs in use cannot be deleted - Remove the config from all services first

List Config Items

GET /api/configs/{config_id}/items/

Example:

curl -H "Authorization: Bearer gob_your_key" \
  https://api.example.com/api/configs/abc123.../items/

Response:

{
  "count": 3,
  "results": [
    {
      "id": "item1...",
      "key": "DATABASE_URL",
      "value": "postgresql://localhost/mydb"
    },
    {
      "id": "item2...",
      "key": "API_ENDPOINT",
      "value": "https://api.example.com"
    }
  ]
}

Add Config Item

POST /api/configs/{config_id}/items/

Request Body:

{
  "key": "DATABASE_URL",
  "value": "postgresql://localhost/mydb"
}

Example:

curl -X POST https://api.example.com/api/configs/abc123.../items/ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "API_ENDPOINT",
    "value": "https://api.production.com"
  }'

Update Config Item

PATCH /api/configs/{config_id}/items/{id}/

Example:

curl -X PATCH https://api.example.com/api/configs/abc123.../items/item1.../ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{"value": "postgresql://newhost/mydb"}'

Delete Config Item

DELETE /api/configs/{config_id}/items/{id}/

Example:

curl -X DELETE https://api.example.com/api/configs/abc123.../items/item1.../ \
  -H "Authorization: Bearer gob_your_key"

Automatic Sync

When you add, update, or delete config items, changes are automatically synced to your running services. Services will pick up the new configuration after they restart or redeploy.

Configs vs Secrets

Feature	Configs	Secrets
Use for	Non-sensitive settings	Sensitive data
Encryption	Not encrypted	Encrypted at rest
Visibility	Values visible in UI	Values hidden by default
Access logging	No	Yes

Use Configs For

• API endpoints and URLs
• Feature flags
• Environment names
• Non-sensitive settings

Use Secrets For

• API keys and tokens
• Database passwords
• Private keys
• Any sensitive data

Example Workflow

1. Create a Config

CONFIG=$(curl -s -X POST https://api.example.com/api/configs/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app-config"}')

CONFIG_ID=$(echo $CONFIG | jq -r '.id')

2. Add Config Items

# Add multiple config items
curl -X POST https://api.example.com/api/configs/$CONFIG_ID/items/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "API_URL", "value": "https://api.example.com"}'

curl -X POST https://api.example.com/api/configs/$CONFIG_ID/items/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "LOG_LEVEL", "value": "info"}'

3. Use in Service

curl -X POST https://api.example.com/api/services/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "image": "myapp:v1.0.0",
    "port": 8080,
    "config": "'$CONFIG_ID'",
    "secret": "your-secret-id"
  }'

Next Steps

• Secrets - Manage sensitive data
• Services - Attach configs to services