Apps API

Path Parameters

Description

Lists essesseff apps for a team account. Supports filtering by organization and app name. Returns app details including repository URLs, template information, and creation timestamps.

Query Parameters

Request Example

curl -X GET \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

With optional app_name filter:

curl -X GET \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps?app_name=my-app" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response Example

{
  "success": true,
  "data": [
    {
      "app_name": "my-app",
      "organization_login": "my-apps-org",
      "description": "My essesseff app",
      "programming_language": "go",
      "repository_visibility": "private",
      "template": {
        "name": "essesseff-hello-world-go-template",
        "language": "go",
        "is_global_template": true
      },
      "created_at": "2025-01-01T00:00:00Z",
      "repository_urls": {
        "source_repo": "https://github.com/my-apps-org/my-app",
        "config_dev_repo": "https://github.com/my-apps-org/my-app-config-dev",
        "config_qa_repo": "https://github.com/my-apps-org/my-app-config-qa",
        "config_staging_repo": "https://github.com/my-apps-org/my-app-config-staging",
        "config_prod_repo": "https://github.com/my-apps-org/my-app-config-prod",
        "argocd_dev_repo": "https://github.com/my-apps-org/my-app-argocd-dev",
        "argocd_qa_repo": "https://github.com/my-apps-org/my-app-argocd-qa",
        "argocd_staging_repo": "https://github.com/my-apps-org/my-app-argocd-staging",
        "argocd_prod_repo": "https://github.com/my-apps-org/my-app-argocd-prod"
      }
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

Path Parameters

Query Parameters

Description

Creates a new essesseff app with the specified configuration. The app creation process includes creating 9 GitHub repositories (1 source + 4 config + 4 Argo CD), setting up webhooks, assigning teams, and configuring retention policies.

Request Body

Note: account_slug, organization_login, and app_name are now provided in the path and query parameters, not in the request body.

Request Examples

Below are examples for each available global template:

curl -X POST \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps?app_name=my-java-app" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "My Java Spring Boot application",
    "programming_language": "java",
    "template": {
      "template_org_login": "essesseff-helloworld-springboot-templat",
      "source_template_repo": "helloworld",
      "is_global_template": true,
      "replacement_string": "helloworld"
    },
    "repository_visibility": "private"
  }'

curl -X POST \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps?app_name=my-go-app" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "My Go application",
    "programming_language": "go",
    "template": {
      "template_org_login": "essesseff-hello-world-go-template",
      "source_template_repo": "hello-world",
      "is_global_template": true,
      "replacement_string": "hello-world"
    },
    "repository_visibility": "private"
  }'

curl -X POST \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps?app_name=my-nodejs-app" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "My Node.js application",
    "programming_language": "node",
    "template": {
      "template_org_login": "essesseff-hello-world-nodejs-template",
      "source_template_repo": "hello-world",
      "is_global_template": true,
      "replacement_string": "hello-world"
    },
    "repository_visibility": "private"
  }'

curl -X POST \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps?app_name=my-python-app" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "My Python Flask application",
    "programming_language": "python",
    "template": {
      "template_org_login": "essesseff-hello-world-flask-template",
      "source_template_repo": "hello-world",
      "is_global_template": true,
      "replacement_string": "hello-world"
    },
    "repository_visibility": "private"
  }'

Response Example

{
  "success": true,
  "data": {
    "account_slug": "my-team",
    "app_name": "my-app",
    "organization_login": "my-apps-org",
    "description": "My essesseff app",
    "programming_language": "go",
    "resultant_repos": {
      "source_repo": "my-app",
      "config_dev_repo": "my-app-config-dev",
      "config_qa_repo": "my-app-config-qa",
      "config_staging_repo": "my-app-config-staging",
      "config_prod_repo": "my-app-config-prod",
      "argocd_dev_repo": "my-app-argocd-dev",
      "argocd_qa_repo": "my-app-argocd-qa",
      "argocd_staging_repo": "my-app-argocd-staging",
      "argocd_prod_repo": "my-app-argocd-prod",
      "template_org_login": "essesseff-hello-world-go-template",
      "is_global_template": true,
      "replacement_string": "hello-world"
    },
    "repository_visibility": "private"
  }
}

Template Notes

For global templates, the replacement_string is always "hello-world" (or "helloworld" for Java Spring Boot template). The system will automatically replace "hello-world" and/or "helloworld" with the specified app_name when cloning repository content from the templates.

Description

Gets app details including all repository IDs and URLs. Returns 404 if app doesn't exist.

Path Parameters

Request Example

curl -X GET \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps/my-app" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response Example

{
  "success": true,
  "data": {
    "app_name": "my-app",
    "organization_login": "my-apps-org",
    "description": "My essesseff app",
    "programming_language": "go",
    "repository_visibility": "private",
    "template": {
      "name": "essesseff-hello-world-go-template",
      "language": "go",
      "is_global_template": true
    },
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-01T00:00:00Z",
    "repository_urls": {
      "source_repo": "https://github.com/my-apps-org/my-app",
      "config_dev_repo": "https://github.com/my-apps-org/my-app-config-dev",
      "config_qa_repo": "https://github.com/my-apps-org/my-app-config-qa",
      "config_staging_repo": "https://github.com/my-apps-org/my-app-config-staging",
      "config_prod_repo": "https://github.com/my-apps-org/my-app-config-prod",
      "argocd_dev_repo": "https://github.com/my-apps-org/my-app-argocd-dev",
      "argocd_qa_repo": "https://github.com/my-apps-org/my-app-argocd-qa",
      "argocd_staging_repo": "https://github.com/my-apps-org/my-app-argocd-staging",
      "argocd_prod_repo": "https://github.com/my-apps-org/my-app-argocd-prod"
    },
    "repository_ids": {
      "source_repo": 12345678,
      "config_dev_repo": 12345679,
      "config_qa_repo": 12345680,
      "config_staging_repo": 12345681,
      "config_prod_repo": 12345682,
      "argocd_dev_repo": 12345683,
      "argocd_qa_repo": 12345684,
      "argocd_staging_repo": 12345685,
      "argocd_prod_repo": 12345686
    }
  }
}

Description

Updates an existing essesseff app. Currently supports updating description and repository visibility (private/public). When repository visibility is updated, all repositories associated with the app are updated in both the database and GitHub.

Path Parameters

Request Body

At least one of description or repository_visibility must be provided.

Request Example

curl -X PATCH \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps/my-app" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "repository_visibility": "public"
  }'

Response Example

{
  "success": true,
  "data": {
    "app_name": "my-app",
    "description": "Updated description",
    "repository_visibility": "public",
    "updated_at": "2025-01-02T00:00:00Z"
  }
}

Description

Lists deployments for a specific essesseff app. Supports filtering by environment (dev, qa, staging, prod) and status (pending, in_progress, succeeded, failed). Returns deployment details including image tags, GitHub commit information, and deployment timestamps.

Path Parameters

Query Parameters

Request Example

curl -X GET \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps/my-app/deployments?environment=prod&status=succeeded" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response Example

{
  "success": true,
  "data": [
    {
      "app_name": "my-app",
      "environment": "prod",
      "status": "succeeded",
      "image_tag": "v1.2.3",
      "github_sha": "abc123def456",
      "github_ref": "refs/heads/main",
      "deployed_at": "2025-01-01T12:00:00Z",
      "completed_at": "2025-01-01T12:05:00Z",
      "metadata": {
        "github_repository": "my-apps-org/my-app",
        "github_workflow_run_id": 12345678,
        "deployment_method": "manual_promote",
        "deployment_conclusion": "success",
        "health_status": "Healthy"
      }
    }
  ],
  "pagination": {
    "total": 10,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

Description

Lists container images for a specific essesseff app. Supports filtering by repository name, image tag, and status (active, expired, all). Returns image metadata including GitHub package version IDs.

Path Parameters

Query Parameters

Request Example

curl -X GET \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps/my-app/images?status=active" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response Example

{
  "success": true,
  "data": [
    {
      "app_name": "my-app",
      "repository_name": "my-app",
      "image_name": "my-app",
      "image_tag": "v1.2.3",
      "status": "active",
      "github_package_version_id": 12345678,
      "created_at": "2025-01-01T00:00:00Z",
      "expired_at": null,
      "metadata": {
        "github_organization": "my-apps-org",
        "package_type": "container"
      }
    }
  ],
  "pagination": {
    "total": 50,
    "limit": 100,
    "offset": 0,
    "has_more": false
  }
}

Description

Retrieves detailed information about a specific container image by tag. If multiple repositories have the same image tag, use the repository_name query parameter to disambiguate.

Path Parameters

Query Parameters

Request Example

curl -X GET \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps/my-app/images/v1.2.3" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response Example

{
  "success": true,
  "data": {
    "app_name": "my-app",
    "repository_name": "my-app",
    "image_name": "my-app",
    "image_tag": "v1.2.3",
    "status": "active",
    "github_package_version_id": 12345678,
    "created_at": "2025-01-01T00:00:00Z",
    "expired_at": null,
    "metadata": {
      "github_organization": "my-apps-org",
      "package_type": "container",
      "github_package_url": "https://github.com/my-apps-org/my-app/pkgs/container/my-app"
    }
  }
}

Description

Returns current lifecycle state and timestamp for the image. Query history=true to include state history (no UUIDs). Response includes account_slug, organization, app, image_name, image_tag, current_state (e.g. "QA" for QA_TESTING), state_timestamp.

Query Parameters

history (optional): set totrue or1 to include state history in the response.

Request Example

curl -X GET \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps/my-app/images/v1.2.3/lifecycle?history=true" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response Example (200, no history)

{
  "account_slug": "my-team",
  "organization": "my-apps-org",
  "app": "my-app",
  "image_name": "my-app",
  "image_tag": "v1.2.3",
  "current_state": "RC",
  "state_timestamp": "2025-09-30T12:00:00Z"
}

Response Example (200, with history=true)

{
  "account_slug": "my-team",
  "organization": "my-apps-org",
  "app": "my-app",
  "image_name": "my-app",
  "image_tag": "v1.2.3",
  "current_state": "RC",
  "state_timestamp": "2025-09-30T12:00:00Z",
  "history": [
    { "state": "BUILD", "state_timestamp": "2025-09-30T10:00:00Z", "is_active": false },
    { "state": "DEV", "state_timestamp": "2025-09-30T11:00:00Z", "is_active": false },
    { "state": "RC", "state_timestamp": "2025-09-30T12:00:00Z", "is_active": true }
  ]
}

Description

Transition the image to a new lifecycle state. Body:state (required; use "QA" for QA_TESTING); optional deployment_note when state is PROD. Only allowed transitions (per lifecycle table) are accepted; same-state or backwards transitions return 400. When state is DEV, QA, STAGING, or PROD, the API also performs the corresponding environment deployment (config repo promotion and deployment record). PROD via API does not require OTP.

Request Example

curl -X POST \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps/my-app/images/v1.2.3/lifecycle" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"state": "QA"}'

Response Example (200)

{
  "account_slug": "my-team",
  "organization": "my-apps-org",
  "app": "my-app",
  "image_name": "my-app",
  "image_tag": "v1.2.3",
  "state": "QA",
  "state_timestamp": "2025-09-30T12:00:00Z"
}

Path Parameters

env must be one of: DEV, QA, STAGING, PROD.

Description

Returns the image currently deployed to the given environment. Response includes account_slug, organization, app, environment, image_name, image_tag, state_timestamp, and argocd_application_url (optional URL to the Argo CD application for this environment, if set in app settings). If no deployment exists, image_name, image_tag, and state_timestamp are null.

Request Example

curl -X GET \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps/my-app/environments/QA" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response Example (200, with deployment)

{
  "account_slug": "my-team",
  "organization": "my-apps-org",
  "app": "my-app",
  "environment": "QA",
  "image_name": "my-app",
  "image_tag": "v1.2.3",
  "state_timestamp": "2025-09-30T11:00:00Z",
  "argocd_application_url": "https://argocd.example.com/applications/argocd/my-app-qa"
}

Response Example (200, no deployment)

When no image is deployed to the environment:

{
  "account_slug": "my-team",
  "organization": "my-apps-org",
  "app": "my-app",
  "environment": "QA",
  "image_name": null,
  "image_tag": null,
  "state_timestamp": null,
  "argocd_application_url": null
}

Path Parameters

env must be one of: DEV, QA, STAGING, PROD.

Description

Sets the optional Argo CD application URL for the given environment. The URL is stored in app settings and shown in the essesseff UI (deployment cards, app settings). The URL is validated and normalized (trailing slash removed). Send null or empty to clear. Returns 204 on success.

Request Body

url (optional): string or null. Full URL to the Argo CD application for this environment (e.g. https://argocd.example.com/applications/argocd/my-app-qa). Max 1000 characters. Omit or set to null to clear.

Request Example

curl -X POST \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps/my-app/environments/QA/set-argocd-application-url" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://argocd.example.com/applications/argocd/my-app-qa"}'

Response

Returns 204 No Content on success. Returns 400 for invalid env or invalid URL format.

Request Example

curl -X POST \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps/my-app/environments/DEV/declare-rc" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{}'

Response Example (200)

{
  "account_slug": "my-team",
  "organization": "my-apps-org",
  "app": "my-app",
  "environment": "DEV",
  "image_name": "my-app",
  "image_tag": "v1.2.3",
  "state": "RC",
  "state_timestamp": "2025-09-30T12:00:00Z"
}

Request Example

curl -X POST \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps/my-app/environments/QA/accept-rc" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"image_tag": "v1.2.3"}'

Response Example (200)

{
  "account_slug": "my-team",
  "organization": "my-apps-org",
  "app": "my-app",
  "environment": "QA",
  "image_name": "my-app",
  "image_tag": "v1.2.3",
  "state": "QA",
  "state_timestamp": "2025-09-30T12:00:00Z"
}

Request Example

curl -X POST \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps/my-app/environments/QA/reject-rc" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"image_tag": "v1.2.3"}'

Response Example (200)

{
  "account_slug": "my-team",
  "organization": "my-apps-org",
  "app": "my-app",
  "environment": "QA",
  "image_name": "my-app",
  "image_tag": "v1.2.3",
  "state": "REJECTED",
  "state_timestamp": "2025-09-30T12:00:00Z"
}

Request Example

curl -X POST \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps/my-app/environments/QA/declare-stable" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{}'

Response Example (200)

{
  "account_slug": "my-team",
  "organization": "my-apps-org",
  "app": "my-app",
  "environment": "QA",
  "image_name": "my-app",
  "image_tag": "v1.2.3",
  "state": "STABLE",
  "state_timestamp": "2025-09-30T12:00:00Z"
}

Request Example

curl -X POST \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps/my-app/environments/QA/declare-rejected" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{}'

Response Example (200)

{
  "account_slug": "my-team",
  "organization": "my-apps-org",
  "app": "my-app",
  "environment": "QA",
  "image_name": "my-app",
  "image_tag": "v1.2.3",
  "state": "REJECTED",
  "state_timestamp": "2025-09-30T12:00:00Z"
}

Request Example

curl -X POST \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps/my-app/environments/STAGING/deploy-stable" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"image_tag": "v1.2.3"}'

Response Example (200)

{
  "account_slug": "my-team",
  "organization": "my-apps-org",
  "app": "my-app",
  "environment": "STAGING",
  "image_name": "my-app",
  "image_tag": "v1.2.3",
  "state": "STAGING",
  "state_timestamp": "2025-09-30T12:00:00Z"
}

Request Example

curl -X POST \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps/my-app/environments/PROD/deploy-stable" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"image_tag": "v1.2.3", "deployment_note": "CR#12345"}'

Response Example (200)

{
  "account_slug": "my-team",
  "organization": "my-apps-org",
  "app": "my-app",
  "environment": "PROD",
  "image_name": "my-app",
  "image_tag": "v1.2.3",
  "state": "PROD",
  "state_timestamp": "2025-09-30T12:00:00Z",
  "deployment_note": "CR#12345"
}

Description

Lists retention policies for a specific essesseff app. Retention policies are mapped to environments (dev, qa, staging, prod) based on lifecycle states (DEV, QA, STAGING, PROD). Returns retention days and timestamps for each policy.

Path Parameters

Query Parameters

Request Example

curl -X GET \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps/my-app/retention-policies?environment=prod" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response Example

{
  "success": true,
  "data": [
    {
      "app_name": "my-app",
      "repository_name": "my-app",
      "environment": "prod",
      "retention_days": 30,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ]
}

Description

Updates an existing retention policy for a specific app, repository, and environment. Allows modifying retention_days for image lifecycle states. Retention policies are app-scoped (source repository scoped).

Path Parameters

Query Parameters

Request Body

Request Example

curl -X PATCH \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps/my-app/retention-policies?repository_name=my-app&environment=prod" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "retention_days": 60
  }'

Response Example

{
  "success": true,
  "data": {
    "app_name": "my-app",
    "repository_name": "my-app",
    "environment": "prod",
    "retention_days": 60,
    "updated_at": "2025-01-02T00:00:00Z"
  }
}

Description

Retrieves the notifications-secret.yaml file content for Argo CD setup. Returns YAML content with Content-Type: application/x-yaml. This file contains Argo CD Notifications Event Processor API keys and environment-specific app secrets.

Note: Secrets are automatically issued from the database when this file is generated if they don't already exist.

Path Parameters

Request Example

curl -X GET \
  "https://www.essesseff.com/api/v1/accounts/my-team/organizations/my-apps-org/apps/my-app/notifications-secret" \
  -H "X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -o notifications-secret.yaml

Response

Returns YAML content with Content-Type: application/x-yaml:

# notifications-secret.yaml

# Store Argo CD Notifications Event Processor API key and environment-specific app secrets
# ***DELETE THIS FILE AFTER APPLYING - DO NOT COMMIT SECRETS TO GITHUB***

apiVersion: v1
kind: Secret
metadata:
  name: argocd-notifications-secret
  namespace: argocd
type: Opaque
stringData:
  argocd-webhook-url: "https://api.essesseff.com/api/v1/argocd/webhook"
  aws-api-gateway-key-my-apps-org: "ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  app-secret-12345678: "abc123def456..."
  app-secret-12345679: "xyz789uvw012..."
  app-secret-12345680: "mno345pqr678..."
  app-secret-12345681: "ghi901jkl234..."

The response includes secrets for all environments (dev, qa, staging, prod) that have config repositories. Secret keys are environment-specific: app-secret-{config-env-repository-id}