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:

ReferenceContentsreferences/api-overview.mdAuth, base URL, rate limiting, error codesreferences/api-templates.mdGlobal templates, account-specific templatesreferences/api-organizations.mdList and detail GitHub orgs for an accountreferences/api-apps.mdCreate, list, get, update apps; list deploymentsreferences/api-images.mdList images, get image by tagreferences/api-images.mdImage lifecycle: get state, transition statereferences/api-environments.mdGet environment; set Argo CD URL; DEV→QA→STAGING→PROD lifecycle actionsreferences/api-packages.mdGet GitHub API payloads for expired package deletionreferences/api-retention-policies.mdList and update retention policies

API Endpoint Map#

Global#

MethodPathPurposeGET/global/templatesList 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)#

MethodPathPurposeGET/accounts/{account_slug}/templatesList account templatesGET/accounts/{account_slug}/templates/{template_name}Get account template detailsGET/accounts/{account_slug}/organizationsList orgs for accountGET/accounts/{account_slug}/organizations/{org_login}Get org detail + app listGET/accounts/{account_slug}/organizations/{org_login}/appsList appsPOST/accounts/{account_slug}/organizations/{org_login}/apps?app_name={name}Create appGET/accounts/{account_slug}/organizations/{org_login}/apps/{app_name}Get app detailPATCH/accounts/{account_slug}/organizations/{org_login}/apps/{app_name}Update appGET.../apps/{app_name}/deploymentsList deploymentsGET.../apps/{app_name}/imagesList imagesGET.../apps/{app_name}/images/{image_tag}Get image by tagGET.../apps/{app_name}/images/{image_tag}/lifecycleGet image lifecycle statePOST.../apps/{app_name}/images/{image_tag}/lifecycleTransition image lifecycle stateGET.../apps/{app_name}/environments/{env}Get current env deploymentPOST.../apps/{app_name}/environments/{env}/set-argocd-application-urlSet/clear Argo CD URLPOST.../apps/{app_name}/environments/DEV/declare-rcMark DEV image as RCPOST.../apps/{app_name}/environments/QA/accept-rcAccept RC → deploy to QAPOST.../apps/{app_name}/environments/QA/reject-rcReject RCPOST.../apps/{app_name}/environments/QA/declare-stableMark QA image as STABLEPOST.../apps/{app_name}/environments/QA/declare-rejectedMark QA image as REJECTEDPOST.../apps/{app_name}/environments/STAGING/deploy-stableDeploy STABLE to STAGINGPOST.../apps/{app_name}/environments/PROD/deploy-stableDeploy STABLE to PROD (no OTP)GET.../apps/{app_name}/notifications-secretGet notifications-secret.yaml for Argo CDGET.../apps/{app_name}/packages/delete-packagesGet expired package deletion payloadsGET.../apps/{app_name}/retention-policiesList 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:

text

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:

ReferenceContentsreferences/onboarding-utility.mdFull guide: setup, commands, how it worksreferences/prerequisites.mdSystem binaries, PATs, K8s/Argo CD prereqsreferences/non-subscriber-mode.mdClone/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#

CodeMeaning400Invalid request parameters401Invalid or missing API key403API key does not match the account_slug in the path404Resource not found429Rate limit exceeded — wait and retry500Server error