essesseff Public API Documentation

Overview

The essesseff Public API provides programmatic access to essesseff platform features. All API requests require authentication via API keys and are subject to rate limiting.

Base URL

https://essesseff.com/api/v1

Authentication

All API requests must include an API key in the Authorization header:

Authorization: Bearer ess_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys can be generated and managed in your team account settings. API keys are only issuable to account owners and DevOps Engineers.

API Structure

The essesseff API uses a hierarchical path structure to express context explicitly:

Global resources: /api/v1/global/... (system-level resources, not account-specific)
Account-specific resources: /api/v1/accounts/{account_slug}/... (requires account_slug in path)

For account-specific endpoints, the API key must belong to the account_slug specified in the path. If the API key does not match the account_slug, a 403 Forbidden error is returned.

Rate Limiting

API requests are rate-limited to 3 requests per 10 seconds.

Rate limit information is included in response headers:

X-RateLimit-Limit: 3
X-RateLimit-Remaining: 2
X-RateLimit-Reset: 1234567890

Error Handling

Errors are returned in JSON format with appropriate HTTP status codes:

{
  "error": "Error message describing what went wrong",
  "message": "Additional details about the error"
}

Common error codes:

400 Bad Request - Invalid request parameters
401 Unauthorized - Invalid or missing API key
403 Forbidden - API key does not belong to the specified account_slug
404 Not Found - Resource not found
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error

API Endpoints

Available essesseff public API endpoints organized by context hierarchy

Global Resources

System-level resources available to all authenticated users (no account_slug required)

GET /global/templates

List available global essesseff app templates. Supports optional filtering by programming language.

GET /global/templates/{template_name}

Get complete details for a specific global template (all fields needed for app creation).

Account-Specific Resources

All account-specific endpoints require account_slug in the path. The API key must belong to the specified account_slug.

Templates

GET /accounts/{account_slug}/templates

List team-account-specific templates for the specified account.

GET /accounts/{account_slug}/templates/{template_name}

Get complete details for a team-account-specific template.

Organizations

GET /accounts/{account_slug}/organizations

List GitHub organizations associated with a team account.

GET /accounts/{account_slug}/organizations/{organization_login}

Retrieve detailed information about a specific GitHub organization with app list.

Apps

POST /accounts/{account_slug}/organizations/{organization_login}/apps

Create a new essesseff app. Requires app_name as a query parameter.

GET /accounts/{account_slug}/organizations/{organization_login}/apps

List essesseff apps for an organization. Supports optional filtering by app_name.

GET /accounts/{account_slug}/organizations/{organization_login}/apps/{app_name}

Get app details including all repository IDs and URLs.

PATCH /accounts/{account_slug}/organizations/{organization_login}/apps/{app_name}

Update an existing essesseff app (description, repository_visibility).

Other Endpoints

GET /packages/delete-packages

Retrieve GitHub API payloads for deleting package versions that correspond to expired essesseff images.

Getting Started

Generate an API key in your team account settings (/home/[account]/settings)
Include the API key in the Authorization header of all requests
Review the individual endpoint documentation for request/response formats
Implement proper error handling and rate limit management in your client code