Secrets API

All endpoints require authentication via Bearer token.

Base URL

• Cloud: https://api.soup.dev/api/v1
• Self-hosted: http://your-server:8080/api/v1

Get All Secrets

Get all secrets for an environment with inheritance and reference resolution.

GET /projects/{project_id}/environments/{env_id}/secrets

Query Parameters

Parameter	Type	Default	Description
resolve	boolean	true	Resolve ${VAR} references

Response

{
  "data": {
    "DATABASE_URL": "postgres://localhost:5432/mydb",
    "API_KEY": "sk_live_...",
    "LOG_LEVEL": "info"
  }
}

Example

# Get resolved secrets
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.soup.dev/api/v1/projects/proj_123/environments/env_456/secrets"

# Get unresolved (raw values)
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.soup.dev/api/v1/projects/proj_123/environments/env_456/secrets?resolve=false"

Get Single Secret

GET /projects/{project_id}/environments/{env_id}/secrets/{key}

Response

{
  "data": {
    "key": "DATABASE_URL",
    "value": "postgres://localhost:5432/mydb"
  }
}

Errors

Status	Error	Description
404	Secret not found	Key doesn’t exist in this environment or parents
403	Permission denied	User doesn’t have access to this project

Set Secret

Create or update a secret.

POST /projects/{project_id}/environments/{env_id}/secrets
Content-Type: application/json

{
  "key": "DATABASE_URL",
  "value": "postgres://localhost:5432/mydb"
}

Response

{
  "data": {
    "key": "DATABASE_URL"
  }
}

Status: 201 Created

Key Validation

Keys must:

• Start with a letter (A-Z)
• Contain only uppercase letters, numbers, and underscores
• Be 1-255 characters

Valid: DATABASE_URL, API_KEY_V2, MY_VAR Invalid: database_url, 123_KEY, my-var

Delete Secret

DELETE /projects/{project_id}/environments/{env_id}/secrets/{key}

Response

Status: 204 No Content

Notes

• Only deletes from the specified environment
• If the key exists in a parent environment, child environments will inherit it after deletion

List Secret Keys

Get just the keys (not values) for an environment.

GET /projects/{project_id}/environments/{env_id}/secrets/keys

Response

{
  "data": [
    "DATABASE_URL",
    "API_KEY",
    "LOG_LEVEL"
  ]
}

Batch Operations

Export All (CLI)

The CLI’s export command uses the secrets endpoint:

soup export my-app production
# Calls: GET /projects/{id}/environments/{id}/secrets
# Formats as shell exports

Import (Coming Soon)

Bulk import from .env file:

soup import my-app production --file .env

Rate Limits

Tier	Requests/minute
Self-hosted	Unlimited
Cloud Free	100
Cloud Pro	1,000
Cloud Enterprise	10,000

Examples

cURL

# Set a secret
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "API_KEY", "value": "sk_live_..."}' \
  https://api.soup.dev/api/v1/projects/proj_123/environments/env_456/secrets

# Get all secrets
curl -H "Authorization: Bearer $TOKEN" \
  https://api.soup.dev/api/v1/projects/proj_123/environments/env_456/secrets

# Delete a secret
curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  https://api.soup.dev/api/v1/projects/proj_123/environments/env_456/secrets/OLD_KEY

JavaScript

const response = await fetch(
  `${API_URL}/projects/${projectId}/environments/${envId}/secrets`,
  {
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  }
);
const { data } = await response.json();
console.log(data.DATABASE_URL);

Python

import requests

response = requests.get(
    f"{API_URL}/projects/{project_id}/environments/{env_id}/secrets",
    headers={"Authorization": f"Bearer {token}"}
)
secrets = response.json()["data"]
print(secrets["DATABASE_URL"])