API Reference

    Integrate programmatically with the AeThex API

    The REST API exposes every core capability of the AeThex platform. Authenticate with OAuth 2.1 or personal access tokens, call idempotent endpoints, and subscribe to webhooks to react to changes in real time.

    Authentication flow

    Use the OAuth client credentials grant for service-to-service integrations:

    curl -X POST https://api.aethex.dev/v1/auth/token   -u CLIENT_ID:CLIENT_SECRET   -d "grant_type=client_credentials"   -d "scope=projects:read deployments:write"

    Prefer user-scoped access? Direct builders through the hosted OAuth consent screen and exchange their authorization code using the same endpoint.

    Request example

    Call the Projects endpoint with your Bearer token and inspect pagination headers for large result sets.

    fetch("https://api.aethex.dev/v1/projects?page=1&limit=25", {
  headers: {
    Authorization: "Bearer ${TOKEN}",
    "AeThex-Environment": "production",
  },
}).then(async (res) => {
  if (!res.ok) throw new Error(await res.text());
  console.log("Projects", await res.json());
});

    Responses include X-RateLimit-Remainingand X-Request-ID headers. Share the request ID when contacting support for faster triage.

    Core endpoints

    MethodPathDescription
    POST
    		/v1/auth/tokenExchange client credentials for an access token
    GET
    		/v1/projectsList projects the current identity can access
    POST
    		/v1/projectsCreate a project with environment defaults
    GET
    		/v1/projects/{projectId}/metricsRetrieve runtime metrics and usage breakdowns
    POST
    		/v1/webhooks/verifyValidate webhook signatures from AeThex
    Need deeper coverage? The JavaScript SDK ships with typed request builders for every endpoint.

    Webhook topics

    deployment.succeeded

    Triggered when a deployment pipeline completes successfully with promoted build artifacts.

    deployment.failed

    Sent when a pipeline fails. Includes failure stage, summary, and recommended remediation steps.

    incident.opened

    Raised when monitoring detects outages or SLA breaches in production environments.

    member.invited

    Notify downstream systems when a collaborator invitation is created or accepted.

    Configure webhook destinations and signing secrets from the dashboard. Verify requests with the AeThex-Signatureheader to guarantee authenticity.

    Resilience & errors

    All endpoints are idempotent where appropriate and support conditional requests via theIf-Match header.

    401

    Unauthorized

    Verify the Bearer token and ensure it has not expired.

    403

    Forbidden

    The identity lacks the required scope. Request the project-admin role.

    429

    Too Many Requests

    Respect the rate limit headers or enable adaptive backoff via the SDK.

    503

    Service Unavailable

    Retry with exponential backoff. AeThex dashboards surface ongoing maintenance windows.

    Monitor rate-limit headers and retry using an exponential backoff strategy. Persistent errors can be escalated to the AeThex support team with the failing request ID.

    Ship production-ready integrations

    Combine the REST API with event webhooks for a full-duplex integration pattern. Use the official TypeScript SDK for typed helpers or generate your own client with the published OpenAPI schema.

    OpenAPI explorerSee implementation patterns