essesseff DevOps ALM

Interact with the essesseff DevOps platform — call the essesseff Public API (templates, organizations, apps, deployments, images, image lifecycle, environmen...

essesseff Skill

This skill covers two complementary ways to work with the essesseff DevOps platform:

1. essesseff Public API — direct HTTP calls for managing templates, organizations, apps, images, deployments, environments, packages, and retention policies.
2. essesseff Onboarding Utility — shell scripts that automate app creation and Argo CD deployment setup.

Quick Reference

Base URL: https://www.essesseff.com/api/v1 (use www to avoid 307 redirects)

Authentication: All requests require X-API-Key: ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx header.

Rate limit: 3 requests per 10 seconds. Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Path structure:

• Global (no account needed): /api/v1/global/...
• Account-specific: /api/v1/accounts/{account_slug}/... — API key must belong to the account_slug in the path or a 403 is returned.

API Reference Files

For full endpoint details, request/response examples, and query parameters, see:

Reference	Contents
references/api-overview.md	Auth, base URL, rate limiting, error codes
references/api-templates.md	Global templates, account-specific templates
references/api-organizations.md	List and detail GitHub orgs for an account
references/api-apps.md	Create, list, get, update apps; list deployments
references/api-images.md	List images, get image by tag
references/api-images.md	Image lifecycle: get state, transition state
references/api-environments.md	Get environment; set Argo CD URL; DEV→QA→STAGING→PROD lifecycle actions
references/api-packages.md	Get GitHub API payloads for expired package deletion
references/api-retention-policies.md	List and update retention policies

API Endpoint Map

Global

Method	Path	Purpose
GET	/global/templates	List global templates (optional ?language=go|python|node|java|rust|php)
GET	/global/templates/{template_name}	Get global template details

Account-Specific (all require matching API key)

Method	Path	Purpose
GET	/accounts/{account_slug}/templates	List account templates
GET	/accounts/{account_slug}/templates/{template_name}	Get account template details
GET	/accounts/{account_slug}/organizations	List orgs for account
GET	/accounts/{account_slug}/organizations/{org_login}	Get org detail + app list
GET	/accounts/{account_slug}/organizations/{org_login}/apps	List apps
POST	/accounts/{account_slug}/organizations/{org_login}/apps?app_name={name}	Create app
GET	/accounts/{account_slug}/organizations/{org_login}/apps/{app_name}	Get app detail
PATCH	/accounts/{account_slug}/organizations/{org_login}/apps/{app_name}	Update app
GET	.../apps/{app_name}/deployments	List deployments
GET	.../apps/{app_name}/images	List images
GET	.../apps/{app_name}/images/{image_tag}	Get image by tag
GET	.../apps/{app_name}/images/{image_tag}/lifecycle	Get image lifecycle state
POST	.../apps/{app_name}/images/{image_tag}/lifecycle	Transition image lifecycle state
GET	.../apps/{app_name}/environments/{env}	Get current env deployment
POST	.../apps/{app_name}/environments/{env}/set-argocd-application-url	Set/clear Argo CD URL
POST	.../apps/{app_name}/environments/DEV/declare-rc	Mark DEV image as RC
POST	.../apps/{app_name}/environments/QA/accept-rc	Accept RC → deploy to QA
POST	.../apps/{app_name}/environments/QA/reject-rc	Reject RC
POST	.../apps/{app_name}/environments/QA/declare-stable	Mark QA image as STABLE
POST	.../apps/{app_name}/environments/QA/declare-rejected	Mark QA image as REJECTED
POST	.../apps/{app_name}/environments/STAGING/deploy-stable	Deploy STABLE to STAGING
POST	.../apps/{app_name}/environments/PROD/deploy-stable	Deploy STABLE to PROD (no OTP)
GET	.../apps/{app_name}/notifications-secret	Get notifications-secret.yaml for Argo CD
GET	.../apps/{app_name}/packages/delete-packages	Get expired package deletion payloads
GET	.../apps/{app_name}/retention-policies	List retention policies (filter by ?state=)
PATCH	.../apps/{app_name}/retention-policies?state={state}	Create or update a retention policy for a lifecycle state

Image Lifecycle State Machine

Images progress through states in this order:

BUILD → DEV → RC → QA → STABLE → STAGING → PROD
              ↑  ↓  ↓
            REJECTED

Key transitions via API:

• DEV/declare-rc — promotes current DEV image to RC (no body)
• QA/accept-rc — body: {"image_tag": "v1.2.3"} → sets QA, deploys to QA
• QA/reject-rc — body: {"image_tag": "v1.2.3"} → sets REJECTED
• QA/declare-stable — no body → sets STABLE on current QA image
• QA/declare-rejected — no body → sets REJECTED on current QA image
• STAGING/deploy-stable — body: {"image_tag": "v1.2.3"} → deploys to STAGING
• PROD/deploy-stable — body: {"image_tag": "v1.2.3", "deployment_note": "CR#123"} → deploys to PROD (no OTP required via API)

Alternatively, use POST .../images/{image_tag}/lifecycle with body {"state": "QA"} for direct lifecycle transitions.

Onboarding Utility Reference

For shell-script-based automation (no API calls required), see:

Reference	Contents
references/onboarding-utility.md	Full guide: setup, commands, how it works
references/prerequisites.md	System binaries, PATs, K8s/Argo CD prereqs
references/non-subscriber-mode.md	Clone/replace/push workflow without a subscription

The utility (essesseff-onboard.sh) accepts:

• --list-templates — list available templates
• --create-app — create all 9 repos (via API for subscribers, clone/replace/push for non-subscribers)
• --setup-argocd dev,qa,staging,prod — configure Argo CD for each environment
• --non-essesseff-subscriber-mode — no essesseff API required
• --config-file .essesseff — path to config file
• --verbose — debug output

Common Errors

Code	Meaning
400	Invalid request parameters
401	Invalid or missing API key
403	API key does not match the account_slug in the path
404	Resource not found
429	Rate limit exceeded — wait and retry
500	Server error