# CLAUDE Source: https://api-docs.sevalla.com/CLAUDE # CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview Sevalla API documentation site built with [Mintlify](https://mintlify.com). Endpoint pages are generated from remote OpenAPI specs. There are no local MDX files per endpoint. * **Live site:** [https://api-docs.sevalla.com](https://api-docs.sevalla.com) * **Repo:** sevalla-hosting/api-docs ## Architecture * **Remote OpenAPI specs** (source of truth for all endpoint details, schemas, and examples), served by the production API: * `https://api.sevalla.com/v3/openapi.json`: v3 primary endpoints * `https://api.sevalla.com/v2/openapi.json`: v2 legacy endpoints * The specs are generated by `mk-app-management-service` with `@fastify/swagger` (`src/web/apiGateway/v3/` and `src/web/apiGateway/v2/`). Change endpoint summaries, descriptions, schemas, and examples there, not in this repo. * `docs.json`: Mintlify configuration (navigation tabs, theme, integrations, navbar, footer). Each tab has an `openapi` field pointing to a remote spec. An endpoint appears on the site only if a navigation group lists it as `" "`, for example `"GET /applications/{id}/egress-ips"`. Endpoints that are in the spec but not in `docs.json` are not published. * `v3/`: hand-written guide pages (authentication, errors, rate limits, pagination, CLI, webhook events). They are listed in `docs.json` like any other page. * `index.mdx`: standalone landing page ## Development There is no build step or package.json. Mintlify handles rendering and hosting. To preview locally and check links, install the Mintlify CLI and run: ``` npx mintlify dev npx mintlify broken-links ``` The preview reads the prod specs. To preview an endpoint that is only on dev so far, temporarily point the tab's `openapi.source` at `https://api-dev.sevalla.com/v3/openapi.json` (or `v2`). Revert it before committing. ## Adding a New Endpoint 1. Add the route and its schema in `mk-app-management-service` (`src/web/apiGateway/v3/` or `v2/`). 2. Add `" "` to the matching group in `docs.json`, under the right tab. The method and path must match the spec exactly, including parameter names such as `{id}`. 3. Merge only after the endpoint is in the prod spec. Check with `curl -s https://api.sevalla.com/v3/openapi.json`. ## Conventions * All API endpoints use Bearer token authentication * Navigation uses two tabs (v3 and v2) with a top-left switcher * Commit messages follow conventional commits: `feat(scope): description` * Never use em dashes (—) in any content. Use periods, commas, or rephrase instead * Write copy that sounds human and direct. Avoid generic AI-sounding filler phrases * Always use TypeScript for code examples, never Python or other languages # Sevalla API Reference Source: https://api-docs.sevalla.com/index 200+ endpoints to deploy, scale, and manage your entire cloud infrastructure programmatically. Applications, databases, static sites, load balancers, object storage, and more. One API. Full control over your infrastructure. Deploy applications, provision databases, manage load balancers, store objects, and automate every part of your stack without touching a dashboard.
200+
API endpoints
13
Resource types
REST
JSON over HTTPS
Bearer
Token auth
## Get started in 60 seconds Create a key from your [Sevalla dashboard](https://app.sevalla.com/api-keys). One key authenticates every endpoint. ```bash theme={null} curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.sevalla.com/v3/applications ``` Browse the **v3** tab in the sidebar for full endpoint specs, schemas, and code examples. Use the **Try it** console on any page to make live calls. ## Let AI manage your infrastructure Your AI coding tools can talk to Sevalla directly. Connect Claude Code, Cursor, Codex, Windsurf, or any MCP-enabled agent and let it handle deployments, debugging, and scaling for you. Connect your agent to Sevalla in one command. The MCP server gives AI tools full access to the API through natural language, with OAuth authentication and sandboxed execution. Works with Claude Code, Cursor, Codex, Windsurf, and OpenCode. OAuth-based authentication for MCP connections, scoped API keys for direct access. Read-only for debugging, deploy-only for CI, full access for trusted tools. Rotate any key instantly. "Deploy the latest commit." "Roll back to yesterday." Your agent triggers deployments, watches build logs, and rolls back automatically if something breaks. "Why is the app slow?" Your agent pulls runtime logs, access logs, and metrics to diagnose issues without switching to a dashboard. "Scale web to 3 instances." Your agent adjusts process counts and resource limits based on what the traffic actually looks like. Get started with the [coding agents quick-start guide](https://docs.sevalla.com/quick-starts/coding-agents/overview) to connect your favorite AI tool to Sevalla in minutes. ## Everything you can manage Deploy from Git or Docker. Configure processes, domains, env vars, CDN, TCP proxies, IP restrictions, and deployment hooks. Monitor with 13 metrics endpoints. Provision PostgreSQL, MySQL, MariaDB, MongoDB, Redis, or Valkey. Manage backups, internal connections, external access, password resets, and resource metrics. Deploy to Cloudflare's edge. Manage domains, env vars, deployments, cache purging, access logs, and performance metrics. Distribute traffic across applications. Configure destinations, custom domains, and toggle routing on the fly. S3-compatible buckets with CORS policies, CDN domains, and object management built in. Staging-to-production workflows. Promote between stages, manage preview apps for feature branches. Connect private registries for Docker-based deployments. Full CRUD management. Get notified on infrastructure events. Inspect deliveries, rotate secrets, toggle endpoints. Organize services into logical groups. Add or remove applications, databases, and sites from projects. Create, rotate, and toggle API keys programmatically. Full lifecycle management. Trigger from branches or images. Track status, view build logs, cancel in progress, and rollback to last successful. Requests per minute, response times, status codes, top pages, CPU, memory, and storage for both apps and databases. ## Built for automation Trigger deployments from GitHub Actions, GitLab CI, or any pipeline. Use deployment hooks for zero-touch releases. Script your entire stack. Spin up applications, provision databases, configure load balancers, and set env vars in a single workflow. Pull CPU, memory, storage, and request metrics via API. Feed them into Datadog, Grafana, or your own dashboards. React to deployment completions, scaling events, and status changes in real time with configurable webhooks. # Delete application Source: https://api-docs.sevalla.com/v2/applications/delete-application https://api.sevalla.com/v2/openapi.json delete /applications/{id} Permanently delete an application and all related resources. # Get application Source: https://api-docs.sevalla.com/v2/applications/get-application https://api.sevalla.com/v2/openapi.json get /applications/{id} Fetch detailed information about a specific application by its unique identifier. # Get applications Source: https://api-docs.sevalla.com/v2/applications/get-applications https://api.sevalla.com/v2/openapi.json get /applications Retrieve a list of all applications accessible in a company. # Promote application Source: https://api-docs.sevalla.com/v2/applications/promote-application https://api.sevalla.com/v2/openapi.json post /applications/promote Promote an application in a pipeline to the next stage. # Update application Source: https://api-docs.sevalla.com/v2/applications/update-application https://api.sevalla.com/v2/openapi.json put /applications/{id} Update properties or settings of an existing application. # Validate API key Source: https://api-docs.sevalla.com/v2/authentication/validate-api-key https://api.sevalla.com/v2/openapi.json get /validate Validate the provided API key and return its details including name, expiration, associated company, and current status. # Get company users Source: https://api-docs.sevalla.com/v2/company/get-company-users https://api.sevalla.com/v2/openapi.json get /company/{id}/users Retrieve the list of users belonging to a company. # Get usage Source: https://api-docs.sevalla.com/v2/company/get-usage https://api.sevalla.com/v2/openapi.json get /company/{id}/paas-usage Retrieve daily PaaS usage data for a company within a billing period. # Create database Source: https://api-docs.sevalla.com/v2/databases/create-database https://api.sevalla.com/v2/openapi.json post /databases Create a new database with the specified configuration. # Delete database Source: https://api-docs.sevalla.com/v2/databases/delete-database https://api.sevalla.com/v2/openapi.json delete /databases/{id} Delete a database and all its associated data permanently. # Get database Source: https://api-docs.sevalla.com/v2/databases/get-database https://api.sevalla.com/v2/openapi.json get /databases/{id} Get details for a specific database, including configuration and status. # Get databases Source: https://api-docs.sevalla.com/v2/databases/get-databases https://api.sevalla.com/v2/openapi.json get /databases Retrieve a list of all databases available to a company. # Update database Source: https://api-docs.sevalla.com/v2/databases/update-database https://api.sevalla.com/v2/openapi.json put /databases/{id} Update settings or metadata for an existing database. # Get deployment Source: https://api-docs.sevalla.com/v2/deployments/get-deployment https://api.sevalla.com/v2/openapi.json get /applications/deployments/{id} Retrieve a deployment and details for a specific application. # Start deployment Source: https://api-docs.sevalla.com/v2/deployments/start-deployment https://api.sevalla.com/v2/openapi.json post /applications/deployments Start a new deployment for your application using this endpoint. # Clear cache Source: https://api-docs.sevalla.com/v2/networking/clear-cache https://api.sevalla.com/v2/openapi.json post /applications/{id}/clear-cache Clear the edge cache for your application to instantly update cached resources. # Create internal connection Source: https://api-docs.sevalla.com/v2/networking/create-internal-connection https://api.sevalla.com/v2/openapi.json post /applications/{id}/internal-connections Create an internal connection between an application and another resource (application or database) within the same region. Connections are bidirectional, so only one connection can exist between a given pair of services - creating it again in either direction returns 409. # Toggle CDN Source: https://api-docs.sevalla.com/v2/networking/toggle-cdn https://api.sevalla.com/v2/openapi.json post /applications/{id}/cdn/toggle-status Enable or disable CDN for your application to optimize content delivery. # Toggle edge cache Source: https://api-docs.sevalla.com/v2/networking/toggle-edge-cache https://api.sevalla.com/v2/openapi.json post /applications/{id}/edge-cache/toggle-status Toggle edge caching for improved application performance and lower latency. # Create preview app Source: https://api-docs.sevalla.com/v2/pipelines/create-preview-app https://api.sevalla.com/v2/openapi.json post /pipelines/{id}/create-preview-app Create a preview application in a pipeline. # Get pipelines Source: https://api-docs.sevalla.com/v2/pipelines/get-pipelines https://api.sevalla.com/v2/openapi.json get /pipelines List all pipeline configurations and workflows available to a company. # Get process Source: https://api-docs.sevalla.com/v2/processes/get-process https://api.sevalla.com/v2/openapi.json get /applications/processes/{id} Get information about the running processes for a specific application. # Update process Source: https://api-docs.sevalla.com/v2/processes/update-process https://api.sevalla.com/v2/openapi.json put /applications/processes/{id} Update or scale the running processes of an application. # Deploy static site Source: https://api-docs.sevalla.com/v2/static-site-deployments/deploy-static-site https://api.sevalla.com/v2/openapi.json post /static-sites/deployments Manually or programmatically deploy a static site. # Get static site deployment Source: https://api-docs.sevalla.com/v2/static-site-deployments/get-static-site-deployment https://api.sevalla.com/v2/openapi.json get /static-sites/deployments/{id} Retrieve deployment details for a specific static site deployment. # Delete static site Source: https://api-docs.sevalla.com/v2/static-sites/delete-static-site https://api.sevalla.com/v2/openapi.json delete /static-sites/{id} Permanently delete a static site and all related resources. # Get static site Source: https://api-docs.sevalla.com/v2/static-sites/get-static-site https://api.sevalla.com/v2/openapi.json get /static-sites/{id} Fetch detailed information about a specific static site by its unique identifier. # Get static sites Source: https://api-docs.sevalla.com/v2/static-sites/get-static-sites https://api.sevalla.com/v2/openapi.json get /static-sites Retrieve a list of all static sites accessible in a company. # Update static site Source: https://api-docs.sevalla.com/v2/static-sites/update-static-site https://api.sevalla.com/v2/openapi.json put /static-sites/{id} Update properties or settings of an existing static site. # Create API key Source: https://api-docs.sevalla.com/v3/api-keys/create-api-key https://api.sevalla.com/v3/openapi.json post /api-keys Create a new API key with the specified roles and/or capabilities. The response includes the raw token value, which is only shown once - make sure to store it securely. At least one role or capability must be provided. # Delete API key Source: https://api-docs.sevalla.com/v3/api-keys/delete-api-key https://api.sevalla.com/v3/openapi.json delete /api-keys/{id} Permanently delete an API key. This immediately revokes all access for this key and cannot be undone. An API key cannot delete itself. # Get API key Source: https://api-docs.sevalla.com/v3/api-keys/get-api-key https://api.sevalla.com/v3/openapi.json get /api-keys/{id} Retrieve the full details of a single API key including its roles, capabilities, and usage metadata. The token value is masked for security. # Get current API key Source: https://api-docs.sevalla.com/v3/api-keys/get-current-api-key https://api.sevalla.com/v3/openapi.json get /api-keys/me Retrieve the details of the API key used to authenticate the current request, including a unified list of its effective capabilities (the permissions from its roles merged with its custom capabilities). Use this to discover what the calling key is allowed to do without knowing its ID. Any valid API key can call this endpoint regardless of its permissions. The token value is masked for security. # List API keys Source: https://api-docs.sevalla.com/v3/api-keys/list-api-keys https://api.sevalla.com/v3/openapi.json get /api-keys Retrieve a paginated list of all API keys for the authenticated company. Results are ordered by creation date (newest first). Token values are masked for security. # Rotate API key Source: https://api-docs.sevalla.com/v3/api-keys/rotate-api-key https://api.sevalla.com/v3/openapi.json post /api-keys/{id}/rotate Generate a new token for an API key. The old token can optionally remain valid for a transition period (up to 168 hours) to allow graceful migration. The response includes the new raw token, which is only shown once. An API key cannot rotate itself. # Toggle API key Source: https://api-docs.sevalla.com/v3/api-keys/toggle-api-key https://api.sevalla.com/v3/openapi.json post /api-keys/{id}/toggle Enable or disable an API key. A disabled API key cannot be used for authentication until it is re-enabled. An API key cannot toggle itself. # Update API key Source: https://api-docs.sevalla.com/v3/api-keys/update-api-key https://api.sevalla.com/v3/openapi.json patch /api-keys/{id} Update an API key's name, roles, or capabilities. When roles or capabilities are provided, they fully replace the existing values. An API key cannot update itself. # Validate API key Source: https://api-docs.sevalla.com/v3/api-keys/validate-api-key https://api.sevalla.com/v3/openapi.json get /api-keys/validate Validate the provided API key and return its details including name, expiration, associated company, and current status. Use this endpoint to verify that an API key is valid and active before making other API calls. # Activate application Source: https://api-docs.sevalla.com/v3/applications/activate-application https://api.sevalla.com/v3/openapi.json post /applications/{id}/activate Activate a previously suspended application, restoring all processes to their running state. The operation is asynchronous - the application status will transition once activation completes. # Add application domain Source: https://api-docs.sevalla.com/v3/applications/add-application-domain https://api.sevalla.com/v3/openapi.json post /applications/{id}/domains Add a custom domain to an application. After adding, configure your DNS records as indicated in the response to complete domain verification. The domain status will transition from `verification` to `pointing` to `active` as DNS propagates. # Cancel deployment Source: https://api-docs.sevalla.com/v3/applications/cancel-deployment https://api.sevalla.com/v3/openapi.json post /applications/{id}/deployments/{deployment_id}/cancel Cancel a deployment that is currently in progress or waiting. Deployments in the `waiting` status are skipped immediately, while `inProgress` deployments are stopped mid-execution. Deployments that already finished (including ones whose build completed while the request was in flight) cannot be cancelled and return a 400. # Clone application Source: https://api-docs.sevalla.com/v3/applications/clone-application https://api.sevalla.com/v3/openapi.json post /applications/{id}/clone Create an identical copy of an existing application including its processes, environment variables, build settings, and configuration. The cloned application is created in a new namespace and an initial deployment is triggered automatically. # Create application Source: https://api-docs.sevalla.com/v3/applications/create-application https://api.sevalla.com/v3/openapi.json post /applications Create a new application from a Git repository or Docker image. The application is created with a default web process, auto deploy disabled, and an initial deployment is not triggered automatically - use the Deploy endpoint to start the first deployment. Auto deploy can be enabled later via the Update endpoint but only works with privateGit applications. # Create environment variable Source: https://api-docs.sevalla.com/v3/applications/create-environment-variable https://api.sevalla.com/v3/openapi.json post /applications/{id}/env-vars Create a new app-level environment variable for an application. The value is encrypted before storage. A deployment is required for the new variable to take effect. # Create private port Source: https://api-docs.sevalla.com/v3/applications/create-private-port https://api.sevalla.com/v3/openapi.json post /applications/{id}/private-ports Expose a private port on an application process. Private ports allow cluster-internal communication between services without external network access. The port is provisioned asynchronously after creation. # Create process Source: https://api-docs.sevalla.com/v3/applications/create-process https://api.sevalla.com/v3/openapi.json post /applications/{id}/processes Create a new process for an application. Each application can have at most one web process. The process is created with the specified resource type and scaling strategy. A deployment is required after creation for the new process to take effect. # Create TCP proxy Source: https://api-docs.sevalla.com/v3/applications/create-tcp-proxy https://api.sevalla.com/v3/openapi.json post /applications/{id}/tcp-proxies Create a public TCP proxy for an application process. The proxy gets its own public hostname and port, allowing direct TCP connections from the internet to the specified container port. The proxy is provisioned asynchronously after creation. # Delete application Source: https://api-docs.sevalla.com/v3/applications/delete-application https://api.sevalla.com/v3/openapi.json delete /applications/{id} Permanently delete an application and all of its associated resources including processes, deployments, and environment variables. This operation is irreversible and cannot be performed while a deployment is in progress. # Delete application domain Source: https://api-docs.sevalla.com/v3/applications/delete-application-domain https://api.sevalla.com/v3/openapi.json delete /applications/{id}/domains/{domain_id} Remove a custom domain from an application. System domains cannot be deleted - use the toggle endpoint to disable them instead. This action cannot be undone. # Delete environment variable Source: https://api-docs.sevalla.com/v3/applications/delete-environment-variable https://api.sevalla.com/v3/openapi.json delete /applications/{id}/env-vars/{env_var_id} Delete an app-level environment variable. A deployment is required for the removal to take effect. # Delete private port Source: https://api-docs.sevalla.com/v3/applications/delete-private-port https://api.sevalla.com/v3/openapi.json delete /applications/{id}/private-ports/{private_port_id} Remove a private port from an application. The port is no longer accessible for cluster-internal communication after deletion. The port configuration is synchronized asynchronously. # Delete process Source: https://api-docs.sevalla.com/v3/applications/delete-process https://api.sevalla.com/v3/openapi.json delete /applications/{id}/processes/{process_id} Delete a non-web process from an application. The web process cannot be deleted. Deletion is performed asynchronously - the process is queued for removal and will be fully deleted after the next deployment. # Delete TCP proxy Source: https://api-docs.sevalla.com/v3/applications/delete-tcp-proxy https://api.sevalla.com/v3/openapi.json delete /applications/{id}/tcp-proxies/{tcp_proxy_id} Delete a public TCP proxy from an application. The external port and hostname are released immediately. The port configuration is synchronized asynchronously after deletion. # Disable deployment hook Source: https://api-docs.sevalla.com/v3/applications/disable-deployment-hook https://api.sevalla.com/v3/openapi.json delete /applications/{id}/deployment-hook Disable the deployment hook for an application. The existing hook URL will stop working immediately. A new secret is generated if the hook is re-enabled later. # Enable deployment hook Source: https://api-docs.sevalla.com/v3/applications/enable-deployment-hook https://api.sevalla.com/v3/openapi.json post /applications/{id}/deployment-hook Enable the deployment hook for an application. Returns a unique URL that can be called via HTTP POST to trigger a deployment. If the hook is already enabled, the existing URL is returned. # Get application Source: https://api-docs.sevalla.com/v3/applications/get-application https://api.sevalla.com/v3/openapi.json get /applications/{id} Retrieve the full details of an application including its source configuration, build settings, and current status. # Get application access logs Source: https://api-docs.sevalla.com/v3/applications/get-application-access-logs https://api.sevalla.com/v3/openapi.json get /applications/{id}/access-logs Retrieve HTTP access logs for an application. These are logs of incoming requests handled by the application. Use the `filters` parameter for advanced filtering by severity, message content, tags, or attributes. # Get application average response time Source: https://api-docs.sevalla.com/v3/applications/get-application-average-response-time https://api.sevalla.com/v3/openapi.json get /applications/{id}/metrics/response-time-avg Retrieve the average response time in milliseconds for an application over the specified time range. Returns a single aggregated value rather than a time series. # Get application deployment logs Source: https://api-docs.sevalla.com/v3/applications/get-application-deployment-logs https://api.sevalla.com/v3/openapi.json get /applications/{id}/deployments/{deployment_id}/logs Retrieve build and deployment logs for a specific deployment. These include output from the build process and rollout steps. Use the `filters` parameter for advanced filtering by severity, message content, tags, or attributes. # Get application domain Source: https://api-docs.sevalla.com/v3/applications/get-application-domain https://api.sevalla.com/v3/openapi.json get /applications/{id}/domains/{domain_id} Retrieve the details of a specific domain associated with an application, including its verification status, DNS records, and configuration. # Get application repository Source: https://api-docs.sevalla.com/v3/applications/get-application-repository https://api.sevalla.com/v3/openapi.json get /applications/{id}/repository Retrieve metadata about the Git repository connected to an application: the source type, Git provider, repository URL, default branch, and the commit currently running (from the latest successful deployment). Call this first to discover the deployed commit SHA, then pass it as the `ref` to the tree and contents endpoints to inspect exactly the code that is running. Only applications with a `privateGit` or `publicGit` source have a repository; `dockerImage` and internally created apps return 422. # Get application requests per minute Source: https://api-docs.sevalla.com/v3/applications/get-application-requests-per-minute https://api.sevalla.com/v3/openapi.json get /applications/{id}/metrics/requests-per-minute Retrieve a time series of requests per minute for an application. Returns data points at the specified interval, useful for monitoring traffic patterns and detecting spikes. # Get application response time Source: https://api-docs.sevalla.com/v3/applications/get-application-response-time https://api.sevalla.com/v3/openapi.json get /applications/{id}/metrics/response-time Retrieve a time series of response times for an application. Use the optional `percent` parameter to get a specific percentile (e.g., p95 or p99) instead of the default. # Get application runtime logs Source: https://api-docs.sevalla.com/v3/applications/get-application-runtime-logs https://api.sevalla.com/v3/openapi.json get /applications/{id}/runtime-logs Retrieve runtime logs for an application. These are logs produced by the running application processes (stdout/stderr). Use the `filters` parameter for advanced filtering by severity, message content, tags, or attributes. # Get application slowest requests Source: https://api-docs.sevalla.com/v3/applications/get-application-slowest-requests https://api.sevalla.com/v3/openapi.json get /applications/{id}/metrics/slowest-requests Retrieve the slowest request paths for an application, ranked by average response time. Each entry includes the HTTP method, path, average response time, and total request count. # Get application status code breakdown Source: https://api-docs.sevalla.com/v3/applications/get-application-status-code-breakdown https://api.sevalla.com/v3/openapi.json get /applications/{id}/metrics/status-codes Retrieve a time series showing the breakdown of HTTP response status codes for an application. Each data point includes a map of status codes to their request counts. # Get application top countries Source: https://api-docs.sevalla.com/v3/applications/get-application-top-countries https://api.sevalla.com/v3/openapi.json get /applications/{id}/metrics/top-countries Retrieve the countries generating the most traffic to an application, ranked by total request count. Each entry includes the country code, average response time, and total requests. # Get application top pages Source: https://api-docs.sevalla.com/v3/applications/get-application-top-pages https://api.sevalla.com/v3/openapi.json get /applications/{id}/metrics/top-pages Retrieve the most visited pages for an application, ranked by total request count. Useful for understanding which endpoints or pages receive the most traffic. # Get application top status codes Source: https://api-docs.sevalla.com/v3/applications/get-application-top-status-codes https://api.sevalla.com/v3/openapi.json get /applications/{id}/metrics/top-status-codes Retrieve the most common HTTP response status codes for an application, ranked by total request count. Useful for identifying error rates and common response patterns. # Get deployment Source: https://api-docs.sevalla.com/v3/applications/get-deployment https://api.sevalla.com/v3/openapi.json get /applications/{id}/deployments/{deployment_id} Retrieve the full details of a specific deployment including its current status, pipeline steps, Git source information, and timestamps. # Get deployment hook URL Source: https://api-docs.sevalla.com/v3/applications/get-deployment-hook-url https://api.sevalla.com/v3/openapi.json get /applications/{id}/deployment-hook Retrieve the deployment hook URL for an application. Returns 404 if no deployment hook is currently enabled. # Get egress IPs Source: https://api-docs.sevalla.com/v3/applications/get-egress-ips https://api.sevalla.com/v3/openapi.json get /applications/{id}/egress-ips Retrieve the IP addresses that outbound connections from an application can originate from, for example to allow the application through a firewall in front of an external database or API. The result depends on the cluster the application runs on. # Get IP restriction Source: https://api-docs.sevalla.com/v3/applications/get-ip-restriction https://api.sevalla.com/v3/openapi.json get /applications/{id}/ip-restriction Retrieve the current IP restriction configuration for an application. Returns the restriction type, whether it is active, and the list of IP addresses or CIDR ranges. If no restriction has been configured, returns a default state with type `deny`, disabled, and an empty IP list. # Get maintenance mode Source: https://api-docs.sevalla.com/v3/applications/get-maintenance-mode https://api.sevalla.com/v3/openapi.json get /applications/{id}/maintenance-mode Retrieve the maintenance mode configuration for an application. Returns whether maintenance mode is active and the URL of the custom maintenance page, if one is set. If maintenance mode has never been configured, returns a default state with `is_enabled` false and `page_url` null. # Get process Source: https://api-docs.sevalla.com/v3/applications/get-process https://api.sevalla.com/v3/openapi.json get /applications/{id}/processes/{process_id} Retrieve the full details of a specific process including its runtime configuration, scaling strategy, resource limits, and probe settings. # Get process CPU limit Source: https://api-docs.sevalla.com/v3/applications/get-process-cpu-limit https://api.sevalla.com/v3/openapi.json get /applications/{id}/processes/{process_id}/metrics/cpu-limit Retrieve a time series of CPU limits for a specific application process. Returns data points at the specified interval showing the configured CPU limit in cores. # Get process CPU usage Source: https://api-docs.sevalla.com/v3/applications/get-process-cpu-usage https://api.sevalla.com/v3/openapi.json get /applications/{id}/processes/{process_id}/metrics/cpu-usage Retrieve a time series of CPU usage for a specific application process. Returns data points at the specified interval showing actual CPU consumption in cores. # Get process exit codes Source: https://api-docs.sevalla.com/v3/applications/get-process-exit-codes https://api.sevalla.com/v3/openapi.json get /applications/{id}/processes/{process_id}/metrics/exit-codes Retrieve exit codes for a specific application process within a time range. Returns each exit code event with a timestamp and a human-readable description when available. # Get process instance count Source: https://api-docs.sevalla.com/v3/applications/get-process-instance-count https://api.sevalla.com/v3/openapi.json get /applications/{id}/processes/{process_id}/metrics/instance-count Retrieve a time series of running instance counts for a specific application process. Returns data points at the specified interval showing the number of active replicas. # Get process memory limit Source: https://api-docs.sevalla.com/v3/applications/get-process-memory-limit https://api.sevalla.com/v3/openapi.json get /applications/{id}/processes/{process_id}/metrics/memory-limit Retrieve a time series of memory limits for a specific application process. Returns data points at the specified interval showing the configured memory limit in bytes. # Get process memory usage Source: https://api-docs.sevalla.com/v3/applications/get-process-memory-usage https://api.sevalla.com/v3/openapi.json get /applications/{id}/processes/{process_id}/metrics/memory-usage Retrieve a time series of memory usage for a specific application process. Returns data points at the specified interval showing actual memory consumption in bytes. # Get rate limit Source: https://api-docs.sevalla.com/v3/applications/get-rate-limit https://api.sevalla.com/v3/openapi.json get /applications/{id}/rate-limit Retrieve the current rate limiting configuration for an application. Rate limiting restricts each client IP to 100 requests per minute per hostname and applies the configured action when the limit is exceeded. If rate limiting has never been configured, returns the default state: disabled with the `challenge` action. # List application domains Source: https://api-docs.sevalla.com/v3/applications/list-application-domains https://api.sevalla.com/v3/openapi.json get /applications/{id}/domains Retrieve a paginated list of all domains (both system and custom) associated with an application. System domains are assigned automatically, while custom domains are added by users. # List application repository tree Source: https://api-docs.sevalla.com/v3/applications/list-application-repository-tree https://api.sevalla.com/v3/openapi.json get /applications/{id}/repository/tree List files and directories in the application Git repository at a given ref. Use this to discover the repository structure before reading individual files. Defaults to reading the commit of the latest successful deployment so you see exactly the code that is running. Only applications with a `privateGit` or `publicGit` source have a repository; `dockerImage` and internally created apps return 422. # List applications Source: https://api-docs.sevalla.com/v3/applications/list-applications https://api.sevalla.com/v3/openapi.json get /applications Retrieve a paginated list of all applications the authenticated API key has access to. Results are ordered by name and can be paginated using the `limit` and `offset` query parameters. Use the `status`, `source`, `project_id`, and `search` query parameters to narrow down the results - multiple filters combine with AND. # List deployments Source: https://api-docs.sevalla.com/v3/applications/list-deployments https://api.sevalla.com/v3/openapi.json get /applications/{id}/deployments Retrieve a paginated list of all deployments for an application, ordered by most recent first. Each deployment includes its status, source details, and timestamps. # List environment variables Source: https://api-docs.sevalla.com/v3/applications/list-environment-variables https://api.sevalla.com/v3/openapi.json get /applications/{id}/env-vars Retrieve a paginated list of all app-level environment variables for an application. Values are returned decrypted. Variables are ordered by creation time. # List private ports Source: https://api-docs.sevalla.com/v3/applications/list-private-ports https://api.sevalla.com/v3/openapi.json get /applications/{id}/private-ports Retrieve a paginated list of private ports for an application. Private ports expose internal container ports for cluster-internal communication between services, without any external network access. # List processes Source: https://api-docs.sevalla.com/v3/applications/list-processes https://api.sevalla.com/v3/openapi.json get /applications/{id}/processes Retrieve a paginated list of all processes for an application, ordered by their display order and creation time. Each process includes its runtime configuration, scaling strategy, and resource limits. # List TCP proxies Source: https://api-docs.sevalla.com/v3/applications/list-tcp-proxies https://api.sevalla.com/v3/openapi.json get /applications/{id}/tcp-proxies Retrieve a paginated list of public TCP proxies for an application. TCP proxies expose an internal container port on a public hostname and port, allowing direct TCP connections from the internet. # Open terminal session (WebSocket) Source: https://api-docs.sevalla.com/v3/applications/open-terminal-session-websocket https://api.sevalla.com/v3/openapi.json get /applications/{id}/processes/{process_id}/terminal Open an interactive terminal (shell) session to a running application process. **This is a WebSocket endpoint.** Connect using a WebSocket client with the `Upgrade: websocket` header. Standard HTTP requests return a `426 Upgrade Required` response. ### Connection ``` wscat -c "wss://api.sevalla.com/v3/applications/{id}/processes/{process_id}/terminal?shell=bash" -H "Authorization: Bearer " ``` Authentication runs before the WebSocket upgrade - invalid credentials are rejected with a standard HTTP 401/403 response. ### Communication Once connected, the WebSocket streams stdin/stdout bidirectionally to a shell running inside the container. Send text messages as shell input and receive command output as text messages. ### Close codes - `4000` - Application or process not found - `4001` - No running pod available to connect to - `4002` - Shell stream error - `4003` - Shell stream closed normally - `4005` - Failed to connect to the pod - `4300` - Unexpected server error # Purge edge cache Source: https://api-docs.sevalla.com/v3/applications/purge-edge-cache https://api.sevalla.com/v3/openapi.json post /applications/{id}/purge-cache Purge the edge cache for an application, removing all cached content. Use this when you need cached resources to be refreshed immediately without waiting for the cache TTL to expire. # Read application repository file Source: https://api-docs.sevalla.com/v3/applications/read-application-repository-file https://api.sevalla.com/v3/openapi.json get /applications/{id}/repository/contents Read the contents of a single file from the application Git repository at a given ref. Defaults to the commit of the latest successful deployment so you read exactly the code that is running. Binary files and files larger than 1 MB return metadata only with a null `content` (check `is_binary` and `truncated`). Returns 404 when the file does not exist at the ref. Only applications with a `privateGit` or `publicGit` source have a repository; `dockerImage` and internally created apps return 422. # Refresh application domain status Source: https://api-docs.sevalla.com/v3/applications/refresh-application-domain-status https://api.sevalla.com/v3/openapi.json post /applications/{id}/domains/{domain_id}/refresh-status Trigger a re-check of the domain verification and DNS pointing status. Use this after updating your DNS records to speed up the verification process. # Regenerate deployment hook Source: https://api-docs.sevalla.com/v3/applications/regenerate-deployment-hook https://api.sevalla.com/v3/openapi.json put /applications/{id}/deployment-hook Regenerate the deployment hook secret for an application. The previous hook URL will stop working immediately and a new URL is returned. Use this if the current hook secret has been compromised. # Rollback deployment Source: https://api-docs.sevalla.com/v3/applications/rollback-deployment https://api.sevalla.com/v3/openapi.json post /applications/{id}/deployments/rollback Roll back an application to the most recent successful deployment. This creates a new deployment that reuses the build artifact from the previous successful deployment, skipping the build step entirely. # Run a command in a process Source: https://api-docs.sevalla.com/v3/applications/run-a-command-in-a-process https://api.sevalla.com/v3/openapi.json post /applications/{id}/processes/{process_id}/exec Run a single command inside a running application process (container) and return its output. This is a non-interactive alternative to the WebSocket terminal: one command runs, and its stdout, stderr, and exit code are returned. The command runs directly without a shell, so pipes, redirects, and command chaining do not apply. This endpoint requires at least read access to the application. A key with only read access can run read-only commands (such as `ls`, `cat`, `env`, `ps`, `grep`); a request to run any other command is rejected with a 403. A key with write access to the application can run any command. Note that the read-only restriction is a convenience to prevent accidental changes, not a security sandbox: read-only commands can still read environment variables and files inside the container. # Search application repository code Source: https://api-docs.sevalla.com/v3/applications/search-application-repository-code https://api.sevalla.com/v3/openapi.json get /applications/{id}/repository/search Search the application Git repository for code matching a query, useful for locating where something is defined or used. Search runs against the provider index, which covers the default branch, so it does not accept a ref. Result quality varies by provider: it is strongest on GitHub and more limited on GitLab and Bitbucket. Only applications with a `privateGit` or `publicGit` source have a repository; `dockerImage` and internally created apps return 422. # Set primary application domain Source: https://api-docs.sevalla.com/v3/applications/set-primary-application-domain https://api.sevalla.com/v3/openapi.json post /applications/{id}/domains/{domain_id}/set-primary Set a domain as the primary domain for the application. The primary domain is used for canonical URLs and redirects. Only one domain can be primary at a time - the previously primary domain is automatically demoted. # Suspend application Source: https://api-docs.sevalla.com/v3/applications/suspend-application https://api.sevalla.com/v3/openapi.json post /applications/{id}/suspend Suspend a running application by stopping all of its processes. The application configuration, environment variables, and deployment history are preserved. Use the activate endpoint to restore the application. # Toggle application system domain Source: https://api-docs.sevalla.com/v3/applications/toggle-application-system-domain https://api.sevalla.com/v3/openapi.json post /applications/{id}/domains/{domain_id}/toggle Enable or disable a system domain for the application. When disabled, the system domain stops serving traffic. Only applies to system domains - custom domains cannot be toggled. # Toggle CDN Source: https://api-docs.sevalla.com/v3/applications/toggle-cdn https://api.sevalla.com/v3/openapi.json post /applications/{id}/cdn/toggle Toggle CDN on or off for an application. If CDN is currently enabled, it will be disabled, and vice versa. Returns the new CDN status after toggling. # Toggle edge cache Source: https://api-docs.sevalla.com/v3/applications/toggle-edge-cache https://api.sevalla.com/v3/openapi.json post /applications/{id}/edge-cache/toggle Toggle edge caching on or off for an application. If edge caching is currently enabled, it will be disabled, and vice versa. Returns the new edge caching status after toggling. # Trigger cron job Source: https://api-docs.sevalla.com/v3/applications/trigger-cron-job https://api.sevalla.com/v3/openapi.json post /applications/{id}/processes/{process_id}/trigger Manually trigger an immediate execution of a cron process. This creates a one-off run outside of the regular cron schedule. The process must be of type `cron`. # Trigger deployment Source: https://api-docs.sevalla.com/v3/applications/trigger-deployment https://api.sevalla.com/v3/openapi.json post /applications/{id}/deployments Trigger a new deployment for an application. By default, deploys the latest commit on the default branch. You can optionally specify a different branch, a Docker image, or restart from the last successful deployment. The deployment runs asynchronously - use the get deployment endpoint to track its progress. # Update application Source: https://api-docs.sevalla.com/v3/applications/update-application https://api.sevalla.com/v3/openapi.json patch /applications/{id} Update one or more properties of an existing application. Only include the fields you want to change - omitted fields are left unchanged. Changes to build settings take effect on the next deployment. Changing the source switches how the application is built and deployed - for example, from a Git repository to a Docker image. # Update application system domain Source: https://api-docs.sevalla.com/v3/applications/update-application-system-domain https://api.sevalla.com/v3/openapi.json patch /applications/{id}/domains/{domain_id} Update the subdomain name of a system domain. Only applies to system domains - use the add/delete endpoints to manage custom domains. # Update environment variable Source: https://api-docs.sevalla.com/v3/applications/update-environment-variable https://api.sevalla.com/v3/openapi.json put /applications/{id}/env-vars/{env_var_id} Update an existing app-level environment variable. You can change the key, value, or runtime/buildtime flags. A deployment is required for changes to take effect. # Update IP restriction Source: https://api-docs.sevalla.com/v3/applications/update-ip-restriction https://api.sevalla.com/v3/openapi.json put /applications/{id}/ip-restriction Update the IP restriction configuration for an application. Sets the restriction type (allow or deny), enables or disables it, and updates the list of IP addresses or CIDR ranges. When type is `allow`, only the listed IPs can access the application. When type is `deny`, the listed IPs are blocked. Returns the updated restriction state. # Update maintenance mode Source: https://api-docs.sevalla.com/v3/applications/update-maintenance-mode https://api.sevalla.com/v3/openapi.json put /applications/{id}/maintenance-mode Turn maintenance mode on or off for an application and optionally set a custom maintenance page URL. While enabled, every request to every domain of the application gets the maintenance page with status 503 and a Retry-After header instead of reaching the application. There are no path, method or visitor exceptions, and IP restrictions still apply first. The application keeps running and deployments still work. The change is written to the edge synchronously but can take up to 5 minutes to reach every location. Returns the updated state. # Update process Source: https://api-docs.sevalla.com/v3/applications/update-process https://api.sevalla.com/v3/openapi.json patch /applications/{id}/processes/{process_id} Update the configuration of an existing process. Only the provided fields are changed - all other fields retain their current values. Changes to resource type, scaling, or probes take effect on the next deployment. Protocol changes are applied asynchronously. # Update rate limit Source: https://api-docs.sevalla.com/v3/applications/update-rate-limit https://api.sevalla.com/v3/openapi.json put /applications/{id}/rate-limit Update the rate limiting configuration for an application. Rate limiting restricts each client IP to 100 requests per minute per hostname across the application domains. When a client exceeds the limit, the configured action is applied: `challenge` requires the visitor to pass a managed challenge for 5 minutes, `throttle` blocks requests only while the rate stays above the limit, and `ban` blocks the client IP for 5 minutes. Changes are synced to the edge network as part of the request. Returns the updated rate limit state. # Authentication Source: https://api-docs.sevalla.com/v3/authentication How to authenticate with the Sevalla API using Bearer tokens. Every request to the Sevalla API must include a valid API key in the `Authorization` header. ## Get an API key Go to [API Keys](https://app.sevalla.com/api-keys) in your Sevalla dashboard. Click **Create API Key**, give it a name, and select the permissions it needs. You'll only see the full key once. Store it somewhere safe. ## Using the key Pass your API key as a Bearer token in the `Authorization` header: ```bash theme={null} curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.sevalla.com/v3/applications ``` All requests must use HTTPS. HTTP requests will be rejected. ## Scoped keys API keys can be scoped to specific permissions. Create a key with only the access it needs, for example read-only for monitoring or deploy-only for CI pipelines. You can [manage keys through the API](/v3/api-keys/list-api-keys) or from the dashboard. Create a separate API key for each integration or environment. If a key is compromised, you can rotate or revoke it without affecting your other tools. ## Error responses If authentication fails, you'll get one of these responses: | Status | Meaning | | - | - | | `401 Unauthorized` | Missing or invalid API key. Check that your `Authorization` header is formatted correctly. | | `403 Forbidden` | The API key is valid but doesn't have permission for this action. Create a key with broader scope or contact your team admin. | # CLI Source: https://api-docs.sevalla.com/v3/cli Install and use the Sevalla CLI to manage your infrastructure from the terminal. The Sevalla CLI lets you deploy applications, manage databases, configure domains, monitor metrics, and more without leaving your terminal. ## Installation ```bash theme={null} brew install sevalla-hosting/tap/sevalla ``` Requires Node.js 22 or later. ```bash theme={null} npm install -g @sevalla/cli ``` ```bash theme={null} bash <(curl -fsSL https://raw.githubusercontent.com/sevalla-hosting/cli/main/install.sh) ``` Windows binaries are available on the [releases page](https://github.com/sevalla-hosting/cli/releases). ## Authentication ### Interactive login The `login` command opens your browser and authenticates via device authorization. No need to copy-paste tokens. ```bash theme={null} sevalla login ``` Check your current authentication status or log out: ```bash theme={null} sevalla auth status sevalla logout ``` Credentials are stored at `~/.config/sevalla/credentials.json` with `0600` permissions. ### API token (CI/CD) For non-interactive environments, set the `SEVALLA_API_TOKEN` environment variable: ```bash theme={null} export SEVALLA_API_TOKEN="your-api-token" sevalla apps list ``` Generate tokens from the [dashboard](https://app.sevalla.com/api-keys) or with the CLI: ```bash theme={null} sevalla api-keys create --name "CI Token" ``` ## Quick start ```bash theme={null} # Log in sevalla login # List your applications sevalla apps list # Trigger a deployment sevalla apps deployments trigger --branch main # View runtime logs sevalla apps logs runtime ``` ## Commands ### Applications ```bash theme={null} sevalla apps list # List all applications sevalla apps get # Get application details sevalla apps create --name myapp --source privateGit --cluster sevalla apps update --display-name "My App" sevalla apps delete sevalla apps activate # Activate a suspended app sevalla apps suspend # Suspend an app sevalla apps clone --display-name "Clone" --cluster sevalla apps purge-cache # Clear application cache sevalla apps cdn-toggle # Toggle CDN on/off ``` ### Deployments ```bash theme={null} sevalla apps deployments list --app-id sevalla apps deployments get --app-id sevalla apps deployments trigger --branch main sevalla apps deployments rollback --deployment-id sevalla apps deployments cancel --app-id sevalla apps deployments logs --app-id ``` ### Deployment hooks ```bash theme={null} sevalla apps deployment-hook get sevalla apps deployment-hook enable sevalla apps deployment-hook disable sevalla apps deployment-hook regenerate ``` ### Processes ```bash theme={null} sevalla apps processes list --app-id sevalla apps processes get --app-id sevalla apps processes create --name web --type web sevalla apps processes update --app-id --instances 3 sevalla apps processes delete --app-id sevalla apps processes trigger --app-id ``` ### Domains ```bash theme={null} sevalla apps domains list --app-id sevalla apps domains add --name example.com sevalla apps domains get --app-id sevalla apps domains update --app-id sevalla apps domains delete sevalla apps domains set-primary sevalla apps domains toggle sevalla apps domains refresh-status ``` ### Environment variables ```bash theme={null} sevalla apps env-vars list --app-id sevalla apps env-vars create --key MY_VAR --value "my value" sevalla apps env-vars update --app-id --value "new value" sevalla apps env-vars delete ``` ### Networking ```bash theme={null} # IP restrictions sevalla apps ip-restriction get sevalla apps ip-restriction update --type allow --ip-list "1.2.3.4,5.6.7.8" # TCP proxies sevalla apps tcp-proxies list --app-id sevalla apps tcp-proxies create --port 3000 sevalla apps tcp-proxies delete # Private ports sevalla apps private-ports list --app-id sevalla apps private-ports create --port 8080 --protocol TCP sevalla apps private-ports delete ``` ### Logs ```bash theme={null} sevalla apps logs runtime sevalla apps logs access ``` ### Metrics ```bash theme={null} sevalla apps metrics requests-per-minute sevalla apps metrics response-time sevalla apps metrics response-time-avg sevalla apps metrics status-codes sevalla apps metrics top-status-codes sevalla apps metrics top-countries sevalla apps metrics slowest-requests sevalla apps metrics top-pages # Process metrics sevalla apps processes metrics cpu-usage sevalla apps processes metrics cpu-limit sevalla apps processes metrics memory-usage sevalla apps processes metrics memory-limit sevalla apps processes metrics instance-count ``` ### Databases ```bash theme={null} sevalla databases list sevalla databases get sevalla databases create --name mydb --type postgresql --db-version 16 --cluster --resource-type --db-name mydb --db-password secret sevalla databases update --display-name "My DB" sevalla databases delete sevalla databases activate sevalla databases suspend sevalla databases reset-password ``` #### Backups ```bash theme={null} sevalla databases backups list --db-id sevalla databases backups create sevalla databases backups delete sevalla databases backups restore ``` #### Connections ```bash theme={null} sevalla databases connections internal-list --db-id sevalla databases connections internal-create --application-id sevalla databases connections internal-delete sevalla databases connections external-toggle ``` #### Database metrics ```bash theme={null} sevalla databases metrics cpu-usage sevalla databases metrics cpu-limit sevalla databases metrics memory-usage sevalla databases metrics memory-limit sevalla databases metrics storage-usage sevalla databases metrics storage-limit sevalla databases metrics all-storage sevalla databases metrics used-storage ``` #### Database IP restriction ```bash theme={null} sevalla databases ip-restriction get sevalla databases ip-restriction update ``` ### Static sites ```bash theme={null} sevalla static-sites list sevalla static-sites get sevalla static-sites create --name mysite --repository user/repo --branch main sevalla static-sites update --display-name "My Site" sevalla static-sites delete sevalla static-sites purge-cache ``` #### Static site deployments ```bash theme={null} sevalla static-sites deployments list --site-id sevalla static-sites deployments get --site-id sevalla static-sites deployments trigger --branch main sevalla static-sites deployments cancel --site-id sevalla static-sites deployments logs --site-id ``` #### Static site domains ```bash theme={null} sevalla static-sites domains list --site-id sevalla static-sites domains get --site-id sevalla static-sites domains add --name example.com sevalla static-sites domains update --site-id sevalla static-sites domains delete sevalla static-sites domains set-primary sevalla static-sites domains toggle sevalla static-sites domains refresh-status ``` #### Static site environment variables ```bash theme={null} sevalla static-sites env-vars list --site-id sevalla static-sites env-vars create --key MY_VAR --value "my value" sevalla static-sites env-vars update --site-id sevalla static-sites env-vars delete ``` #### Static site logs and metrics ```bash theme={null} sevalla static-sites logs access sevalla static-sites metrics requests-per-minute sevalla static-sites metrics response-time sevalla static-sites metrics response-time-avg sevalla static-sites metrics status-codes sevalla static-sites metrics top-status-codes sevalla static-sites metrics top-countries sevalla static-sites metrics slowest-requests sevalla static-sites metrics top-pages ``` ### Load balancers ```bash theme={null} sevalla load-balancers list sevalla load-balancers get sevalla load-balancers create --name "My LB" --cluster sevalla load-balancers update --display-name "Updated LB" sevalla load-balancers delete # Destinations sevalla load-balancers destinations list --lb-id sevalla load-balancers destinations create --application-id sevalla load-balancers destinations delete sevalla load-balancers destinations toggle # Domains sevalla load-balancers domains list --lb-id sevalla load-balancers domains add --name example.com sevalla load-balancers domains delete sevalla load-balancers domains set-primary sevalla load-balancers domains toggle sevalla load-balancers domains refresh-status ``` ### Object storage ```bash theme={null} sevalla object-storage list sevalla object-storage get sevalla object-storage create --name mybucket --cluster sevalla object-storage update --display-name "My Bucket" sevalla object-storage delete # Objects sevalla object-storage objects list --storage-id sevalla object-storage objects delete --storage-id # CORS policies sevalla object-storage cors-policies list --storage-id sevalla object-storage cors-policies create sevalla object-storage cors-policies update --storage-id sevalla object-storage cors-policies delete # CDN domain sevalla object-storage domain create sevalla object-storage domain delete ``` ### Pipelines ```bash theme={null} sevalla pipelines list sevalla pipelines get sevalla pipelines create --name "My Pipeline" sevalla pipelines update --display-name "Updated Pipeline" sevalla pipelines delete sevalla pipelines promote # Preview sevalla pipelines preview update sevalla pipelines preview enable sevalla pipelines preview disable # Stages sevalla pipelines stages create sevalla pipelines stages delete sevalla pipelines stages add-app --application-id sevalla pipelines stages remove-app ``` ### Projects ```bash theme={null} sevalla projects list sevalla projects get sevalla projects create --name "My Project" sevalla projects update --display-name "Updated Project" sevalla projects delete sevalla projects add-service --service-id sevalla projects remove-service ``` ### Docker registries ```bash theme={null} sevalla docker-registries list sevalla docker-registries get sevalla docker-registries create --name "My Registry" --url registry.example.com --username user --password secret sevalla docker-registries update --display-name "Updated Registry" sevalla docker-registries delete ``` ### Webhooks ```bash theme={null} sevalla webhooks list sevalla webhooks get sevalla webhooks create --name "My Webhook" --url https://example.com/hook --events "deployment.started,deployment.completed" sevalla webhooks update sevalla webhooks delete sevalla webhooks toggle sevalla webhooks roll-secret # Deliveries sevalla webhooks deliveries list --webhook-id sevalla webhooks deliveries get --webhook-id ``` ### API keys ```bash theme={null} sevalla api-keys list sevalla api-keys get sevalla api-keys create --name "My Key" sevalla api-keys update --name "Updated Key" sevalla api-keys delete sevalla api-keys rotate sevalla api-keys toggle sevalla api-keys validate ``` ### Global environment variables ```bash theme={null} sevalla global-env-vars list sevalla global-env-vars create --key GLOBAL_VAR --value "value" sevalla global-env-vars update --value "new value" sevalla global-env-vars delete ``` ### Resources ```bash theme={null} sevalla resources clusters # List available clusters sevalla resources database-resource-types # List database resource types sevalla resources process-resource-types # List process resource types sevalla resources git-providers # List Git providers ``` ## Global flags Every command supports these flags: | Flag | Description | | - | - | | `--json` | Output structured JSON for scripting and CI/CD pipelines. | | `--api-url ` | Override the default API endpoint. | | `--confirm` | Skip confirmation prompts for destructive actions. | | `--version` | Display the CLI version. | | `--help` | Show help for any command. | ```bash theme={null} # Example: pipe JSON output to jq sevalla apps list --json | jq '.[].name' ``` ## Shell completions Enable tab completions for your shell: ```bash theme={null} eval "$(sevalla completion bash)" ``` ```bash theme={null} eval "$(sevalla completion zsh)" ``` ```bash theme={null} sevalla completion fish | source ``` Add the command to your shell profile to enable completions in every session. ## Environment variables | Variable | Description | | - | - | | `SEVALLA_API_TOKEN` | API token for authentication. Overrides stored credentials from `sevalla login`. | | `SEVALLA_API_URL` | Override the default API endpoint. | # Activate database Source: https://api-docs.sevalla.com/v3/databases/activate-database https://api.sevalla.com/v3/openapi.json post /databases/{id}/activate Activate a previously suspended database, restoring it to a running state. The operation is asynchronous - the database status will transition once activation completes. # Create database Source: https://api-docs.sevalla.com/v3/databases/create-database https://api.sevalla.com/v3/openapi.json post /databases Create a new database on a specified cluster. The database is provisioned asynchronously - the initial status will be `creating` and will transition to `ready` once provisioning completes. # Create database backup Source: https://api-docs.sevalla.com/v3/databases/create-database-backup https://api.sevalla.com/v3/openapi.json post /databases/{id}/backups Create a manual backup of a database. The backup is created asynchronously and will appear in the backup list once completed. Manual backups have a 14-day retention period. Not available on OCI clusters - those use external backups and this endpoint returns a 400 there. # Create internal connection Source: https://api-docs.sevalla.com/v3/databases/create-internal-connection https://api.sevalla.com/v3/openapi.json post /databases/{id}/internal-connections Create an internal connection from this database to another service (application or database). Both services must be in the same cluster. The target application does not need to be deployed yet - you can connect a database before the first deployment. The database from the URL path is always the source of the connection. Connections are bidirectional, so only one connection can exist between a given pair of services - creating it again in either direction returns 409. A database cannot be connected to itself. # Delete database Source: https://api-docs.sevalla.com/v3/databases/delete-database https://api.sevalla.com/v3/openapi.json delete /databases/{id} Permanently delete a database and all of its data. This operation is irreversible and cannot be performed while the database status is creating, deleting, updating, or when a backup is in progress. # Delete database backup Source: https://api-docs.sevalla.com/v3/databases/delete-database-backup https://api.sevalla.com/v3/openapi.json delete /databases/{id}/backups/{backup_id} Delete a specific database backup by its unique name. The deletion is processed asynchronously. # Delete internal connection Source: https://api-docs.sevalla.com/v3/databases/delete-internal-connection https://api.sevalla.com/v3/openapi.json delete /databases/{id}/internal-connections/{connection_id} Delete an internal connection associated with this database. The connection must belong to this database (either as source or target). # Get database Source: https://api-docs.sevalla.com/v3/databases/get-database https://api.sevalla.com/v3/openapi.json get /databases/{id} Retrieve the full details of a database including connection hostnames, cluster information, and current status. # Get database CPU limit Source: https://api-docs.sevalla.com/v3/databases/get-database-cpu-limit https://api.sevalla.com/v3/openapi.json get /databases/{id}/metrics/cpu-limit Retrieve a time series of CPU limits for a database. Returns data points at the specified interval showing the configured CPU limit in cores. # Get database CPU usage Source: https://api-docs.sevalla.com/v3/databases/get-database-cpu-usage https://api.sevalla.com/v3/openapi.json get /databases/{id}/metrics/cpu-usage Retrieve a time series of CPU usage for a database. Returns data points at the specified interval showing actual CPU consumption in cores. # Get database IP restriction Source: https://api-docs.sevalla.com/v3/databases/get-database-ip-restriction https://api.sevalla.com/v3/openapi.json get /databases/{id}/ip-restriction Retrieve the current IP restriction configuration for a database. Returns the restriction type, whether it is active, and the list of IP addresses or CIDR ranges. If no restriction has been configured, returns a default state with type `deny`, disabled, and an empty IP list. # Get database memory limit Source: https://api-docs.sevalla.com/v3/databases/get-database-memory-limit https://api.sevalla.com/v3/openapi.json get /databases/{id}/metrics/memory-limit Retrieve a time series of memory limits for a database. Returns data points at the specified interval showing the configured memory limit in bytes. # Get database memory usage Source: https://api-docs.sevalla.com/v3/databases/get-database-memory-usage https://api.sevalla.com/v3/openapi.json get /databases/{id}/metrics/memory-usage Retrieve a time series of memory usage for a database. Returns data points at the specified interval showing actual memory consumption in bytes. # Get database storage limit Source: https://api-docs.sevalla.com/v3/databases/get-database-storage-limit https://api.sevalla.com/v3/openapi.json get /databases/{id}/metrics/storage-limit Retrieve a time series of storage limits for a database. Returns data points at the specified interval showing the configured storage limit in bytes. # Get database storage usage Source: https://api-docs.sevalla.com/v3/databases/get-database-storage-usage https://api.sevalla.com/v3/openapi.json get /databases/{id}/metrics/storage-usage Retrieve a time series of storage usage for a database. Returns data points at the specified interval showing actual disk consumption in bytes. # Get database total storage Source: https://api-docs.sevalla.com/v3/databases/get-database-total-storage https://api.sevalla.com/v3/openapi.json get /databases/{id}/metrics/all-storage Retrieve the current total allocated storage for a database. Returns a single point-in-time value in bytes. # Get database used storage Source: https://api-docs.sevalla.com/v3/databases/get-database-used-storage https://api.sevalla.com/v3/openapi.json get /databases/{id}/metrics/used-storage Retrieve the current used storage for a database. Returns a single point-in-time value in bytes. # List database backups Source: https://api-docs.sevalla.com/v3/databases/list-database-backups https://api.sevalla.com/v3/openapi.json get /databases/{id}/backups Retrieve all backups for a database, including both automatic daily backups and user-created manual backups. Daily backups have a 7-day retention period and manual backups have a 14-day retention period. Use the optional type filter to retrieve only daily or manual backups. # List databases Source: https://api-docs.sevalla.com/v3/databases/list-databases https://api.sevalla.com/v3/openapi.json get /databases Retrieve a paginated list of all databases the authenticated API key has access to. Results are ordered by name and can be paginated using the `limit` and `offset` query parameters. Use the `status`, `type`, `project_id`, and `search` query parameters to narrow down the results - multiple filters combine with AND. # List internal connections Source: https://api-docs.sevalla.com/v3/databases/list-internal-connections https://api.sevalla.com/v3/openapi.json get /databases/{id}/internal-connections Retrieve all internal connections for a database. Internal connections allow services within the same cluster to communicate with each other. Returns connections where this database is either the source or target. # Reset database password Source: https://api-docs.sevalla.com/v3/databases/reset-database-password https://api.sevalla.com/v3/openapi.json post /databases/{id}/reset-password Reset the password for a database. The operation is asynchronous - the database status will change to `passwordChange` during the process and transition back to `ready` once complete. # Restart database Source: https://api-docs.sevalla.com/v3/databases/restart-database https://api.sevalla.com/v3/openapi.json post /databases/{id}/restart Restart the database. The database configuration and stored data are preserved. The operation is asynchronous - the database status transitions to `updating` while the restart is in progress and back to `ready` once it completes. Allowed only when the database status is `ready`, `error`, `passwordChangeFailed`, or `restoringFailed`, the database is not suspended, and there is no backup in progress. # Restore database backup Source: https://api-docs.sevalla.com/v3/databases/restore-database-backup https://api.sevalla.com/v3/openapi.json post /databases/{id}/backups/{backup_id}/restore Restore a database from a specific backup. The restore operation is asynchronous - the database status will reflect the progress of the operation. By default the source database is restored in place and its current data is replaced. Optionally pass `target_database_id` in the body to restore the backup into a different database; the target must be in the same cluster, of the same database type, and on the same version as the source. The request is rejected with a 400 while another operation is in progress on the database being restored, or while a backup of the source database is still being created. # Suspend database Source: https://api-docs.sevalla.com/v3/databases/suspend-database https://api.sevalla.com/v3/openapi.json post /databases/{id}/suspend Suspend a running database by stopping all of its processes. The database configuration and data are preserved. Use the activate endpoint to restore the database. Cannot be performed while the database is being created, deleted, updated, or has a backup in progress. # Toggle external connection Source: https://api-docs.sevalla.com/v3/databases/toggle-external-connection https://api.sevalla.com/v3/openapi.json post /databases/{id}/external-connection/toggle Toggle external network access for a database. When enabled, the database becomes accessible from outside the cluster via the external hostname and port. When disabled, the database is only accessible internally. The operation is asynchronous - the database status will reflect the progress. # Update database Source: https://api-docs.sevalla.com/v3/databases/update-database https://api.sevalla.com/v3/openapi.json patch /databases/{id} Update one or more properties of an existing database. Only include the fields you want to change - omitted fields are left unchanged. Changing the resource type triggers an asynchronous update operation. # Update database IP restriction Source: https://api-docs.sevalla.com/v3/databases/update-database-ip-restriction https://api.sevalla.com/v3/openapi.json put /databases/{id}/ip-restriction Update the IP restriction configuration for a database. Sets the restriction type (allow or deny), enables or disables it, and updates the list of IP addresses or CIDR ranges. IP restrictions only apply to external connections. When type is `allow`, only the listed IPs can access the database. When type is `deny`, the listed IPs are blocked. For MySQL and MariaDB, a blocked client may still receive the initial server greeting because the server speaks first, but the connection is closed as soon as the client sends any data, so authentication can never complete. The change is applied to the cluster before the response is sent, which can take up to a couple of minutes. Returns the updated restriction state, or 409 if another change to the same database is still being applied. # Create device code Source: https://api-docs.sevalla.com/v3/device-authorization/create-device-code https://api.sevalla.com/v3/openapi.json post /auth/device-codes Request a new device authorization code. The external client displays this code to the user, who then visits the Sevalla dashboard to approve the device. The client polls the GET endpoint until the code is approved, denied, or expired. Codes expire after 5 minutes. Maximum 5 active codes per IP address. # Poll device code status Source: https://api-docs.sevalla.com/v3/device-authorization/poll-device-code-status https://api.sevalla.com/v3/openapi.json get /auth/device-codes/{code} Check the current status of a device authorization code. The external client should poll this endpoint at regular intervals (recommended every 5 seconds) until the status changes from `pending`. When approved, the response includes the API key token for a one-time retrieval - the token cannot be fetched again. # Create Docker registry credential Source: https://api-docs.sevalla.com/v3/docker-registries/create-docker-registry-credential https://api.sevalla.com/v3/openapi.json post /docker-registries Create a new Docker registry credential for the company. The credential is used to authenticate with private Docker registries when pulling images for deployments. The secret is encrypted before storage and never returned in API responses. # Delete Docker registry credential Source: https://api-docs.sevalla.com/v3/docker-registries/delete-docker-registry-credential https://api.sevalla.com/v3/openapi.json delete /docker-registries/{id} Permanently delete a Docker registry credential. Applications using this credential will no longer be able to pull private images from the registry. Make sure no active applications depend on this credential before deleting it. # Get Docker registry credential Source: https://api-docs.sevalla.com/v3/docker-registries/get-docker-registry-credential https://api.sevalla.com/v3/openapi.json get /docker-registries/{id} Retrieve the details of a Docker registry credential. The secret field is never included in responses for security reasons. # List Docker registry credentials Source: https://api-docs.sevalla.com/v3/docker-registries/list-docker-registry-credentials https://api.sevalla.com/v3/openapi.json get /docker-registries Retrieve a paginated list of all Docker registry credentials in the company. Credentials are used to authenticate with private Docker registries when pulling images for deployments. The secret field is never included in responses. # Update Docker registry credential Source: https://api-docs.sevalla.com/v3/docker-registries/update-docker-registry-credential https://api.sevalla.com/v3/openapi.json patch /docker-registries/{id} Update one or more properties of an existing Docker registry credential. Only the provided fields are updated. The secret is re-encrypted if changed. # Errors Source: https://api-docs.sevalla.com/v3/errors How the Sevalla API reports errors, including the error object shape and HTTP status codes. The Sevalla API uses standard HTTP status codes and returns a consistent JSON error object when something goes wrong. ## Error object Every error response has this shape: ```json theme={null} { "message": "Unauthorized", "status": 401, "data": { "code": "err-abc-123", "message": "If you need assistance, please contact support." } } ``` | Field | Type | Description | | - | - | - | | `message` | string | Short description of the error. | | `status` | integer | HTTP status code. | | `data.code` | string | Error tracking identifier. Include this when contacting support. | | `data.message` | string | Additional context or instructions for resolving the error. | The `data` field may not be present on all error responses. Always check for it before accessing nested fields. ## HTTP status codes | Code | Meaning | | - | - | | `200` | Success. The request completed and returned data. | | `201` | Created. A new resource was created. | | `204` | No content. The request succeeded but there's nothing to return (common for deletes). | | `400` | Bad request. The request body or parameters are invalid. | | `401` | Unauthorized. Missing or invalid API key. | | `403` | Forbidden. The API key doesn't have permission for this action. | | `404` | Not found. The resource doesn't exist or you don't have access to it. | | `422` | Unprocessable entity. The request was well-formed but failed validation. | | `429` | Too many requests. You're being rate limited. | | `500` | Internal server error. Something went wrong on our end. | ## Handling errors Use the HTTP status code to determine the category of error. 4xx means something is wrong with your request. 5xx means something went wrong on our side. The `message` field tells you what went wrong. The `data.message` field, when present, gives you specific guidance on how to fix it. If the response includes `data.code`, save it. Support can use this to look up exactly what happened. Don't retry `4xx` errors without changing the request. They will keep failing. Retry `5xx` errors with exponential backoff. # List Git providers Source: https://api-docs.sevalla.com/v3/git/list-git-providers https://api.sevalla.com/v3/openapi.json get /git/providers Retrieve available Git providers (GitHub, Bitbucket, GitLab) with their OAuth connect URLs. Use the connect_url to initiate the OAuth flow and link a Git account. GitHub also includes a settings_url for managing repository access permissions. # Create global environment variable Source: https://api-docs.sevalla.com/v3/global-environment-variables/create-global-environment-variable https://api.sevalla.com/v3/openapi.json post /applications/global-env-vars Create a new company-wide global environment variable. Global variables are inherited by all applications in the company and can be overridden by app-level variables with the same key. A deployment is required for the new variable to take effect in running applications. # Delete global environment variable Source: https://api-docs.sevalla.com/v3/global-environment-variables/delete-global-environment-variable https://api.sevalla.com/v3/openapi.json delete /applications/global-env-vars/{id} Delete a global environment variable. A deployment is required for the removal to take effect in running applications. # List global environment variables Source: https://api-docs.sevalla.com/v3/global-environment-variables/list-global-environment-variables https://api.sevalla.com/v3/openapi.json get /applications/global-env-vars Retrieve a paginated list of all company-wide global environment variables. Global variables are inherited by all applications in the company and can be overridden at the application level. Values are returned decrypted. # Update global environment variable Source: https://api-docs.sevalla.com/v3/global-environment-variables/update-global-environment-variable https://api.sevalla.com/v3/openapi.json put /applications/global-env-vars/{id} Update an existing global environment variable. You can change the key, value, or runtime/buildtime flags. A deployment is required for changes to take effect in running applications. # Add load balancer domain Source: https://api-docs.sevalla.com/v3/load-balancers/add-load-balancer-domain https://api.sevalla.com/v3/openapi.json post /load-balancers/{id}/domains Add a custom domain to a load balancer. After adding, configure your DNS records as indicated in the response to complete domain verification. The domain status will transition from `verification` to `pointing` to `active` as DNS propagates. # Create load balancer Source: https://api-docs.sevalla.com/v3/load-balancers/create-load-balancer https://api.sevalla.com/v3/openapi.json post /load-balancers Create a new load balancer. The load balancer is created with no destinations - add them separately using the create destination endpoint. # Create load balancer destination Source: https://api-docs.sevalla.com/v3/load-balancers/create-load-balancer-destination https://api.sevalla.com/v3/openapi.json post /load-balancers/{id}/destinations Add a new destination to a load balancer. The destination starts enabled and will immediately begin receiving traffic according to the load balancer routing type. # Delete load balancer Source: https://api-docs.sevalla.com/v3/load-balancers/delete-load-balancer https://api.sevalla.com/v3/openapi.json delete /load-balancers/{id} Permanently delete a load balancer and all its destinations. This operation is irreversible. # Delete load balancer destination Source: https://api-docs.sevalla.com/v3/load-balancers/delete-load-balancer-destination https://api.sevalla.com/v3/openapi.json delete /load-balancers/{id}/destinations/{destination_id} Remove a destination from a load balancer. Traffic will no longer be routed to this destination. This action cannot be undone. # Delete load balancer domain Source: https://api-docs.sevalla.com/v3/load-balancers/delete-load-balancer-domain https://api.sevalla.com/v3/openapi.json delete /load-balancers/{id}/domains/{domain_id} Remove a custom domain from a load balancer. System domains cannot be deleted - use the toggle endpoint to disable them instead. This action cannot be undone. # Get load balancer Source: https://api-docs.sevalla.com/v3/load-balancers/get-load-balancer https://api.sevalla.com/v3/openapi.json get /load-balancers/{id} Retrieve the full details of a load balancer including its routing type and custom route configuration. # Get load balancer domain Source: https://api-docs.sevalla.com/v3/load-balancers/get-load-balancer-domain https://api.sevalla.com/v3/openapi.json get /load-balancers/{id}/domains/{domain_id} Retrieve the details of a specific domain associated with a load balancer, including its verification status, DNS records, and configuration. # Get rate limit Source: https://api-docs.sevalla.com/v3/load-balancers/get-rate-limit https://api.sevalla.com/v3/openapi.json get /load-balancers/{id}/rate-limit Retrieve the current rate limiting configuration for a load balancer. Rate limiting restricts each client IP to 100 requests per minute per hostname and applies the configured action when the limit is exceeded. If rate limiting has never been configured, returns the default state: disabled with the `challenge` action. # List load balancer destinations Source: https://api-docs.sevalla.com/v3/load-balancers/list-load-balancer-destinations https://api.sevalla.com/v3/openapi.json get /load-balancers/{id}/destinations Retrieve a paginated list of all destinations configured for a load balancer. # List load balancer domains Source: https://api-docs.sevalla.com/v3/load-balancers/list-load-balancer-domains https://api.sevalla.com/v3/openapi.json get /load-balancers/{id}/domains Retrieve a paginated list of all domains (both system and custom) associated with a load balancer. # List load balancers Source: https://api-docs.sevalla.com/v3/load-balancers/list-load-balancers https://api.sevalla.com/v3/openapi.json get /load-balancers Retrieve a paginated list of all load balancers the authenticated API key has access to. Results are ordered by creation date (newest first) and can be paginated using the `limit` and `offset` query parameters. # Refresh load balancer domain status Source: https://api-docs.sevalla.com/v3/load-balancers/refresh-load-balancer-domain-status https://api.sevalla.com/v3/openapi.json post /load-balancers/{id}/domains/{domain_id}/refresh-status Trigger a re-check of the domain verification and DNS pointing status. Use this after updating your DNS records to speed up the verification process. # Set primary load balancer domain Source: https://api-docs.sevalla.com/v3/load-balancers/set-primary-load-balancer-domain https://api.sevalla.com/v3/openapi.json post /load-balancers/{id}/domains/{domain_id}/set-primary Set a domain as the primary domain for the load balancer. The primary domain is used for canonical URLs. Only one domain can be primary at a time - the previously primary domain is automatically demoted. # Toggle load balancer destination Source: https://api-docs.sevalla.com/v3/load-balancers/toggle-load-balancer-destination https://api.sevalla.com/v3/openapi.json post /load-balancers/{id}/destinations/{destination_id}/toggle Enable or disable a load balancer destination. When disabled, the destination stops receiving traffic. # Toggle load balancer system domain Source: https://api-docs.sevalla.com/v3/load-balancers/toggle-load-balancer-system-domain https://api.sevalla.com/v3/openapi.json post /load-balancers/{id}/domains/{domain_id}/toggle Enable or disable a system domain for the load balancer. When disabled, the system domain stops serving traffic. Only applies to system domains - custom domains cannot be toggled. # Update load balancer Source: https://api-docs.sevalla.com/v3/load-balancers/update-load-balancer https://api.sevalla.com/v3/openapi.json patch /load-balancers/{id} Update one or more properties of an existing load balancer. Only include the fields you want to change - omitted fields are left unchanged. # Update load balancer system domain Source: https://api-docs.sevalla.com/v3/load-balancers/update-load-balancer-system-domain https://api.sevalla.com/v3/openapi.json patch /load-balancers/{id}/domains/{domain_id} Update the subdomain name of a system domain. Only applies to system domains - use the add/delete endpoints to manage custom domains. # Update rate limit Source: https://api-docs.sevalla.com/v3/load-balancers/update-rate-limit https://api.sevalla.com/v3/openapi.json put /load-balancers/{id}/rate-limit Update the rate limiting configuration for a load balancer. Rate limiting restricts each client IP to 100 requests per minute per hostname across the load balancer domains. When a client exceeds the limit, the configured action is applied: `challenge` requires the visitor to pass a managed challenge for 5 minutes, `throttle` blocks requests only while the rate stays above the limit, and `ban` blocks the client IP for 5 minutes. Changes are synced to the edge network as part of the request. Returns the updated rate limit state. # Create CORS policy Source: https://api-docs.sevalla.com/v3/object-storages/create-cors-policy https://api.sevalla.com/v3/openapi.json post /object-storage/{id}/cors-policies Add a new CORS policy rule to the object storage bucket. The rule is appended to any existing rules. # Create object storage bucket Source: https://api-docs.sevalla.com/v3/object-storages/create-object-storage-bucket https://api.sevalla.com/v3/openapi.json post /object-storage Create a new R2 object storage bucket. The bucket is provisioned immediately with S3-compatible API credentials returned in the response. Optionally enable a public CDN domain by setting `public_access` to true. # Delete CORS policy Source: https://api-docs.sevalla.com/v3/object-storages/delete-cors-policy https://api.sevalla.com/v3/openapi.json delete /object-storage/{id}/cors-policies/{cors_policy_id} Remove a CORS policy rule from the object storage bucket. If this is the last rule, the entire CORS configuration is removed. # Delete object storage bucket Source: https://api-docs.sevalla.com/v3/object-storages/delete-object-storage-bucket https://api.sevalla.com/v3/openapi.json delete /object-storage/{id} Schedule permanent deletion of an object storage bucket. This endpoint marks the bucket for deletion and queues a background job that empties all objects, revokes API credentials, and removes the bucket. The operation runs asynchronously and is irreversible. Poll the bucket to track its status - it will be reported as `deleting` while the job runs and disappears once the deletion completes. A bucket that is still used as a database backup target cannot be deleted and returns 409 until that backup target is removed. # Delete objects Source: https://api-docs.sevalla.com/v3/object-storages/delete-objects https://api.sevalla.com/v3/openapi.json delete /object-storage/{id}/objects Delete one or more objects from the bucket by their keys. Objects are deleted in batches of up to 1000. Partial failures are logged but do not cause the request to fail. # Disable CDN domain Source: https://api-docs.sevalla.com/v3/object-storages/disable-cdn-domain https://api.sevalla.com/v3/openapi.json delete /object-storage/{id}/domain Disable the public CDN domain for the object storage bucket. Objects will no longer be accessible via the domain URL. # Enable CDN domain Source: https://api-docs.sevalla.com/v3/object-storages/enable-cdn-domain https://api.sevalla.com/v3/openapi.json post /object-storage/{id}/domain Enable a public CDN domain for the object storage bucket. Objects in the bucket will be accessible via this domain. Fails if a domain is already enabled. # Get object storage bucket Source: https://api-docs.sevalla.com/v3/object-storages/get-object-storage-bucket https://api.sevalla.com/v3/openapi.json get /object-storage/{id} Retrieve the full details of an object storage bucket including the S3-compatible endpoint, access credentials, and CDN domain. # List CORS policies Source: https://api-docs.sevalla.com/v3/object-storages/list-cors-policies https://api.sevalla.com/v3/openapi.json get /object-storage/{id}/cors-policies Retrieve all CORS policy rules configured for the object storage bucket. Rules without an ID are automatically assigned one. # List object storage buckets Source: https://api-docs.sevalla.com/v3/object-storages/list-object-storage-buckets https://api.sevalla.com/v3/openapi.json get /object-storage Retrieve a paginated list of all object storage buckets the authenticated API key has access to. Results are ordered by name and can be paginated using the `limit` and `offset` query parameters. # List objects Source: https://api-docs.sevalla.com/v3/object-storages/list-objects https://api.sevalla.com/v3/openapi.json get /object-storage/{id}/objects List objects in the bucket using cursor-based pagination. Use the `prefix` and `delimiter` parameters to browse the bucket like a file system. # Purge CDN cache Source: https://api-docs.sevalla.com/v3/object-storages/purge-cdn-cache https://api.sevalla.com/v3/openapi.json post /object-storage/{id}/cache/purge Purge all cached content for the bucket's public CDN domain at the edge. Use this after replacing or updating objects so visitors get the latest versions instead of stale cached copies. Purging affects only the bucket's CDN domain and takes effect within a few seconds. If the bucket has no CDN domain enabled, there is nothing cached and the request succeeds without doing anything. # Rotate object storage credentials Source: https://api-docs.sevalla.com/v3/object-storages/rotate-object-storage-credentials https://api.sevalla.com/v3/openapi.json post /object-storage/{id}/rotate-credentials Generate a new access key and secret key for the object storage bucket. The previous credentials can optionally stay valid for a grace period (up to 168 hours) so clients can migrate without downtime. When the grace period elapses, the previous credentials stop working. The new credentials are returned in the response and are the only chance to capture them. # Update CORS policy Source: https://api-docs.sevalla.com/v3/object-storages/update-cors-policy https://api.sevalla.com/v3/openapi.json patch /object-storage/{id}/cors-policies/{cors_policy_id} Update an existing CORS policy rule on the object storage bucket. All fields must be provided as the rule is fully replaced. # Update object storage bucket Source: https://api-docs.sevalla.com/v3/object-storages/update-object-storage-bucket https://api.sevalla.com/v3/openapi.json patch /object-storage/{id} Update one or more properties of an existing object storage bucket. Only include the fields you want to change - omitted fields are left unchanged. # Pagination Source: https://api-docs.sevalla.com/v3/pagination How to paginate through list responses in the Sevalla API. List endpoints return paginated results using offset-based pagination. You control the page size and position with two query parameters. ## Parameters | Parameter | Type | Default | Range | Description | | - | - | - | - | - | | `limit` | integer | `25` | 1-100 | Maximum number of items per page. | | `offset` | integer | `0` | 0-10000 | Number of items to skip. | ## Response shape Every paginated response includes these fields: ```json theme={null} { "data": [], "total": 42, "offset": 0, "limit": 25 } ``` | Field | Type | Description | | - | - | - | | `data` | array | The items for the current page. | | `total` | integer | Total number of matching items across all pages. | | `offset` | integer | The offset used for this request. | | `limit` | integer | The limit used for this request. | ## Example Fetch the first page of applications: ```bash theme={null} curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://api.sevalla.com/v3/applications?limit=10&offset=0" ``` Fetch the next page: ```bash theme={null} curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://api.sevalla.com/v3/applications?limit=10&offset=10" ``` ## Paging through all results To iterate through every item, increment `offset` by `limit` until you've fetched `total` items. ```typescript theme={null} const url = "https://api.sevalla.com/v3/applications"; const headers = { Authorization: "Bearer YOUR_API_KEY" }; let offset = 0; const limit = 25; const allItems: any[] = []; while (true) { const resp = await fetch(`${url}?limit=${limit}&offset=${offset}`, { headers }); const body = await resp.json(); allItems.push(...body.data); if (offset + limit >= body.total) break; offset += limit; } console.log(`Fetched ${allItems.length} applications`); ``` Use the smallest `limit` that works for your use case. If you only need to check whether items exist, `limit=1` keeps the response fast. # Add application to pipeline stage Source: https://api-docs.sevalla.com/v3/pipelines/add-application-to-pipeline-stage https://api.sevalla.com/v3/openapi.json post /pipelines/{id}/stages/{stage_id}/apps Add an existing application to a pipeline stage. The application must belong to the same company as the pipeline and must not already be assigned to another pipeline stage. The application inherits the project assignment from the pipeline. # Create pipeline Source: https://api-docs.sevalla.com/v3/pipelines/create-pipeline https://api.sevalla.com/v3/openapi.json post /pipelines Create a new pipeline with two default stages (Dev and Production). Pipelines let you organize applications into deployment stages and promote builds between them. # Create pipeline stage Source: https://api-docs.sevalla.com/v3/pipelines/create-pipeline-stage https://api.sevalla.com/v3/openapi.json post /pipelines/{id}/stages Create a new stage in a pipeline. The stage is inserted at the specified position and existing stages are shifted up. New stages are always created with the "standard" type. # Delete pipeline Source: https://api-docs.sevalla.com/v3/pipelines/delete-pipeline https://api.sevalla.com/v3/openapi.json delete /pipelines/{id} Permanently delete a pipeline and all its stages. Applications in the pipeline are unlinked but not deleted. Preview apps are queued for deletion. # Delete pipeline stage Source: https://api-docs.sevalla.com/v3/pipelines/delete-pipeline-stage https://api.sevalla.com/v3/openapi.json delete /pipelines/{id}/stages/{stage_id} Delete a stage from a pipeline. Applications in the stage are unlinked but not deleted. Remaining stages are automatically reordered to fill the gap. # Disable pipeline preview Source: https://api-docs.sevalla.com/v3/pipelines/disable-pipeline-preview https://api.sevalla.com/v3/openapi.json post /pipelines/{id}/preview/disable Disable preview apps for a pipeline. All existing preview apps in the preview stage are queued for deletion and the preview stage is removed. # Enable pipeline preview Source: https://api-docs.sevalla.com/v3/pipelines/enable-pipeline-preview https://api.sevalla.com/v3/openapi.json post /pipelines/{id}/preview/enable Enable preview apps for a pipeline. When enabled, the pipeline can create ephemeral preview environments for pull requests. If the pipeline does not have a Git repository configured, you must provide a repo_url to connect one. # Get pipeline Source: https://api-docs.sevalla.com/v3/pipelines/get-pipeline https://api.sevalla.com/v3/openapi.json get /pipelines/{id} Retrieve the full details of a pipeline including all its stages. Use this to inspect the pipeline configuration, stage ordering, and preview settings. # List pipelines Source: https://api-docs.sevalla.com/v3/pipelines/list-pipelines https://api.sevalla.com/v3/openapi.json get /pipelines Retrieve a paginated list of all pipelines in the company. Each pipeline includes a summary of its stages. Use the `type`, `project_id`, and `search` query parameters to narrow down the results - multiple filters combine with AND. # Promote pipeline Source: https://api-docs.sevalla.com/v3/pipelines/promote-pipeline https://api.sevalla.com/v3/openapi.json post /pipelines/{id}/promote Promote an application from one pipeline stage to another by copying the latest successful deployment from the source app to one or more target apps. The target apps receive a new deployment that reuses the source build image without rebuilding. # Remove application from pipeline stage Source: https://api-docs.sevalla.com/v3/pipelines/remove-application-from-pipeline-stage https://api.sevalla.com/v3/openapi.json delete /pipelines/{id}/stages/{stage_id}/apps/{app_id} Remove an application from a pipeline stage. The application is unlinked from the stage but not deleted. It can be added to a different stage or used independently. # Update pipeline Source: https://api-docs.sevalla.com/v3/pipelines/update-pipeline https://api.sevalla.com/v3/openapi.json patch /pipelines/{id} Update one or more properties of an existing pipeline. You can change the display name, type, project assignment, or reorder stages in a single request. # Update pipeline preview settings Source: https://api-docs.sevalla.com/v3/pipelines/update-pipeline-preview-settings https://api.sevalla.com/v3/openapi.json put /pipelines/{id}/preview Update the preview stage configuration for a pipeline. You can change the auto-create behavior, stale app cleanup settings, or switch the connected Git repository. # Add service to project Source: https://api-docs.sevalla.com/v3/projects/add-service-to-project https://api.sevalla.com/v3/openapi.json post /projects/{id}/services Add an existing service to a project. The service must belong to the same company as the project. When adding a pipeline, all applications in the pipeline stages are also moved into the project. # Create project Source: https://api-docs.sevalla.com/v3/projects/create-project https://api.sevalla.com/v3/openapi.json post /projects Create a new project within the company. Projects are used to group related services (applications, databases, pipelines, object storage) together for easier management. # Delete project Source: https://api-docs.sevalla.com/v3/projects/delete-project https://api.sevalla.com/v3/openapi.json delete /projects/{id} Permanently delete a project. All services (applications, databases, pipelines, object storage) currently in this project will be unlinked but not deleted. API key capabilities scoped to this project will also be removed. # Get project Source: https://api-docs.sevalla.com/v3/projects/get-project https://api.sevalla.com/v3/openapi.json get /projects/{id} Retrieve the details of a specific project by its identifier. # List projects Source: https://api-docs.sevalla.com/v3/projects/list-projects https://api.sevalla.com/v3/openapi.json get /projects Retrieve a paginated list of all projects the authenticated API key has access to. Results are ordered by name and can be paginated using the `limit` and `offset` query parameters. Use the `search` query parameter to narrow down the results by name. # Remove service from project Source: https://api-docs.sevalla.com/v3/projects/remove-service-from-project https://api.sevalla.com/v3/openapi.json delete /projects/{id}/services/{service_id} Remove a service from a project. The service itself is not deleted, only the association with the project is removed. When removing a pipeline, all applications in the pipeline stages are also removed from the project. # Update project Source: https://api-docs.sevalla.com/v3/projects/update-project https://api.sevalla.com/v3/openapi.json patch /projects/{id} Update the display name of an existing project. # Rate Limits Source: https://api-docs.sevalla.com/v3/rate-limits How the Sevalla API enforces rate limits, including per-tier limits, response headers, and how to handle 429 errors. To keep the platform stable for everyone, the Sevalla API enforces rate limits on all requests. When you exceed a limit, the API returns a `429 Too Many Requests` response. ## Rate limit tiers Limits are scoped per company or per service depending on the operation type. | Tier | Limit | Scope | | - | - | - | | Service creation | 20/hour | Per company | | Service mutation | 10/min | Per service + company | | Deployment | 10/min | Per service + company | | General write | 30/min | Per company | | Logs | 30/min | Per company | | Read | 400/min | Per company | **Service creation** covers `POST` requests that create new applications, databases, static sites, or other resources. **Service mutation** covers `PUT`, `PATCH`, and `DELETE` requests that modify an existing service. **General write** covers all other write operations that don't fall into a more specific tier. ## Response headers Every response includes rate limit headers so you can track your usage without guessing. | Header | Description | | - | - | | `x-ratelimit-limit` | Maximum number of requests allowed in the current window. | | `x-ratelimit-remaining` | Number of requests remaining in the current window. | | `x-ratelimit-reset` | Seconds remaining until the current rate limit window resets. | | `x-request-id` | Unique identifier for the request. Include this when contacting support. | Example response headers: ``` x-ratelimit-limit: 400 x-ratelimit-remaining: 398 x-ratelimit-reset: 5 x-request-id: req-a1b2c3d4e5 ``` ## Handling 429 responses When you hit a rate limit, the API returns a `429` status code. The `x-ratelimit-reset` header tells you how many seconds to wait before retrying. ```typescript theme={null} async function makeRequest(url: string, headers: Record): Promise { const resp = await fetch(url, { headers }); if (resp.status === 429) { const wait = Number(resp.headers.get("x-ratelimit-reset")); await new Promise((resolve) => setTimeout(resolve, wait * 1000)); return makeRequest(url, headers); } return resp; } ``` Check `x-ratelimit-remaining` before making requests. If you're running low, slow down proactively instead of waiting to get throttled. Always use exponential backoff with jitter when retrying. Retrying in a tight loop will keep you rate limited longer. # List API key permissions Source: https://api-docs.sevalla.com/v3/resources/list-api-key-permissions https://api.sevalla.com/v3/openapi.json get /resources/rbac/api-key-permissions Retrieve all available API key permissions. Permissions define specific actions on specific resource types that can be granted to API keys. This is reference data and does not require specific resource permissions. # List API key roles Source: https://api-docs.sevalla.com/v3/resources/list-api-key-roles https://api.sevalla.com/v3/openapi.json get /resources/rbac/api-key-roles Retrieve all available API key roles. Roles are predefined permission sets that can be assigned to API keys. This is reference data and does not require specific resource permissions. # List clusters Source: https://api-docs.sevalla.com/v3/resources/list-clusters https://api.sevalla.com/v3/openapi.json get /resources/clusters Retrieve all available clusters (data center locations) where applications and databases can be deployed. This is reference data and does not require specific resource permissions. # List database resource types Source: https://api-docs.sevalla.com/v3/resources/list-database-resource-types https://api.sevalla.com/v3/openapi.json get /resources/database-resource-types Retrieve all available database resource types (machine sizes) that can be assigned to databases. This is reference data and does not require specific resource permissions. # List process resource types Source: https://api-docs.sevalla.com/v3/resources/list-process-resource-types https://api.sevalla.com/v3/openapi.json get /resources/process-resource-types Retrieve all available process resource types (machine sizes) that can be assigned to application processes. This is reference data and does not require specific resource permissions. # Add static site domain Source: https://api-docs.sevalla.com/v3/static-sites/add-static-site-domain https://api.sevalla.com/v3/openapi.json post /static-sites/{id}/domains Add a custom domain to a static site. After adding, configure your DNS records as indicated in the response to complete domain verification. The domain status will transition from `verification` to `pointing` to `active` as DNS propagates. # Cancel static site deployment Source: https://api-docs.sevalla.com/v3/static-sites/cancel-static-site-deployment https://api.sevalla.com/v3/openapi.json post /static-sites/{id}/deployments/{deployment_id}/cancel Cancel a deployment that is currently in progress or waiting. Deployments in the `waiting` status are skipped immediately, while `inProgress` deployments are stopped mid-execution. Completed or already cancelled deployments cannot be cancelled. # Create static site Source: https://api-docs.sevalla.com/v3/static-sites/create-static-site https://api.sevalla.com/v3/openapi.json post /static-sites Create a new static site from a Git repository. An initial deployment is triggered automatically after creation. # Create static site environment variable Source: https://api-docs.sevalla.com/v3/static-sites/create-static-site-environment-variable https://api.sevalla.com/v3/openapi.json post /static-sites/{id}/env-vars Create a new environment variable for a static site. The value is encrypted before storage. A deployment is required for the new variable to take effect. # Delete static site Source: https://api-docs.sevalla.com/v3/static-sites/delete-static-site https://api.sevalla.com/v3/openapi.json delete /static-sites/{id} Permanently delete a static site and all of its associated resources including deployments and custom domains. This operation is irreversible. # Delete static site domain Source: https://api-docs.sevalla.com/v3/static-sites/delete-static-site-domain https://api.sevalla.com/v3/openapi.json delete /static-sites/{id}/domains/{domain_id} Remove a custom domain from a static site. System domains cannot be deleted - use the toggle endpoint to disable them instead. This action cannot be undone. # Delete static site environment variable Source: https://api-docs.sevalla.com/v3/static-sites/delete-static-site-environment-variable https://api.sevalla.com/v3/openapi.json delete /static-sites/{id}/env-vars/{env_var_id} Delete an environment variable from a static site. A deployment is required for the removal to take effect. # Deploy static site Source: https://api-docs.sevalla.com/v3/static-sites/deploy-static-site https://api.sevalla.com/v3/openapi.json post /static-sites/{id}/deployments Trigger a new deployment for a static site. By default, deploys the latest commit on the default branch. You can optionally specify a different branch or roll back to a previous deployment by providing a deployment_id. The deployment runs asynchronously - use the list deployments endpoint to track progress. # Get rate limit Source: https://api-docs.sevalla.com/v3/static-sites/get-rate-limit https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/rate-limit Retrieve the current rate limiting configuration for a static site. Rate limiting restricts each client IP to 100 requests per minute per hostname and applies the configured action when the limit is exceeded. If rate limiting has never been configured, returns the default state: disabled with the `challenge` action. # Get static site Source: https://api-docs.sevalla.com/v3/static-sites/get-static-site https://api.sevalla.com/v3/openapi.json get /static-sites/{id} Retrieve the full details of a static site including its source configuration, build settings, and current status. # Get static site access logs Source: https://api-docs.sevalla.com/v3/static-sites/get-static-site-access-logs https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/access-logs Retrieve HTTP access logs for a static site. These are logs of incoming requests served by the static site. Use the `filters` parameter for advanced filtering by severity, message content, tags, or attributes. # Get static site average response time Source: https://api-docs.sevalla.com/v3/static-sites/get-static-site-average-response-time https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/metrics/response-time-avg Retrieve the average response time in milliseconds for a static site over the specified time range. Returns a single aggregated value rather than a time series. # Get static site deployment Source: https://api-docs.sevalla.com/v3/static-sites/get-static-site-deployment https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/deployments/{deployment_id} Retrieve details of a specific deployment for a static site, including its status, source details, and timestamps. # Get static site deployment logs Source: https://api-docs.sevalla.com/v3/static-sites/get-static-site-deployment-logs https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/deployments/{deployment_id}/logs Retrieve build and deployment logs for a specific static site deployment. These include output from the build process and publish steps. Use the `filters` parameter for advanced filtering by severity, message content, tags, or attributes. # Get static site domain Source: https://api-docs.sevalla.com/v3/static-sites/get-static-site-domain https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/domains/{domain_id} Retrieve the details of a specific domain associated with a static site, including its verification status, DNS records, and configuration. # Get static site repository Source: https://api-docs.sevalla.com/v3/static-sites/get-static-site-repository https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/repository Retrieve metadata about the Git repository connected to a static site: the source type, Git provider, repository URL, default branch, and the commit currently deployed (from the latest successful deployment). Call this first to discover the deployed commit SHA, then pass it as the `ref` to the tree and contents endpoints to inspect exactly the code that is deployed. Static sites always have a `privateGit` or `publicGit` source; the 422 response only occurs if the repository URL is missing. # Get static site requests per minute Source: https://api-docs.sevalla.com/v3/static-sites/get-static-site-requests-per-minute https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/metrics/requests-per-minute Retrieve a time series of requests per minute for a static site. Returns data points at the specified interval, useful for monitoring traffic patterns and detecting spikes. # Get static site response time Source: https://api-docs.sevalla.com/v3/static-sites/get-static-site-response-time https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/metrics/response-time Retrieve a time series of response times for a static site. Use the optional `percent` parameter to get a specific percentile (e.g., p95 or p99) instead of the default. # Get static site slowest requests Source: https://api-docs.sevalla.com/v3/static-sites/get-static-site-slowest-requests https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/metrics/slowest-requests Retrieve the slowest request paths for a static site, ranked by average response time. Each entry includes the HTTP method, path, average response time, and total request count. # Get static site status code breakdown Source: https://api-docs.sevalla.com/v3/static-sites/get-static-site-status-code-breakdown https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/metrics/status-codes Retrieve a time series showing the breakdown of HTTP response status codes for a static site. Each data point includes a map of status codes to their request counts. # Get static site top countries Source: https://api-docs.sevalla.com/v3/static-sites/get-static-site-top-countries https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/metrics/top-countries Retrieve the countries generating the most traffic to a static site, ranked by total request count. Each entry includes the country code, average response time, and total requests. # Get static site top pages Source: https://api-docs.sevalla.com/v3/static-sites/get-static-site-top-pages https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/metrics/top-pages Retrieve the most visited pages for a static site, ranked by total request count. Useful for understanding which pages receive the most traffic. # Get static site top status codes Source: https://api-docs.sevalla.com/v3/static-sites/get-static-site-top-status-codes https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/metrics/top-status-codes Retrieve the most common HTTP response status codes for a static site, ranked by total request count. Useful for identifying error rates and common response patterns. # List static site deployments Source: https://api-docs.sevalla.com/v3/static-sites/list-static-site-deployments https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/deployments Retrieve a paginated list of all deployments for a static site, ordered by most recent first. Each deployment includes its status, source details, and timestamps. # List static site domains Source: https://api-docs.sevalla.com/v3/static-sites/list-static-site-domains https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/domains Retrieve a paginated list of all domains (both system and custom) associated with a static site. System domains are assigned automatically, while custom domains are added by users. # List static site environment variables Source: https://api-docs.sevalla.com/v3/static-sites/list-static-site-environment-variables https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/env-vars Retrieve a paginated list of all environment variables for a static site. Values are returned decrypted. # List static site repository tree Source: https://api-docs.sevalla.com/v3/static-sites/list-static-site-repository-tree https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/repository/tree List files and directories in the static site Git repository at a given ref. Use this to discover the repository structure before reading individual files. Defaults to reading the commit of the latest successful deployment so you see exactly the code that is deployed. Static sites always have a `privateGit` or `publicGit` source; the 422 response only occurs if the repository URL is missing. # List static sites Source: https://api-docs.sevalla.com/v3/static-sites/list-static-sites https://api.sevalla.com/v3/openapi.json get /static-sites Retrieve a paginated list of all static sites the authenticated API key has access to. Results can be paginated using the `limit` and `offset` query parameters. # Purge edge cache Source: https://api-docs.sevalla.com/v3/static-sites/purge-edge-cache https://api.sevalla.com/v3/openapi.json post /static-sites/{id}/purge-cache Purge the edge cache for a static site, removing all cached content. Use this when you need cached resources to be refreshed immediately without waiting for the cache TTL to expire. # Read static site repository file Source: https://api-docs.sevalla.com/v3/static-sites/read-static-site-repository-file https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/repository/contents Read the contents of a single file from the static site Git repository at a given ref. Defaults to the commit of the latest successful deployment so you read exactly the code that is deployed. Binary files and files larger than 1 MB return metadata only with a null `content` (check `is_binary` and `truncated`). Returns 404 when the file does not exist at the ref. Static sites always have a `privateGit` or `publicGit` source; the 422 response only occurs if the repository URL is missing. # Refresh static site domain status Source: https://api-docs.sevalla.com/v3/static-sites/refresh-static-site-domain-status https://api.sevalla.com/v3/openapi.json post /static-sites/{id}/domains/{domain_id}/refresh-status Trigger a re-check of the domain verification and DNS pointing status. Use this after updating your DNS records to speed up the verification process. # Search static site repository code Source: https://api-docs.sevalla.com/v3/static-sites/search-static-site-repository-code https://api.sevalla.com/v3/openapi.json get /static-sites/{id}/repository/search Search the static site Git repository for code matching a query, useful for locating where something is defined or used. Search runs against the provider index, which covers the default branch, so it does not accept a ref. Result quality varies by provider: it is strongest on GitHub and more limited on GitLab and Bitbucket. Static sites always have a `privateGit` or `publicGit` source; the 422 response only occurs if the repository URL is missing. # Set primary static site domain Source: https://api-docs.sevalla.com/v3/static-sites/set-primary-static-site-domain https://api.sevalla.com/v3/openapi.json post /static-sites/{id}/domains/{domain_id}/set-primary Set a domain as the primary domain for the static site. The primary domain is used for canonical URLs and redirects. Only one domain can be primary at a time - the previously primary domain is automatically demoted. # Toggle pretty URLs Source: https://api-docs.sevalla.com/v3/static-sites/toggle-pretty-urls https://api.sevalla.com/v3/openapi.json post /static-sites/{id}/pretty-url/toggle Toggle pretty URL redirects for a static site. When enabled, URLs like `/about` will serve `/about/index.html` or `/about.html` without showing the file extension. # Toggle static site system domain Source: https://api-docs.sevalla.com/v3/static-sites/toggle-static-site-system-domain https://api.sevalla.com/v3/openapi.json post /static-sites/{id}/domains/{domain_id}/toggle Enable or disable a system domain for the static site. When disabled, the system domain stops serving traffic. Only applies to system domains - custom domains cannot be toggled. # Update rate limit Source: https://api-docs.sevalla.com/v3/static-sites/update-rate-limit https://api.sevalla.com/v3/openapi.json put /static-sites/{id}/rate-limit Update the rate limiting configuration for a static site. Rate limiting restricts each client IP to 100 requests per minute per hostname across the static site domains. When a client exceeds the limit, the configured action is applied: `challenge` requires the visitor to pass a managed challenge for 5 minutes, `throttle` blocks requests only while the rate stays above the limit, and `ban` blocks the client IP for 5 minutes. Changes are synced to the edge network as part of the request. Returns the updated rate limit state. # Update static site Source: https://api-docs.sevalla.com/v3/static-sites/update-static-site https://api.sevalla.com/v3/openapi.json patch /static-sites/{id} Update one or more properties of an existing static site. Only include the fields you want to change - omitted fields are left unchanged. Changes to build settings take effect on the next deployment. When changing source or repo_url, the repository is validated against the Git provider. # Update static site environment variable Source: https://api-docs.sevalla.com/v3/static-sites/update-static-site-environment-variable https://api.sevalla.com/v3/openapi.json put /static-sites/{id}/env-vars/{env_var_id} Update an existing environment variable for a static site. You can change the key, value, or scope flags. A deployment is required for changes to take effect. # Update static site system domain Source: https://api-docs.sevalla.com/v3/static-sites/update-static-site-system-domain https://api.sevalla.com/v3/openapi.json patch /static-sites/{id}/domains/{domain_id} Update the subdomain name of a system domain. Only applies to system domains - use the add/delete endpoints to manage custom domains. # Create usage alert config Source: https://api-docs.sevalla.com/v3/usage-alerts/create-usage-alert-config https://api.sevalla.com/v3/openapi.json post /usage-alerts Create a usage alert config for the company or for a specific project. Each company can have one company-wide config plus one config per project. Configs are evaluated hourly against the current billing period. The highest matching trigger fires once per period and notifies the listed emails. # Delete usage alert config Source: https://api-docs.sevalla.com/v3/usage-alerts/delete-usage-alert-config https://api.sevalla.com/v3/openapi.json delete /usage-alerts/{id} Permanently delete a usage alert config. The cron will stop evaluating it immediately. This action cannot be undone. # Get usage alert config Source: https://api-docs.sevalla.com/v3/usage-alerts/get-usage-alert-config https://api.sevalla.com/v3/openapi.json get /usage-alerts/{id} Retrieve a single usage alert config by its identifier, including its trigger thresholds. # List usage alert configs Source: https://api-docs.sevalla.com/v3/usage-alerts/list-usage-alert-configs https://api.sevalla.com/v3/openapi.json get /usage-alerts Retrieve all usage alert configs for the company, including the company-wide config and any project-scoped configs. Pass project_id to filter to a single project. # Update usage alert config Source: https://api-docs.sevalla.com/v3/usage-alerts/update-usage-alert-config https://api.sevalla.com/v3/openapi.json patch /usage-alerts/{id} Update one or more properties of an existing usage alert config. Only the provided fields are changed. The project scope is fixed at creation and cannot be changed - delete the config and create a new one to move it. # List company users Source: https://api-docs.sevalla.com/v3/users/list-company-users https://api.sevalla.com/v3/openapi.json get /users Retrieve the list of users belonging to the company associated with the authenticated API key. # Webhook Events Source: https://api-docs.sevalla.com/v3/webhook-events Payload structure, event types, signature verification, and retry behavior for Sevalla webhooks. When an event fires, Sevalla sends a `POST` request to your webhook endpoint with a JSON payload. This page documents what your endpoint receives and how to verify it. ## Payload structure Every webhook request body follows this format: ```json theme={null} { "webhook_id": "d5f8a1c2-3b4e-5f6a-7b8c-9d0e1f2a3b4c", "event_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "event_delivery_id": "f1e2d3c4-b5a6-9788-9a0b-c1d2e3f4a5b6", "type": "APP_DEPLOY", "data": {} } ``` | Field | Type | Description | | - | - | - | | `webhook_id` | string | UUID of the webhook that triggered this delivery. | | `event_id` | string | UUID of the event. Same across retries. | | `event_delivery_id` | string | UUID of this specific delivery attempt. Unique per retry. | | `type` | string | The event type. See [Event types](#event-types) below. | | `data` | object | Event-specific payload. Shape depends on `type`. | ## Request headers Sevalla sends two headers with every webhook request: | Header | Value | | - | - | | `content-type` | `application/json` | | `svl-signature` | Your webhook secret (e.g. `whsec_...`). | ## Verifying signatures Every webhook request includes an `svl-signature` header containing your webhook's secret. Compare this value against the secret stored on your end to verify the request is from Sevalla. ```typescript theme={null} import { type IncomingMessage } from "node:http"; function verifyWebhook(req: IncomingMessage, secret: string): boolean { const signature = req.headers["svl-signature"]; return signature === secret; } ``` Always verify the `svl-signature` header before processing a webhook. Without verification, anyone who discovers your endpoint URL could send fake events. ## Event types You can subscribe to any combination of these events when creating a webhook. ### Application events | Type | Fires when | | - | - | | `APP_CREATE` | An application is created. | | `APP_UPDATE` | An application is modified. | | `APP_DELETE` | An application is deleted. | | `APP_DEPLOY` | A deployment starts, succeeds, or fails. | **`APP_CREATE`, `APP_UPDATE`, `APP_DELETE` data:** ```json theme={null} { "id": "app-id", "company_id": "company-id", "name": "my-app", "display_name": "My App", "location": "eu-west" } ``` **`APP_DEPLOY` data:** ```json theme={null} { "company_id": "company-id", "app_id": "app-id", "app_name": "my-app", "app_display_name": "My App", "deployment_id": "deploy-id", "status": "success", "commit": "a1b2c3d", "stage": "production", "is_preview": false } ``` ### Static site events | Type | Fires when | | - | - | | `STATIC_SITE_CREATE` | A static site is created. | | `STATIC_SITE_UPDATE` | A static site is modified. | | `STATIC_SITE_DELETE` | A static site is deleted. | | `STATIC_SITE_DEPLOY` | A static site deployment starts, succeeds, or fails. | **`STATIC_SITE_CREATE`, `STATIC_SITE_UPDATE`, `STATIC_SITE_DELETE` data:** ```json theme={null} { "id": "site-id", "company_id": "company-id", "name": "my-site", "display_name": "My Site" } ``` **`STATIC_SITE_DEPLOY` data:** ```json theme={null} { "company_id": "company-id", "static_site_id": "site-id", "static_site_name": "my-site", "static_site_display_name": "My Site", "deployment_id": "deploy-id", "status": "success", "repo_url": "https://github.com/org/repo", "branch": "main", "commit": "a1b2c3d", "is_preview": false } ``` ### Database events | Type | Fires when | | - | - | | `DATABASE_CREATE` | A database is created. | | `DATABASE_UPDATE` | A database is modified. | | `DATABASE_DELETE` | A database is deleted. | ## Retry behavior If your endpoint returns a non-2xx status code or doesn't respond, Sevalla retries the delivery up to **12 times** with exponential backoff: | Retry | Delay | | - | - | | 1 | 1 minute | | 2 | 5 minutes | | 3 | 10 minutes | | 4 | 30 minutes | | 5 | 1 hour | | 6 | 2 hours | | 7 | 4 hours | | 8 | 8 hours | | 9 | 16 hours | | 10 | 1 day | | 11 | 2 days | | 12 | 3 days | Each retry generates a new `event_delivery_id` but keeps the same `event_id`. After 12 failed attempts, the delivery is marked as failed permanently. Return a `200` status code as quickly as possible. Process the webhook payload asynchronously to avoid timeouts. If your endpoint is slow to respond, it may be treated as a failure. ## Secret rotation When you [rotate a webhook secret](/v3/webhooks/roll-webhook-secret), you can set a grace period (0-24 hours) during which both the old and new secrets are valid. During this window, the `svl-signature` header will contain the old secret. Once the grace period expires, only the new secret is used. This lets you deploy updated verification logic without missing events. # Create webhook Source: https://api-docs.sevalla.com/v3/webhooks/create-webhook https://api.sevalla.com/v3/openapi.json post /webhooks Create a new webhook for the company. The webhook will start receiving events for the specified event types as soon as it is created. Each company can have up to 10 webhooks. A signing secret is automatically generated and included in the response. # Delete webhook Source: https://api-docs.sevalla.com/v3/webhooks/delete-webhook https://api.sevalla.com/v3/openapi.json delete /webhooks/{id} Permanently delete a webhook. The webhook will immediately stop receiving events. This action cannot be undone. # Get webhook Source: https://api-docs.sevalla.com/v3/webhooks/get-webhook https://api.sevalla.com/v3/openapi.json get /webhooks/{id} Retrieve the details of a specific webhook, including its subscribed events, endpoint, and signing secret. # Get webhook event delivery Source: https://api-docs.sevalla.com/v3/webhooks/get-webhook-event-delivery https://api.sevalla.com/v3/openapi.json get /webhooks/{id}/deliveries/{delivery_id} Retrieve the details of a specific event delivery, including the request payload sent to the endpoint, the response received, HTTP status code, and response time. # List webhook event deliveries Source: https://api-docs.sevalla.com/v3/webhooks/list-webhook-event-deliveries https://api.sevalla.com/v3/openapi.json get /webhooks/{id}/deliveries Retrieve a paginated list of event deliveries for a specific webhook. Each delivery represents an HTTP POST request sent to the webhook endpoint when a subscribed event occurred. Results are ordered by creation time, newest first. # List webhooks Source: https://api-docs.sevalla.com/v3/webhooks/list-webhooks https://api.sevalla.com/v3/openapi.json get /webhooks Retrieve a paginated list of all webhooks configured for the company. Each company can have up to 10 webhooks. Webhooks receive HTTP POST notifications when subscribed events occur. # Roll webhook secret Source: https://api-docs.sevalla.com/v3/webhooks/roll-webhook-secret https://api.sevalla.com/v3/openapi.json post /webhooks/{id}/roll-secret Generate a new signing secret for the webhook. You can set a transition period (up to 24 hours) during which both old and new secrets are valid, allowing you to update your verification logic without downtime. # Toggle webhook Source: https://api-docs.sevalla.com/v3/webhooks/toggle-webhook https://api.sevalla.com/v3/openapi.json post /webhooks/{id}/toggle Toggle a webhook between enabled and disabled states. Disabled webhooks stop receiving event deliveries until re-enabled. # Update webhook Source: https://api-docs.sevalla.com/v3/webhooks/update-webhook https://api.sevalla.com/v3/openapi.json patch /webhooks/{id} Update one or more properties of an existing webhook. Only the provided fields are updated. Changes take effect immediately for subsequent event deliveries.