> ## Agent Instructions > This is the Sevalla REST API reference. Base URL: https://api.sevalla.com/v3. Authenticate with an API key in the Authorization header as a Bearer token. > The OpenAPI spec is at https://api.sevalla.com/v3/openapi.json. Concepts and dashboard guides are at https://docs.sevalla.com (index: https://docs.sevalla.com/llms.txt). > To act on a Sevalla account from an AI agent, prefer the Sevalla MCP server (https://mcp.sevalla.com/mcp, see https://docs.sevalla.com/ai-agents/overview.md) or the Sevalla CLI (https://api-docs.sevalla.com/v3/cli.md). # Sevalla API reference Source: https://api-docs.sevalla.com/index The Sevalla REST API v3: make a first request with an API key, find the operations for each product, and read the guides on errors, limits, pagination and polling. The Sevalla API is a REST API for managing your company's services and settings: applications, deployments, processes, databases, static sites, object storage, load balancers, pipelines, projects, domains, environment variables, webhooks and API keys. It sends and receives JSON over HTTPS, and every request is authenticated with an [API key](https://docs.sevalla.com/developer-tools/api-keys). | What | Value | | - | - | | Base URL | `https://api.sevalla.com/v3` | | Authentication | `Authorization: Bearer `. See [Authentication](/v3/authentication). | | Format | JSON request and response bodies, `snake_case` field names, UUIDs as IDs | | OpenAPI spec | `https://api.sevalla.com/v3/openapi.json` (OpenAPI 3.1) | ## Make your first request **1. Create an API key** In the Sevalla dashboard, under **Tools**, click **API keys**, then [create a key](https://docs.sevalla.com/developer-tools/api-keys#create-an-api-key). The **Company viewer** role is enough to read. Copy the key when it's shown, and keep it in an environment variable: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} export SEVALLA_API_KEY="svl_..." ``` **2. List your applications** Send the key as a bearer token to [List applications](/v3/applications/list-applications): ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} curl https://api.sevalla.com/v3/applications \ -H "Authorization: Bearer $SEVALLA_API_KEY" ``` **3. Read the response** The API returns the first page of the company's applications, ordered by name: ```json theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} { "data": [ { "id": "7f3c2b1a-9e8d-4c7b-a6f5-4e3d2c1b0a9f", "name": "storefront-x7k2m", "display_name": "storefront", "status": "deploymentSuccess", "type": "app", "source": "privateGit", "is_suspended": false, "created_at": "2026-09-14T08:21:37.000Z", "updated_at": "2026-10-15T16:02:11.000Z" } ], "total": 1, "offset": 0, "limit": 25 } ``` Each application's `id` is what other operations take, for example `POST /applications/{id}/deployments` to [trigger a deployment](/v3/applications/trigger-deployment). [Pagination](/v3/pagination) explains `total`, `offset` and `limit`. To see what a key is allowed to do, call [Get current API key](/v3/api-keys/get-current-api-key) (`GET /api-keys/me`). ## What you can manage > **[Applications](/v3/applications/list-applications)** > > Create, deploy and roll back applications, and manage their processes, domains, environment variables, networking, logs and metrics. > **[Pipelines](/v3/pipelines/list-pipelines)** > > Stages, promotions without a rebuild, and preview apps for pull requests. > **[Databases](/v3/databases/list-databases)** > > PostgreSQL, MySQL, MariaDB, Redis and Valkey, with backups, restores and internal connections. > **[Static sites](/v3/static-sites/list-static-sites)** > > Deployments, custom domains, environment variables, cache purges, logs and metrics. > **[Object storage](/v3/object-storages/list-object-storage-buckets)** > > Buckets, objects, CORS policies, the CDN domain and S3 credentials. > **[Load balancers](/v3/load-balancers/list-load-balancers)** > > Destinations and custom domains. > **[Projects](/v3/projects/list-projects)** > > Group applications, databases, pipelines and buckets, and move services between projects. > **[Webhooks](/v3/webhooks/list-webhooks)** > > Endpoints, events, signing secrets and deliveries. The reference also covers global environment variables, registry credentials, API keys, usage alerts, company users, and resources such as locations and sizes. ## Guides * [Authentication](/v3/authentication): API keys, the `Authorization` header, permissions, and `401` and `403` responses. * [Errors](/v3/errors): the error body, every status code, and which errors to retry. * [Rate limits](/v3/rate-limits): the six limit tiers, the `x-ratelimit-*` headers and `429`. * [Pagination](/v3/pagination): `limit`, `offset` and `total` on list operations. * [Long-running operations](/v3/long-running-operations): operations that finish in the background, and how to poll for the result. * [Webhook events](/v3/webhook-events): the requests Sevalla sends to your webhook endpoint. ## Tools built on the API These tools call this API with the same API keys, so you don't always need to call it by hand. > **[Sevalla CLI](https://docs.sevalla.com/developer-tools/cli)** > > Commands for a terminal or a CI job, with JSON output. > **[MCP server](https://docs.sevalla.com/ai-agents/overview)** > > AI agents that deploy, debug and manage services. > **[Terraform provider](https://docs.sevalla.com/developer-tools/terraform)** > > Services defined as code. ## OpenAPI spec The spec is generated from the API's code, and every operation page in this reference is built from it. Download it without an API key, as JSON from `https://api.sevalla.com/v3/openapi.json` or as YAML from `https://api.sevalla.com/v3/openapi.yaml`. For LLMs and agents, `https://api-docs.sevalla.com/llms.txt` lists every page of this reference with its description. # 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. If Sevalla cannot access the Git repository, the request fails with a 400 error that explains why and links to the page where access can be granted (for example the repository access settings of the GitHub App used by Sevalla). # 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 internal connection Source: https://api-docs.sevalla.com/v3/applications/create-internal-connection https://api.sevalla.com/v3/openapi.json post /applications/{id}/internal-connections Create an internal connection from this application to another application or a database, so they can reach each other over the private cluster network. Both services must be in the same cluster. Applications do not need to be deployed yet. The connection covers every process of the applications, including cron and job processes. The application from the URL path is always the source of the connection. Connections are bidirectional, so traffic is allowed both ways and only one connection can exist between a given pair of services - creating it again in either direction returns 409. An application cannot be connected to itself. The API key needs update access to both the application and the target. # 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 internal connection Source: https://api-docs.sevalla.com/v3/applications/delete-internal-connection https://api.sevalla.com/v3/openapi.json delete /applications/{id}/internal-connections/{connection_id} Delete an internal connection of this application. The application must be either the source or the target of the connection. After deletion the two services can no longer reach each other over the private cluster network. # 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. Returns the most recent `limit` entries in the time range, oldest first by default (set `order=desc` for newest first). Use `search` for a case-insensitive text match on the message, and `filters` for filtering by severity, message, 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. Returns the most recent `limit` entries in the time range, oldest first by default (set `order=desc` for newest first). Use `search` for a case-insensitive text match on the message, and `filters` for filtering by severity, message, 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). Returns the most recent `limit` entries in the time range, oldest first by default (set `order=desc` for newest first). Use `search` for a case-insensitive text match on the message, and `filters` for filtering by severity, message, 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. # 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 internal connections Source: https://api-docs.sevalla.com/v3/applications/list-internal-connections https://api.sevalla.com/v3/openapi.json get /applications/{id}/internal-connections Retrieve all internal connections of an application. Internal connections allow services within the same cluster to communicate with each other. Returns connections where this application is either the source or the target, including connections created from a database. # 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&cols=120&rows=40" -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. ### Terminal size The terminal starts at the size given by the `cols` and `rows` query parameters, or 80x24 without them. To resize it, send a **binary** message holding the UTF-8 encoded JSON `{"type":"resize","cols":120,"rows":40}`. Sizes are clamped to 2-500 columns and 2-200 rows, and a resize message without integer `cols` and `rows` is ignored. Resize messages never reach the shell. Text messages are always shell input, even when they look like a resize message, and any other binary message is passed to the shell as input as well. ### Environment The shell starts with `TERM=xterm-256color` and `COLORTERM=truecolor`. It also gets `LANG=C.UTF-8`, unless the container already sets `LANG` or an `LC_*` variable. ### Output Output arrives as UTF-8 text messages. A character that the container writes in two pieces is always sent whole, never as a replacement character. ### Keepalive The server sends a WebSocket ping every 25 seconds, which standard WebSocket clients answer with a pong on their own. This keeps an idle session open through proxies and load balancers. A connection that leaves two pings in a row unanswered is closed, and so is a session that has had no input and no output for 8 hours. ### Disconnects A closed connection is not resumed, and the next connection starts a new shell. Run long jobs under `nohup`, or in `tmux` or `screen` when the image has them, so you can find them again after a disconnect. ### 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 - `4004` - No input and no output for 8 hours - `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 specific commit, a Docker image, or restart from the last successful deployment. You can also rebuild without the build cache. 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. # Authentication Source: https://api-docs.sevalla.com/v3/authentication Authenticate Sevalla API requests with an API key sent as a bearer token, check what a key can do, and fix 401 and 403 responses. Every request to the Sevalla API is authenticated with an API key, sent in the `Authorization` header as a bearer token. The key belongs to one company, and the request can only act on that company's services, with the permissions set on the key. | Property | Value | | - | - | | Header | `Authorization: Bearer ` | | Key format | `svl_` followed by 64 hexadecimal characters | | Scope | One company: the company the key was created in | | Permissions | Checked on every request, so a change to the key applies to the next request | | Transport | HTTPS. A plain `http://` request gets a `301` redirect to `https://`. | ## Create an API key In the Sevalla dashboard, under **Tools**, click **API keys**, then click **Create API key**. Choose a predefined role (**Company viewer** is enough to read) or custom capabilities, and copy the key: it's shown only once. [API keys](https://docs.sevalla.com/developer-tools/api-keys#create-an-api-key) in the platform docs covers roles, capabilities, expiration and rotation. You can also create keys with [Create API key](/v3/api-keys/create-api-key). Create one key per integration or environment, so you can rotate or revoke one without breaking the others. ## Send the key Keep the key in an environment variable and send it on every request: ```bash curl theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} curl https://api.sevalla.com/v3/applications \ -H "Authorization: Bearer $SEVALLA_API_KEY" ``` ```typescript TypeScript theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} const res = await fetch("https://api.sevalla.com/v3/applications", { headers: { Authorization: `Bearer ${process.env.SEVALLA_API_KEY}` }, }); const applications = await res.json(); ``` Never put the key in code you commit, a URL or a browser app: anyone with the key can act on the company within its permissions. ## Check a key Two operations work with any valid key, whatever its permissions: | Operation | Returns | | - | - | | [Validate API key](/v3/api-keys/validate-api-key) (`GET /api-keys/validate`) | The key's `name`, `expires_at`, `company_id` and `status` | | [Get current API key](/v3/api-keys/get-current-api-key) (`GET /api-keys/me`) | The key's details and `capabilities`: every permission it has, from its roles and custom capabilities, with the `resource_id` it's limited to (`null` for all resources) | ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} curl https://api.sevalla.com/v3/api-keys/me \ -H "Authorization: Bearer $SEVALLA_API_KEY" ``` ## Permissions Each operation checks the permissions it needs, written `RESOURCE:ACTION`: [List applications](/v3/applications/list-applications) needs `APP:READ`, [Trigger deployment](/v3/applications/trigger-deployment) needs `APP:UPDATE`, and [Clone application](/v3/applications/clone-application) needs both `APP:READ` and `APP:CREATE`. A key has a predefined role or custom capabilities, and a capability can be limited to specific resources. [Permissions](https://docs.sevalla.com/developer-tools/api-keys#permissions) in the platform docs lists the roles and capabilities. When a capability is limited to specific resources, requests for other resources of that type fail with `403`, and list operations return only the resources the key can see. > [!WARNING] > > A key with `API_KEY:CREATE` can create new keys with any role, including **Company admin**. Give that permission only to keys you'd trust with full access. ## Authentication errors | Status | Message | Cause | Fix | | - | - | - | - | | `401` | `Unauthorized` | The header is missing, or the key is mistyped, disabled, expired or deleted, or it's an old token past its rotation period | Check the `Authorization: Bearer` header and the key's status under **Tools** > **API keys** | | `403` | `This API key is missing the APP:UPDATE permission. Grant it to the key or use a key that has it.` | The key lacks the permission named in the message. When the key has the permission for other resources only, the message reads `permission for this resource`. | [Update the key's permissions](https://docs.sevalla.com/developer-tools/api-keys#update-an-api-key), or use another key | | `403` | `The service is suspended.` | The company, or the application or database the request acts on, is suspended | Activate the application or database, or [reactivate the company](https://docs.sevalla.com/billing/failed-payments#reactivate-a-suspended-company) | | `403` | `Your company is being migrated to new infrastructure. Changes are disabled until the migration finishes.` | The company is being migrated. Reads (`GET`) still work. | Retry the change after the migration | | `403` | `Your company is under maintenance. Changes are temporarily disabled.` | The company is under maintenance. Reads (`GET`) still work. | Retry the change after the maintenance | | `400` | `An API key cannot modify itself` | A key tried to update, rotate, disable or delete itself | Use another key, or the dashboard | A request that doesn't match the operation's schema, such as an ID that isn't a UUID, returns `400` before the key is checked. See [Errors](/v3/errors) for every status code. # CLI reference Source: https://api-docs.sevalla.com/v3/cli Every command, argument and flag of the Sevalla CLI 1.10.1, with required flags, defaults, dry runs and the API operation each command calls. The Sevalla CLI, `sevalla`, runs the Sevalla API v3 from a terminal or a CI job. A command sends a request with your API key and prints the result as a table or as JSON. This reference covers version 1.10.1, released Oct 18, 2026: all 216 commands with their arguments, flags and defaults, and the API operation each one calls. To install the CLI, sign in and see the commands you use most, read [Sevalla CLI](https://docs.sevalla.com/developer-tools/cli) in the platform docs. ## Install and sign in ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} # Homebrew brew install sevalla-hosting/tap/sevalla # npm, with Node.js 24 or later npm install -g @sevalla/cli # Shell script: installs the macOS or Linux binary to /usr/local/bin/sevalla bash <(curl -fsSL https://raw.githubusercontent.com/sevalla-hosting/cli/main/install.sh) ``` On Windows, download `sevalla-windows-x64.exe` from the [latest release](https://github.com/sevalla-hosting/cli/releases/latest) and put it on your `PATH`. To update or remove the CLI, see [Update or uninstall](https://docs.sevalla.com/developer-tools/cli#update-or-uninstall). ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} # Sign in through the browser. The CLI saves the new API key to ~/.config/sevalla/credentials.json. sevalla login sevalla auth status # Authenticated (source: credentials_file) # In CI, pass an API key instead. It takes priority over the saved key. export SEVALLA_API_TOKEN="svl_..." sevalla auth status # Authenticated (source: environment) ``` [Sign in](https://docs.sevalla.com/developer-tools/cli#sign-in) and [Use an API key in CI](https://docs.sevalla.com/developer-tools/cli#use-an-api-key-in-ci) explain both ways. ## Global flags and environment variables | Flag or variable | What it does | | - | - | | `--json` | Prints JSON instead of tables. The CLI also prints JSON whenever its output isn't a terminal: a pipe, a file or a CI log. In 1.10.1 the flag on its own doesn't switch a terminal to JSON, so pipe the output (to `jq`, for example) to read JSON in a terminal. | | `--api-url ` | Uses another API base URL. In 1.10.1 only `sevalla login` reads this flag and other commands ignore it: set `SEVALLA_API_URL` instead. | | `-V`, `--version` | Prints the version. The Homebrew, shell script and Windows binaries print `1.10.1`. An npm install prints `0.0.0-dev`: check it with `npm ls -g @sevalla/cli`. | | `-h`, `--help` | Prints the arguments and flags of a command or a group, for example `sevalla apps deployments --help`. | | `SEVALLA_API_TOKEN` | The API key to use. Overrides the key from `sevalla login`. | | `SEVALLA_API_URL` | The API base URL. Default `https://api.sevalla.com/v3`. | ## How commands work * **Syntax.** `` is a value you supply. A flag in brackets, such as `[--branch ]`, is optional. A flag without brackets is required: without it, the command stops with `error: required option '--cluster ' not specified`. An unknown flag stops it with `error: unknown option`. * **IDs.** `` and names that end in `-id` are the `id` values that list commands print. Services, deployments and most other objects have UUIDs, and the dashboard shows a service ID on its **Settings** tab. * **Values.** `` is `true` or `false`. Plural values, such as ``, ``, `` or ``, are comma-separated lists without spaces: `--ip-list 203.0.113.10,198.51.100.0/24`. `` is an ISO 8601 timestamp in UTC: `2026-10-18T09:00:00Z`. Quote values that contain spaces. * **Parent IDs.** A command on part of a service takes the parent ID as an argument (`sevalla apps domains delete `) or as a flag (`sevalla apps domains get --app-id `). Each invocation below shows which. * **Pages.** List commands with `[--page ] [--per-page ]` return one page. `--page` defaults to `1` and `--per-page` to `25`. The CLI sends them as `offset` and `limit`, and the API accepts a `limit` of `1` to `100` (see [Pagination](/v3/pagination)). List commands without these flags print what the API returns in one response. * **Metrics.** Time-series commands take `[--from ]` (default 24 hours ago), `[--to ]` (default now) and `[--interval ]` (default `3600`). * **Dry run.** `--dry-run` prints a JSON summary and calls nothing. A `create` or `update` right after a group name, such as `sevalla apps create` or `sevalla webhooks update`, and `sevalla pipelines preview update` print the flag values you passed, or the method, path and body with `--data`. Every other command prints only the command name and the IDs, not the values it would send. * **Raw body.** `apps create`, `apps update`, `usage-alerts create` and `usage-alerts update` take `--data `: the CLI sends that JSON as the request body and ignores the other flags. On the two create commands, the required flags are still required. * **Deletes.** Delete and remove commands need `--confirm`, and the CLI doesn't prompt. Without it, the command exits with `Use --confirm to confirm deletion.` A `--dry-run` doesn't need `--confirm`. * **JSON.** Every command except `login`, `logout`, `completion` and `schema` accepts `--json`. See [Global flags and environment variables](#global-flags-and-environment-variables) for when it applies. ## Output and errors * With JSON output, a list command prints the array of items and the other commands print the object the API returns. A delete prints `"deleted": true` with the IDs, and an action that gets no response body prints `{"success": true}`. * In a terminal, the CLI prints a table or a short list of fields, and a list ends with a line such as `Showing 1-25 of 140`. Use JSON output to get every field. * Errors go to stderr and the command exits with status `1`. With JSON output, an API error prints `{"error": {"status": 404, "message": "Not Found"}}`, with `code` and `detail` when the API sends them. See [Errors](/v3/errors). * A request that takes longer than 30 s fails. ## Authentication | Command | What it does | API operation | | - | - | - | | `sevalla login` | Signs you in through the browser. Prints a device code, opens `https://app.sevalla.com/authorize`, checks every 5 s until you authorize, then saves the new API key to `~/.config/sevalla/credentials.json`. If you're signed in already, it warns and signs you in again. | [Create device code](/v3/device-authorization/create-device-code), [Poll device code status](/v3/device-authorization/poll-device-code-status) | | `sevalla logout` | Deletes `~/.config/sevalla/credentials.json`. The API key stays valid until you delete it under **Tools** > **API keys**. | None | | `sevalla auth status` | Shows whether the CLI has a key and where it comes from: `environment` or `credentials_file`. JSON: `{"logged_in": true, "source": "environment"}`. It doesn't check the key with the API: `sevalla api-keys validate` does. | None | ## Applications | Command | What it does | API operation | | - | - | - | | `sevalla apps list [--page ] [--per-page ]` | Lists applications: ID, name and status. | [List applications](/v3/applications/list-applications) | | `sevalla apps get ` | Shows an application. | [Get application](/v3/applications/get-application) | | `sevalla apps create --name --cluster --source [--project ] [--git-type ] [--repository ] [--branch ] [--docker-registry ] [--docker-image ] [--data ] [--dry-run]` | Creates an application with a default web process and automatic deployments off. It doesn't deploy: run `sevalla apps deployments trigger` next. | [Create application](/v3/applications/create-application) | | `sevalla apps update [--display-name ] [--branch ] [--build-type ] [--dockerfile-path ] [--docker-image ] [--git-lfs-enabled ] [--data ] [--dry-run]` | Updates an application. Build changes apply at the next deployment. | [Update application](/v3/applications/update-application) | | `sevalla apps delete --confirm [--dry-run]` | Deletes an application with its processes, deployments and environment variables. Fails while a deployment is running. | [Delete application](/v3/applications/delete-application) | | `sevalla apps activate [--dry-run]` | Starts a suspended application again. | [Activate application](/v3/applications/activate-application) | | `sevalla apps suspend [--dry-run]` | Stops every process of an application and keeps its settings, environment variables and deployments. | [Suspend application](/v3/applications/suspend-application) | | `sevalla apps clone --display-name [--cluster ] [--dry-run]` | Copies an application with its processes, environment variables and settings, and deploys the copy. | [Clone application](/v3/applications/clone-application) | | `sevalla apps purge-cache [--dry-run]` | Clears the edge cache of an application. | [Purge edge cache](/v3/applications/purge-edge-cache) | | `sevalla apps cdn-toggle [--dry-run]` | Turns the CDN off if it's on, or on if it's off, and returns the new state. | [Toggle CDN](/v3/applications/toggle-cdn) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `apps create` | `--name ` | string | None | Required. Display name, 2 to 64 characters. | | `apps create` | `--cluster ` | UUID | None | Required. Location, from `sevalla resources clusters`. | | `apps create` | `--source ` | `privateGit`, `publicGit` or `dockerImage` | None | Required. A repository from a connected Git account, a public repository URL, or a Docker image. | | `apps create` | `--project ` | UUID | None | Project to add the application to. | | `apps create` | `--git-type ` | `github`, `bitbucket` or `gitlab` | Detected | Git provider, for `privateGit` when the API can't detect it. | | `apps create` | `--repository ` | URL | None | Repository URL. The API requires it for `privateGit` and `publicGit`. | | `apps create` | `--branch ` | string | Repository default branch | Branch to deploy. | | `apps create` | `--docker-registry ` | UUID | None | Registry credential for a private image, from `sevalla docker-registries list`. | | `apps create` | `--docker-image ` | string | None | Image with a tag or digest, such as `nginx:1.27`. The API requires it for `dockerImage`. | | `apps create`, `apps update` | `--data ` | JSON object | None | Request body to send instead of the flags. The fields are on [Create application](/v3/applications/create-application) and [Update application](/v3/applications/update-application). | | `apps update` | `--display-name ` | string | None | New display name, 1 to 64 characters. | | `apps update` | `--branch ` | string | None | New default branch for deployments. | | `apps update` | `--build-type ` | `nixpacks`, `railpack`, `dockerfile` or `pack` | None | Build strategy. | | `apps update` | `--dockerfile-path ` | string | None | Dockerfile path in the repository, for the `dockerfile` build type. | | `apps update` | `--docker-image ` | string | None | Image to run, for a `dockerImage` application. | | `apps update` | `--git-lfs-enabled ` | `true` or `false` | None | Fetches Git LFS objects at checkout, which is on by default. Any value other than `true` turns it off. | | `apps clone` | `--display-name ` | string | None | Required. Name of the copy, unique in the company. | | `apps clone` | `--cluster ` | UUID | Cluster of the source | Location of the copy. | `apps create` doesn't deploy, and `--data` sends fields that have no flag: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} # Create an application from a public repository, then start its first deployment APP_ID=$(sevalla apps create --name storefront --cluster "$CLUSTER_ID" \ --source publicGit --repository https://github.com/acme/storefront --branch main | jq -r '.id') sevalla apps deployments trigger "$APP_ID" # Build from a Dockerfile in a subdirectory: docker_context has no flag sevalla apps update "$APP_ID" --data '{"build_type": "dockerfile", "dockerfile_path": "docker/Dockerfile", "docker_context": "docker"}' ``` ### Deployments | Command | What it does | API operation | | - | - | - | | `sevalla apps deployments list --app-id [--page ] [--per-page ]` | Lists the deployments of an application, newest first: ID, status and creation time. | [List deployments](/v3/applications/list-deployments) | | `sevalla apps deployments get --app-id ` | Shows a deployment and its status. | [Get deployment](/v3/applications/get-deployment) | | `sevalla apps deployments trigger [--branch ] [--dry-run]` | Deploys the latest commit of `--branch`, or of the default branch without it, and returns the new deployment. | [Trigger deployment](/v3/applications/trigger-deployment) | | `sevalla apps deployments rollback [--dry-run]` | Creates a deployment from the build of the most recent successful deployment, with no rebuild. It takes no deployment ID. | [Rollback deployment](/v3/applications/rollback-deployment) | | `sevalla apps deployments cancel --app-id ` | Cancels a waiting or running deployment. A finished deployment returns `400`. | [Cancel deployment](/v3/applications/cancel-deployment) | | `sevalla apps deployments logs --app-id ` | Prints the build and rollout log: up to 1,000 entries from the last hour, oldest first. | [Get application deployment logs](/v3/applications/get-application-deployment-logs) | `logs` sends no time range, so the API returns the last hour. For an older deployment, call [Get application deployment logs](/v3/applications/get-application-deployment-logs) with `from` and `to`. ### Processes | Command | What it does | API operation | | - | - | - | | `sevalla apps processes list --app-id [--page ] [--per-page ]` | Lists the processes of an application: ID, key, start command, internal hostname, scaling and size. | [List processes](/v3/applications/list-processes) | | `sevalla apps processes get --app-id ` | Shows a process. | [Get process](/v3/applications/get-process) | | `sevalla apps processes create --name --type --resource-type [--command ] [--instances ] [--schedule ] [--job-start-policy ] [--dry-run]` | Creates a process with a fixed number of instances. It starts at the next deployment. | [Create process](/v3/applications/create-process) | | `sevalla apps processes update --app-id [--name ] [--command ] [--resource-type ] [--instances ]` | Updates a process. Size and scaling changes apply at the next deployment. | [Update process](/v3/applications/update-process) | | `sevalla apps processes delete --app-id --confirm` | Deletes a process other than the web process. It's removed at the next deployment. | [Delete process](/v3/applications/delete-process) | | `sevalla apps processes trigger --app-id ` | Runs a cron job now, outside its schedule. | [Trigger cron job](/v3/applications/trigger-cron-job) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `apps processes create` | `--name ` | string | None | Required. Display name, 1 to 255 characters. | | `apps processes create` | `--type ` | `web`, `worker`, `cron` or `job` | None | Required. An application has at most one web process. | | `apps processes create` | `--resource-type ` | ID | None | Required. Size, from `sevalla resources process-types`. | | `apps processes create` | `--command ` | string | Empty | Start command. | | `apps processes create` | `--instances ` | integer | `1` | Number of instances. The CLI always sets manual scaling. | | `apps processes create` | `--schedule ` | cron expression | None | Schedule, such as `0 3 * * *`. The API requires it for `cron` processes. | | `apps processes create` | `--job-start-policy ` | `beforeDeployment`, `afterSuccessDeployment` or `afterFailedDeployment` | None | When a job runs. The API requires it for `job` processes. | | `apps processes update` | `--name ` | string | None | New display name. | | `apps processes update` | `--command ` | string | None | New start command. | | `apps processes update` | `--resource-type ` | ID | None | New size, from `sevalla resources process-types`. | | `apps processes update` | `--instances ` | integer | None | Sets manual scaling with this number of instances, replacing any autoscaling. | ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} # Add a cron job, then deploy so that it starts sevalla apps processes create "$APP_ID" --name nightly-report --type cron \ --resource-type "$SIZE_ID" --command "npm run report" --schedule "0 3 * * *" sevalla apps deployments trigger "$APP_ID" ``` ### Process metrics | Command | What it does | API operation | | - | - | - | | `sevalla apps processes metrics cpu-usage [--from ] [--to ] [--interval ]` | CPU used over time, in cores. | [Get process CPU usage](/v3/applications/get-process-cpu-usage) | | `sevalla apps processes metrics cpu-limit [--from ] [--to ] [--interval ]` | CPU limit over time, in cores. | [Get process CPU limit](/v3/applications/get-process-cpu-limit) | | `sevalla apps processes metrics memory-usage [--from ] [--to ] [--interval ]` | Memory used over time, in bytes. | [Get process memory usage](/v3/applications/get-process-memory-usage) | | `sevalla apps processes metrics memory-limit [--from ] [--to ] [--interval ]` | Memory limit over time, in bytes. | [Get process memory limit](/v3/applications/get-process-memory-limit) | | `sevalla apps processes metrics instance-count [--from ] [--to ] [--interval ]` | Running instances over time. | [Get process instance count](/v3/applications/get-process-instance-count) | | `sevalla apps processes metrics exit-codes [--from ] [--to ]` | Exit codes in the range, each with its time and a description when one is known. | [Get process exit codes](/v3/applications/get-process-exit-codes) | ### Environment variables | Command | What it does | API operation | | - | - | - | | `sevalla apps env-vars list --app-id [--page ] [--per-page ]` | Lists the environment variables of an application with their values. | [List environment variables](/v3/applications/list-environment-variables) | | `sevalla apps env-vars create --key --value [--dry-run]` | Adds an environment variable, available at build time and at runtime. It applies at the next deployment. | [Create environment variable](/v3/applications/create-environment-variable) | | `sevalla apps env-vars update --app-id [--key ] [--value ]` | Changes the key or the value of an environment variable. It applies at the next deployment. | [Update environment variable](/v3/applications/update-environment-variable) | | `sevalla apps env-vars delete --confirm [--dry-run]` | Deletes an environment variable. It applies at the next deployment. | [Delete environment variable](/v3/applications/delete-environment-variable) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `apps env-vars create` | `--key ` | string | None | Required. Name, 1 to 255 characters, unique in the application. | | `apps env-vars create` | `--value ` | string | None | Required. Up to 32,768 characters, stored encrypted. | | `apps env-vars update` | `--key `, `--value ` | string | None | New name or value. An empty value isn't sent. | ### Domains | Command | What it does | API operation | | - | - | - | | `sevalla apps domains list --app-id [--page ] [--per-page ]` | Lists the system and custom domains of an application: ID, name, status and whether it's primary. | [List application domains](/v3/applications/list-application-domains) | | `sevalla apps domains get --app-id ` | Shows a domain with its verification status and DNS records. | [Get application domain](/v3/applications/get-application-domain) | | `sevalla apps domains add --name [--dry-run]` | Adds a custom domain, such as `shop.example.com`. Add the DNS records from the response: the status then moves from `verification` to `pointing` to `active`. | [Add application domain](/v3/applications/add-application-domain) | | `sevalla apps domains update --app-id --name ` | Renames the subdomain of the system domain. Custom domains can't be renamed. | [Update application system domain](/v3/applications/update-application-system-domain) | | `sevalla apps domains delete --confirm [--dry-run]` | Deletes a custom domain. The system domain can't be deleted: turn it off with `toggle`. | [Delete application domain](/v3/applications/delete-application-domain) | | `sevalla apps domains refresh-status [--dry-run]` | Checks the verification and DNS of a domain again, for example after you change its records. | [Refresh application domain status](/v3/applications/refresh-application-domain-status) | | `sevalla apps domains set-primary [--dry-run]` | Makes a domain the primary domain, used for canonical URLs and redirects. | [Set primary application domain](/v3/applications/set-primary-application-domain) | | `sevalla apps domains toggle [--dry-run]` | Turns the system domain off or on. Custom domains can't be toggled. | [Toggle application system domain](/v3/applications/toggle-application-system-domain) | ### Deployment hook | Command | What it does | API operation | | - | - | - | | `sevalla apps deployment-hook get ` | Shows the deployment hook URL. Returns `404` when the hook is off. | [Get deployment hook URL](/v3/applications/get-deployment-hook-url) | | `sevalla apps deployment-hook enable [--dry-run]` | Turns on the deployment hook and returns its URL: a `POST` to the URL starts a deployment. If the hook is on already, returns the same URL. | [Enable deployment hook](/v3/applications/enable-deployment-hook) | | `sevalla apps deployment-hook regenerate [--dry-run]` | Returns a new hook URL. The old URL stops working at once. | [Regenerate deployment hook](/v3/applications/regenerate-deployment-hook) | | `sevalla apps deployment-hook disable [--dry-run]` | Turns off the deployment hook. Its URL stops working at once. | [Disable deployment hook](/v3/applications/disable-deployment-hook) | ### Logs | Command | What it does | API operation | | - | - | - | | `sevalla apps logs runtime ` | Prints what the processes write to stdout and stderr. | [Get application runtime logs](/v3/applications/get-application-runtime-logs) | | `sevalla apps logs access ` | Prints the HTTP requests the application handled. | [Get application access logs](/v3/applications/get-application-access-logs) | Both commands send no time range or filter, so the API returns up to 1,000 entries from the last hour, oldest first. For another range, a text search or the newest entries first, call the API operation with `from`, `to`, `search` or `order`. ### IP restrictions | Command | What it does | API operation | | - | - | - | | `sevalla apps ip-restriction get ` | Shows the IP restriction: type, whether it's on and the IP list. Without one, returns type `deny`, off, with an empty list. | [Get IP restriction](/v3/applications/get-ip-restriction) | | `sevalla apps ip-restriction update --type --ip-list --enabled ` | Replaces the IP restriction of an application. | [Update IP restriction](/v3/applications/update-ip-restriction) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `apps ip-restriction update` | `--type ` | `allow` or `deny` | None | Required. `allow` lets only the listed addresses in, and `deny` blocks them. | | `apps ip-restriction update` | `--ip-list ` | list | None | Required. IP addresses or CIDR ranges, such as `203.0.113.10,198.51.100.0/24`. | | `apps ip-restriction update` | `--enabled ` | `true` or `false` | None | Required. Whether the restriction applies. Other values are rejected. | ### TCP proxies | Command | What it does | API operation | | - | - | - | | `sevalla apps tcp-proxies list --app-id [--page ] [--per-page ]` | Lists the TCP proxies of an application: ID, port and status. | [List TCP proxies](/v3/applications/list-tcp-proxies) | | `sevalla apps tcp-proxies create --process-id --port [--dry-run]` | Exposes a container port of a process on a public hostname and port for direct TCP connections. | [Create TCP proxy](/v3/applications/create-tcp-proxy) | | `sevalla apps tcp-proxies delete --confirm [--dry-run]` | Deletes a TCP proxy and releases its public hostname and port. | [Delete TCP proxy](/v3/applications/delete-tcp-proxy) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `apps tcp-proxies create` | `--process-id ` | UUID | None | Required. Process to expose, from `sevalla apps processes list`. | | `apps tcp-proxies create` | `--port ` | integer | None | Required. Container port, `1` to `65535`. | ### Private ports | Command | What it does | API operation | | - | - | - | | `sevalla apps private-ports list --app-id [--page ] [--per-page ]` | Lists the private ports of an application: ID, port and protocol. | [List private ports](/v3/applications/list-private-ports) | | `sevalla apps private-ports create --process-id --port [--dry-run]` | Exposes a container port of a process to other services in the cluster, with no public access. | [Create private port](/v3/applications/create-private-port) | | `sevalla apps private-ports delete --confirm [--dry-run]` | Deletes a private port. | [Delete private port](/v3/applications/delete-private-port) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `apps private-ports create` | `--process-id ` | UUID | None | Required. Process to expose, from `sevalla apps processes list`. | | `apps private-ports create` | `--port ` | integer | None | Required. Container port, `1` to `65535`. | ### Application metrics | Command | What it does | API operation | | - | - | - | | `sevalla apps metrics requests-per-minute [--from ] [--to ] [--interval ]` | Requests per minute over time. | [Get application requests per minute](/v3/applications/get-application-requests-per-minute) | | `sevalla apps metrics response-time [--from ] [--to ] [--interval ]` | Response time over time. | [Get application response time](/v3/applications/get-application-response-time) | | `sevalla apps metrics response-time-avg [--from ] [--to ] [--interval ]` | Average response time over the range, in milliseconds, as one value. | [Get application average response time](/v3/applications/get-application-average-response-time) | | `sevalla apps metrics status-codes [--from ] [--to ] [--interval ]` | Requests per HTTP status code over time. | [Get application status code breakdown](/v3/applications/get-application-status-code-breakdown) | | `sevalla apps metrics top-status-codes [--from ] [--to ] [--interval ]` | The 10 most frequent status codes, by request count. | [Get application top status codes](/v3/applications/get-application-top-status-codes) | | `sevalla apps metrics top-countries [--from ] [--to ] [--interval ]` | The 10 countries that send the most requests, with their average response time. | [Get application top countries](/v3/applications/get-application-top-countries) | | `sevalla apps metrics slowest-requests [--from ] [--to ] [--interval ]` | The 10 slowest paths by average response time, with method and request count. | [Get application slowest requests](/v3/applications/get-application-slowest-requests) | | `sevalla apps metrics top-pages [--from ] [--to ] [--interval ]` | The 10 most requested paths. | [Get application top pages](/v3/applications/get-application-top-pages) | ## Databases | Command | What it does | API operation | | - | - | - | | `sevalla databases list [--page ] [--per-page ]` | Lists databases: ID, name, type and status. | [List databases](/v3/databases/list-databases) | | `sevalla databases get ` | Shows a database with its hostnames and status. | [Get database](/v3/databases/get-database) | | `sevalla databases create --name --type --db-version --cluster --resource-type --db-name --db-password [--project ] [--db-user ] [--dry-run]` | Creates a database. Its status is `creating` until it's `ready`. | [Create database](/v3/databases/create-database) | | `sevalla databases update [--display-name ] [--resource-type ] [--dry-run]` | Renames a database or changes its size. A size change runs in the background. | [Update database](/v3/databases/update-database) | | `sevalla databases delete --confirm [--dry-run]` | Deletes a database and its data. Fails while it's creating, updating, deleting or backing up. | [Delete database](/v3/databases/delete-database) | | `sevalla databases activate [--dry-run]` | Starts a suspended database again. | [Activate database](/v3/databases/activate-database) | | `sevalla databases suspend [--dry-run]` | Stops a database and keeps its settings and data. | [Suspend database](/v3/databases/suspend-database) | | `sevalla databases restart [--dry-run]` | Restarts a database and keeps its data. The status is `updating` until it's `ready` again. Works when the status is `ready`, `error`, `passwordChangeFailed` or `restoringFailed`, the database isn't suspended and no backup is running. | [Restart database](/v3/databases/restart-database) | | `sevalla databases reset-password --new-password [--dry-run]` | Sets a new password for the database user. The status is `passwordChange` until it's `ready` again. | [Reset database password](/v3/databases/reset-database-password) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `databases create` | `--name ` | string | None | Required. Display name, 2 to 64 characters. | | `databases create` | `--type ` | `postgresql`, `mysql`, `mariadb`, `redis` or `valkey` | None | Required. Engine. The CLI help also lists `mongodb`, which the API doesn't accept. | | `databases create` | `--db-version ` | string | None | Required. Engine version available for the type and cluster, such as `16` for PostgreSQL. | | `databases create` | `--cluster ` | UUID | None | Required. Location, from `sevalla resources clusters`. | | `databases create` | `--resource-type ` | ID | None | Required. Size, from `sevalla resources db-types`. | | `databases create` | `--db-name ` | string | None | Required. Name of the database inside the server: 2 to 100 letters, digits, `_`, `-` or `+`. | | `databases create` | `--db-password ` | string | None | Required. 4 to 100 letters, digits or `_?<>#@-=+` characters. | | `databases create` | `--project ` | UUID | None | Project to add the database to. | | `databases create` | `--db-user ` | string | Engine default user | User name, 2 to 32 characters, not `root` or `postgres`. | | `databases update` | `--display-name ` | string | None | New display name, 2 to 64 characters. | | `databases update` | `--resource-type ` | ID | None | New size, from `sevalla resources db-types`. | | `databases reset-password` | `--new-password ` | string | None | Required. Same rules as `--db-password`. | ### Database metrics | Command | What it does | API operation | | - | - | - | | `sevalla databases metrics cpu-usage [--from ] [--to ] [--interval ]` | CPU used over time, in cores. | [Get database CPU usage](/v3/databases/get-database-cpu-usage) | | `sevalla databases metrics cpu-limit [--from ] [--to ] [--interval ]` | CPU limit over time, in cores. | [Get database CPU limit](/v3/databases/get-database-cpu-limit) | | `sevalla databases metrics memory-usage [--from ] [--to ] [--interval ]` | Memory used over time, in bytes. | [Get database memory usage](/v3/databases/get-database-memory-usage) | | `sevalla databases metrics memory-limit [--from ] [--to ] [--interval ]` | Memory limit over time, in bytes. | [Get database memory limit](/v3/databases/get-database-memory-limit) | | `sevalla databases metrics storage-usage [--from ] [--to ] [--interval ]` | Storage used over time, in bytes. | [Get database storage usage](/v3/databases/get-database-storage-usage) | | `sevalla databases metrics storage-limit [--from ] [--to ] [--interval ]` | Storage limit over time, in bytes. | [Get database storage limit](/v3/databases/get-database-storage-limit) | | `sevalla databases metrics all-storage ` | Total storage allocated now, in bytes. | [Get database total storage](/v3/databases/get-database-total-storage) | | `sevalla databases metrics used-storage ` | Storage used now, in bytes. | [Get database used storage](/v3/databases/get-database-used-storage) | ### Backups | Command | What it does | API operation | | - | - | - | | `sevalla databases backups list --db-id ` | Lists all backups of a database: daily backups, kept 7 days, and manual backups, kept 14 days. | [List database backups](/v3/databases/list-database-backups) | | `sevalla databases backups create --name [--dry-run]` | Starts a manual backup, kept 14 days. It appears in the list when it's done. | [Create database backup](/v3/databases/create-database-backup) | | `sevalla databases backups delete --confirm [--dry-run]` | Deletes a backup. | [Delete database backup](/v3/databases/delete-database-backup) | | `sevalla databases backups restore [--dry-run]` | Restores a backup into the same database and replaces its current data. To restore into another database, call the API operation with `target_database_id`. | [Restore database backup](/v3/databases/restore-database-backup) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `databases backups create` | `--name ` | string | None | Required. Backup name. | ### Connections | Command | What it does | API operation | | - | - | - | | `sevalla databases connections internal-list --db-id ` | Lists the internal connections of a database, as source or target. | [List internal connections](/v3/databases/list-internal-connections) | | `sevalla databases connections internal-create --target-id [--target-type ] [--dry-run]` | Connects the database to an application or another database in the same cluster. A connection to an application covers all its processes. | [Create internal connection](/v3/databases/create-internal-connection) | | `sevalla databases connections internal-delete --confirm [--dry-run]` | Deletes an internal connection. | [Delete internal connection](/v3/databases/delete-internal-connection) | | `sevalla databases connections external-toggle [--dry-run]` | Turns access from outside the cluster on or off. | [Toggle external connection](/v3/databases/toggle-external-connection) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `databases connections internal-create` | `--target-id ` | UUID | None | Required. Application or database to connect. | | `databases connections internal-create` | `--target-type ` | `app` or `database` | `app` | Type of the target. | ### Database IP restrictions | Command | What it does | API operation | | - | - | - | | `sevalla databases ip-restriction get ` | Shows the IP restriction of a database. Without one, returns type `deny`, off, with an empty list. | [Get database IP restriction](/v3/databases/get-database-ip-restriction) | | `sevalla databases ip-restriction update --type --ip-list --enabled ` | Replaces the IP restriction. It applies to external connections only. | [Update database IP restriction](/v3/databases/update-database-ip-restriction) | `--type`, `--ip-list` and `--enabled` take the same values as in [IP restrictions](#ip-restrictions) for applications. ## Static sites | Command | What it does | API operation | | - | - | - | | `sevalla static-sites list [--page ] [--per-page ]` | Lists static sites: ID, name and status. | [List static sites](/v3/static-sites/list-static-sites) | | `sevalla static-sites get ` | Shows a static site. | [Get static site](/v3/static-sites/get-static-site) | | `sevalla static-sites create --name --repository --branch [--project ] [--source ] [--git-type ] [--build-command ] [--publish-directory ] [--node-version ] [--allow-deploy-paths ] [--ignore-deploy-paths ] [--dry-run]` | Creates a static site from a Git repository and starts its first deployment. | [Create static site](/v3/static-sites/create-static-site) | | `sevalla static-sites update [--display-name ] [--branch ] [--build-command ] [--publish-directory ] [--allow-deploy-paths ] [--ignore-deploy-paths ] [--git-lfs-enabled ] [--dry-run]` | Updates a static site. Build changes apply at the next deployment. | [Update static site](/v3/static-sites/update-static-site) | | `sevalla static-sites delete --confirm [--dry-run]` | Deletes a static site with its deployments and custom domains. | [Delete static site](/v3/static-sites/delete-static-site) | | `sevalla static-sites purge-cache [--dry-run]` | Clears the edge cache of a static site. | [Purge edge cache](/v3/static-sites/purge-edge-cache) | | `sevalla static-sites pretty-url-toggle [--dry-run]` | Turns pretty URLs on or off and prints the new state. With pretty URLs, `/about` serves `/about/index.html` or `/about.html`. | [Toggle pretty URLs](/v3/static-sites/toggle-pretty-urls) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `static-sites create` | `--name ` | string | None | Required. Display name, 2 to 64 characters. | | `static-sites create` | `--repository ` | URL | None | Required. Repository URL. | | `static-sites create` | `--branch ` | string | None | Required. Branch to deploy. | | `static-sites create` | `--project ` | UUID | None | Project to add the static site to. | | `static-sites create` | `--source ` | `privateGit` or `publicGit` | API default: `privateGit` | A repository from a connected Git account, or a public repository URL. | | `static-sites create` | `--git-type ` | `github`, `bitbucket` or `gitlab` | Detected | Git provider, for `privateGit` when the API can't detect it. | | `static-sites create`, `static-sites update` | `--build-command ` | string | None | Build command, such as `npm run build`. | | `static-sites create`, `static-sites update` | `--publish-directory ` | string | None | Directory with the built files, such as `dist`. | | `static-sites create` | `--node-version ` | string | None | Node.js version for the build. | | `static-sites create`, `static-sites update` | `--allow-deploy-paths ` | list of glob patterns | None | Only commits that touch these paths start an automatic deployment. Can't be combined with `--ignore-deploy-paths`. | | `static-sites create`, `static-sites update` | `--ignore-deploy-paths ` | list of glob patterns | None | Commits that touch only these paths don't start an automatic deployment. | | `static-sites update` | `--display-name ` | string | None | New display name, 1 to 64 characters. | | `static-sites update` | `--branch ` | string | None | New default branch. | | `static-sites update` | `--git-lfs-enabled ` | `true` or `false` | None | Fetches Git LFS objects at checkout, which is on by default. Any value other than `true` turns it off. | ### Static site deployments | Command | What it does | API operation | | - | - | - | | `sevalla static-sites deployments list --site-id [--page ] [--per-page ]` | Lists the deployments of a static site, newest first. | [List static site deployments](/v3/static-sites/list-static-site-deployments) | | `sevalla static-sites deployments get --site-id ` | Shows a deployment and its status. | [Get static site deployment](/v3/static-sites/get-static-site-deployment) | | `sevalla static-sites deployments trigger [--branch ] [--dry-run]` | Deploys the latest commit of `--branch`, or of the default branch without it. | [Deploy static site](/v3/static-sites/deploy-static-site) | | `sevalla static-sites deployments cancel --site-id ` | Cancels a waiting or running deployment. | [Cancel static site deployment](/v3/static-sites/cancel-static-site-deployment) | | `sevalla static-sites deployments logs --site-id ` | Prints the build and publish log: up to 1,000 entries from the last hour, oldest first. | [Get static site deployment logs](/v3/static-sites/get-static-site-deployment-logs) | The CLI has no rollback command for static sites. To redeploy an earlier deployment, call [Deploy static site](/v3/static-sites/deploy-static-site) with `deployment_id`. ### Static site domains | Command | What it does | API operation | | - | - | - | | `sevalla static-sites domains list --site-id [--page ] [--per-page ]` | Lists the system and custom domains of a static site: ID, name, status and whether it's primary. | [List static site domains](/v3/static-sites/list-static-site-domains) | | `sevalla static-sites domains get --site-id ` | Shows a domain with its verification status and DNS records. | [Get static site domain](/v3/static-sites/get-static-site-domain) | | `sevalla static-sites domains add --name [--dry-run]` | Adds a custom domain, such as `shop.example.com`. Add the DNS records from the response: the status then moves from `verification` to `pointing` to `active`. | [Add static site domain](/v3/static-sites/add-static-site-domain) | | `sevalla static-sites domains update --site-id --name ` | Renames the subdomain of the system domain. Custom domains can't be renamed. | [Update static site system domain](/v3/static-sites/update-static-site-system-domain) | | `sevalla static-sites domains delete --confirm [--dry-run]` | Deletes a custom domain. The system domain can't be deleted: turn it off with `toggle`. | [Delete static site domain](/v3/static-sites/delete-static-site-domain) | | `sevalla static-sites domains refresh-status [--dry-run]` | Checks the verification and DNS of a domain again. | [Refresh static site domain status](/v3/static-sites/refresh-static-site-domain-status) | | `sevalla static-sites domains set-primary [--dry-run]` | Makes a domain the primary domain, used for canonical URLs and redirects. | [Set primary static site domain](/v3/static-sites/set-primary-static-site-domain) | | `sevalla static-sites domains toggle [--dry-run]` | Turns the system domain off or on. Custom domains can't be toggled. | [Toggle static site system domain](/v3/static-sites/toggle-static-site-system-domain) | ### Static site environment variables | Command | What it does | API operation | | - | - | - | | `sevalla static-sites env-vars list --site-id [--page ] [--per-page ]` | Lists the environment variables of a static site with their values. | [List static site environment variables](/v3/static-sites/list-static-site-environment-variables) | | `sevalla static-sites env-vars create --key --value [--dry-run]` | Adds an environment variable for production and preview deployments on every branch. It applies at the next deployment. | [Create static site environment variable](/v3/static-sites/create-static-site-environment-variable) | | `sevalla static-sites env-vars update --site-id [--key ] [--value ]` | Changes the key or the value of an environment variable. An empty value isn't sent. | [Update static site environment variable](/v3/static-sites/update-static-site-environment-variable) | | `sevalla static-sites env-vars delete --confirm [--dry-run]` | Deletes an environment variable. It applies at the next deployment. | [Delete static site environment variable](/v3/static-sites/delete-static-site-environment-variable) | `--key` takes 1 to 255 characters and `--value` up to 32,768 characters, as for applications. ### Static site logs | Command | What it does | API operation | | - | - | - | | `sevalla static-sites logs access ` | Prints the HTTP requests the static site served: up to 1,000 entries from the last hour, oldest first. | [Get static site access logs](/v3/static-sites/get-static-site-access-logs) | ### Static site metrics | Command | What it does | API operation | | - | - | - | | `sevalla static-sites metrics requests-per-minute [--from ] [--to ] [--interval ]` | Requests per minute over time. | [Get static site requests per minute](/v3/static-sites/get-static-site-requests-per-minute) | | `sevalla static-sites metrics response-time [--from ] [--to ] [--interval ]` | Response time over time. | [Get static site response time](/v3/static-sites/get-static-site-response-time) | | `sevalla static-sites metrics response-time-avg [--from ] [--to ] [--interval ]` | Average response time over the range, in milliseconds, as one value. | [Get static site average response time](/v3/static-sites/get-static-site-average-response-time) | | `sevalla static-sites metrics status-codes [--from ] [--to ] [--interval ]` | Requests per HTTP status code over time. | [Get static site status code breakdown](/v3/static-sites/get-static-site-status-code-breakdown) | | `sevalla static-sites metrics top-status-codes [--from ] [--to ] [--interval ]` | The 10 most frequent status codes, by request count. | [Get static site top status codes](/v3/static-sites/get-static-site-top-status-codes) | | `sevalla static-sites metrics top-countries [--from ] [--to ] [--interval ]` | The 10 countries that send the most requests. | [Get static site top countries](/v3/static-sites/get-static-site-top-countries) | | `sevalla static-sites metrics slowest-requests [--from ] [--to ] [--interval ]` | The 10 slowest paths by average response time. | [Get static site slowest requests](/v3/static-sites/get-static-site-slowest-requests) | | `sevalla static-sites metrics top-pages [--from ] [--to ] [--interval ]` | The 10 most requested paths. | [Get static site top pages](/v3/static-sites/get-static-site-top-pages) | ## Load balancers | Command | What it does | API operation | | - | - | - | | `sevalla load-balancers list [--page ] [--per-page ]` | Lists load balancers, newest first: ID, name and status. | [List load balancers](/v3/load-balancers/list-load-balancers) | | `sevalla load-balancers get ` | Shows a load balancer with its routing type. | [Get load balancer](/v3/load-balancers/get-load-balancer) | | `sevalla load-balancers create --name [--project ] [--type ] [--dry-run]` | Creates a load balancer with no destinations. | [Create load balancer](/v3/load-balancers/create-load-balancer) | | `sevalla load-balancers update [--display-name ] [--type ] [--dry-run]` | Renames a load balancer or changes its routing type. | [Update load balancer](/v3/load-balancers/update-load-balancer) | | `sevalla load-balancers delete --confirm [--dry-run]` | Deletes a load balancer and its destinations. | [Delete load balancer](/v3/load-balancers/delete-load-balancer) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `load-balancers create` | `--name ` | string | None | Required. Display name, 2 to 64 characters. | | `load-balancers create` | `--project ` | UUID | None | Project to add the load balancer to. | | `load-balancers create`, `load-balancers update` | `--type ` | `DEFAULT` or `GEO` | API default on create: `DEFAULT` | `DEFAULT` routes round-robin or by weight. `GEO` routes by client location. | | `load-balancers update` | `--display-name ` | string | None | New display name, 2 to 64 characters. | ### Destinations | Command | What it does | API operation | | - | - | - | | `sevalla load-balancers destinations list --lb-id [--page ] [--per-page ]` | Lists the destinations of a load balancer. | [List load balancer destinations](/v3/load-balancers/list-load-balancer-destinations) | | `sevalla load-balancers destinations create --service-type [--service-id ] [--url ] [--weight ] [--latitude ] [--longitude ] [--dry-run]` | Adds a destination. It's on and receives traffic at once. | [Create load balancer destination](/v3/load-balancers/create-load-balancer-destination) | | `sevalla load-balancers destinations delete --confirm [--dry-run]` | Deletes a destination. | [Delete load balancer destination](/v3/load-balancers/delete-load-balancer-destination) | | `sevalla load-balancers destinations toggle [--dry-run]` | Turns a destination off or on. | [Toggle load balancer destination](/v3/load-balancers/toggle-load-balancer-destination) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `load-balancers destinations create` | `--service-type ` | `APP`, `STATIC_SITE`, `OBJECT_STORAGE`, `EXTERNAL` or `LOAD_BALANCER` | None | Required. What receives the traffic: an application, a static site, a bucket, an external URL or another load balancer. | | `load-balancers destinations create` | `--service-id ` | ID | None | The service. Required for every type except `EXTERNAL`. | | `load-balancers destinations create` | `--url ` | URL | None | External URL. Required for `EXTERNAL`. | | `load-balancers destinations create` | `--weight ` | integer | None | Share of traffic for weighted routing, `0` to `10000`. A higher weight gets more traffic. | | `load-balancers destinations create` | `--latitude ` | number | None | Latitude for `GEO` routing, `-90` to `90`. | | `load-balancers destinations create` | `--longitude ` | number | None | Longitude for `GEO` routing, `-180` to `180`. | ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} # Send 80% of the traffic to an application and 20% to an external URL sevalla load-balancers destinations create "$LB_ID" --service-type APP --service-id "$APP_ID" --weight 80 sevalla load-balancers destinations create "$LB_ID" --service-type EXTERNAL --url https://legacy.example.com --weight 20 ``` ### Load balancer domains | Command | What it does | API operation | | - | - | - | | `sevalla load-balancers domains list --lb-id [--page ] [--per-page ]` | Lists the system and custom domains of a load balancer: ID, name, status and whether it's primary. | [List load balancer domains](/v3/load-balancers/list-load-balancer-domains) | | `sevalla load-balancers domains get --lb-id ` | Shows a domain with its verification status and DNS records. | [Get load balancer domain](/v3/load-balancers/get-load-balancer-domain) | | `sevalla load-balancers domains add --name [--dry-run]` | Adds a custom domain, such as `shop.example.com`. Add the DNS records from the response: the status then moves from `verification` to `pointing` to `active`. | [Add load balancer domain](/v3/load-balancers/add-load-balancer-domain) | | `sevalla load-balancers domains update --lb-id --name ` | Renames the subdomain of the system domain. Custom domains can't be renamed. | [Update load balancer system domain](/v3/load-balancers/update-load-balancer-system-domain) | | `sevalla load-balancers domains delete --confirm [--dry-run]` | Deletes a custom domain. The system domain can't be deleted: turn it off with `toggle`. | [Delete load balancer domain](/v3/load-balancers/delete-load-balancer-domain) | | `sevalla load-balancers domains refresh-status [--dry-run]` | Checks the verification and DNS of a domain again. | [Refresh load balancer domain status](/v3/load-balancers/refresh-load-balancer-domain-status) | | `sevalla load-balancers domains set-primary [--dry-run]` | Makes a domain the primary domain, used for canonical URLs. | [Set primary load balancer domain](/v3/load-balancers/set-primary-load-balancer-domain) | | `sevalla load-balancers domains toggle [--dry-run]` | Turns the system domain off or on. Custom domains can't be toggled. | [Toggle load balancer system domain](/v3/load-balancers/toggle-load-balancer-system-domain) | ## Object storage | Command | What it does | API operation | | - | - | - | | `sevalla object-storage list [--page ] [--per-page ]` | Lists buckets: ID, name and status. | [List object storage buckets](/v3/object-storages/list-object-storage-buckets) | | `sevalla object-storage get ` | Shows a bucket with its S3-compatible endpoint, access keys and CDN domain. | [Get object storage bucket](/v3/object-storages/get-object-storage-bucket) | | `sevalla object-storage create --name [--project ] [--location ] [--dry-run]` | Creates a bucket and returns its S3-compatible credentials. | [Create object storage bucket](/v3/object-storages/create-object-storage-bucket) | | `sevalla object-storage update [--display-name ] [--dry-run]` | Renames a bucket. | [Update object storage bucket](/v3/object-storages/update-object-storage-bucket) | | `sevalla object-storage delete --confirm [--dry-run]` | Schedules a bucket for deletion: Sevalla deletes its objects, revokes its keys and removes it in the background. Its status is `deleting` meanwhile. | [Delete object storage bucket](/v3/object-storages/delete-object-storage-bucket) | | `sevalla object-storage rotate-credentials [--old-keys-ttl-hours ] [--dry-run]` | Creates a new access key and secret key. The response is the only time you see them. | [Rotate object storage credentials](/v3/object-storages/rotate-object-storage-credentials) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `object-storage create` | `--name ` | string | None | Required. Display name, 2 to 64 characters. | | `object-storage create` | `--project ` | UUID | None | Project to add the bucket to. | | `object-storage create` | `--location ` | `apac`, `eeur`, `enam`, `oc`, `weur` or `wnam` | API default: `enam` | Where most access happens: Asia-Pacific, Eastern Europe, Eastern North America, Oceania, Western Europe or Western North America. | | `object-storage update` | `--display-name ` | string | None | New display name, 2 to 64 characters. | | `object-storage rotate-credentials` | `--old-keys-ttl-hours ` | integer | API default: `0` | Hours the previous keys keep working, `0` to `168`. `0` stops them at once. | ### CDN domain | Command | What it does | API operation | | - | - | - | | `sevalla object-storage cdn-domain enable [--dry-run]` | Turns on a public CDN domain that serves the objects of the bucket. Fails if one is on already. | [Enable CDN domain](/v3/object-storages/enable-cdn-domain) | | `sevalla object-storage cdn-domain disable [--dry-run]` | Turns off the CDN domain. Objects are no longer served from it. | [Disable CDN domain](/v3/object-storages/disable-cdn-domain) | ### CORS policies | Command | What it does | API operation | | - | - | - | | `sevalla object-storage cors-policies list --bucket-id ` | Lists the CORS rules of a bucket. | [List CORS policies](/v3/object-storages/list-cors-policies) | | `sevalla object-storage cors-policies create --origins --methods [--headers ] [--dry-run]` | Adds a CORS rule after the existing ones. | [Create CORS policy](/v3/object-storages/create-cors-policy) | | `sevalla object-storage cors-policies update --bucket-id --origins --methods [--headers ]` | Replaces a CORS rule, so pass every origin, method and header to keep. | [Update CORS policy](/v3/object-storages/update-cors-policy) | | `sevalla object-storage cors-policies delete --confirm [--dry-run]` | Deletes a CORS rule. Deleting the last rule removes the CORS configuration. | [Delete CORS policy](/v3/object-storages/delete-cors-policy) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `object-storage cors-policies create`, `object-storage cors-policies update` | `--origins ` | list | None | Required. Allowed origins, such as `https://shop.example.com`. | | `object-storage cors-policies create`, `object-storage cors-policies update` | `--methods ` | list of `GET`, `PUT`, `POST`, `DELETE` or `HEAD` | None | Required. Allowed methods. | | `object-storage cors-policies create`, `object-storage cors-policies update` | `--headers ` | list | None | Allowed request headers. | ### Objects | Command | What it does | API operation | | - | - | - | | `sevalla object-storage objects list --bucket-id ` | Lists the first 25 objects of a bucket: key, size and last change. The CLI has no flags for a prefix or the next page. | [List objects](/v3/object-storages/list-objects) | | `sevalla object-storage objects delete --keys --confirm [--dry-run]` | Deletes objects by key, up to 1,000 keys per command. | [Delete objects](/v3/object-storages/delete-objects) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `object-storage objects delete` | `--keys ` | list | None | Required. Keys of the objects to delete. | ## Pipelines | Command | What it does | API operation | | - | - | - | | `sevalla pipelines list [--page ] [--per-page ]` | Lists pipelines: ID, name and status. | [List pipelines](/v3/pipelines/list-pipelines) | | `sevalla pipelines get ` | Shows a pipeline with its stages and preview settings. | [Get pipeline](/v3/pipelines/get-pipeline) | | `sevalla pipelines create --name --type [--project ] [--dry-run]` | Creates a pipeline with two stages, Dev and Production. | [Create pipeline](/v3/pipelines/create-pipeline) | | `sevalla pipelines update [--name ] [--dry-run]` | Renames a pipeline. | [Update pipeline](/v3/pipelines/update-pipeline) | | `sevalla pipelines delete --confirm [--dry-run]` | Deletes a pipeline and its stages. Its applications stay, and its preview apps are deleted. | [Delete pipeline](/v3/pipelines/delete-pipeline) | | `sevalla pipelines promote --source-app-id --target-app-ids [--dry-run]` | Deploys the latest successful build of the source application to the target applications, with no rebuild. | [Promote pipeline](/v3/pipelines/promote-pipeline) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `pipelines create` | `--name ` | string | None | Required. Display name, 1 to 255 characters. | | `pipelines create` | `--type ` | `trunk` or `branch` | None | Required. With `trunk`, every stage uses the same repository and branch settings. With `branch`, each stage can use its own branch. | | `pipelines create` | `--project ` | UUID | None | Project to add the pipeline to. | | `pipelines update` | `--name ` | string | None | New display name. | | `pipelines promote` | `--source-app-id ` | UUID | None | Required. Application to promote from. | | `pipelines promote` | `--target-app-ids ` | list of UUIDs | None | Required. Applications to promote to. | ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} # Promote the latest successful build of staging to production sevalla pipelines promote "$PIPELINE_ID" --source-app-id "$STAGING_APP_ID" --target-app-ids "$PRODUCTION_APP_ID" ``` ### Stages | Command | What it does | API operation | | - | - | - | | `sevalla pipelines stages create --name [--insert-before ] [--dry-run]` | Adds a stage at a position. Stages at that position and after it move up one. | [Create pipeline stage](/v3/pipelines/create-pipeline-stage) | | `sevalla pipelines stages delete --confirm [--dry-run]` | Deletes a stage. Its applications stay, and the other stages close the gap. | [Delete pipeline stage](/v3/pipelines/delete-pipeline-stage) | | `sevalla pipelines stages apps add ` | Adds an application to a stage. The application can't be in another pipeline, and it takes the project of the pipeline. | [Add application to pipeline stage](/v3/pipelines/add-application-to-pipeline-stage) | | `sevalla pipelines stages apps remove --confirm` | Removes an application from a stage without deleting it. Without `--confirm`, exits with `Use --confirm to confirm removal.` | [Remove application from pipeline stage](/v3/pipelines/remove-application-from-pipeline-stage) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `pipelines stages create` | `--name ` | string | None | Required. Stage name, 1 to 255 characters. | | `pipelines stages create` | `--insert-before ` | integer | `0` | Position of the new stage, `0` to `50`. | ### Preview apps | Command | What it does | API operation | | - | - | - | | `sevalla pipelines preview enable [--repo-url ] [--auto-create-app ] [--delete-stale-apps ] [--stale-app-days ] [--dry-run]` | Turns on preview apps for pull requests. | [Enable pipeline preview](/v3/pipelines/enable-pipeline-preview) | | `sevalla pipelines preview disable [--dry-run]` | Turns off preview apps, deletes the existing ones and removes the preview stage. | [Disable pipeline preview](/v3/pipelines/disable-pipeline-preview) | | `sevalla pipelines preview update [--repo-url ] [--auto-create-app ] [--delete-stale-apps ] [--stale-app-days ] [--dry-run]` | Changes the preview settings or the connected repository. | [Update pipeline preview settings](/v3/pipelines/update-pipeline-preview-settings) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `pipelines preview enable`, `pipelines preview update` | `--repo-url ` | URL | None | Repository to connect. `enable` needs it when the pipeline has no repository. | | `pipelines preview enable`, `pipelines preview update` | `--auto-create-app ` | `true` or `false` | API default on enable: `false` | Creates a preview app when a pull request opens. | | `pipelines preview enable`, `pipelines preview update` | `--delete-stale-apps ` | `true` or `false` | API default on enable: `false` | Deletes preview apps with no deployment for `--stale-app-days`. | | `pipelines preview enable`, `pipelines preview update` | `--stale-app-days ` | integer | API default on enable: `5` | Days after the last deployment before a preview app is stale, `1` to `365`. | ## Registry credentials The `docker-registries` commands manage the credentials Sevalla uses to pull private Docker images. | Command | What it does | API operation | | - | - | - | | `sevalla docker-registries list [--page ] [--per-page ]` | Lists registry credentials. Secrets are never returned. | [List Docker registry credentials](/v3/docker-registries/list-docker-registry-credentials) | | `sevalla docker-registries get ` | Shows a registry credential, without its secret. | [Get Docker registry credential](/v3/docker-registries/get-docker-registry-credential) | | `sevalla docker-registries create --name --username --secret [--registry ] [--dry-run]` | Saves a registry credential. The secret is stored encrypted. | [Create Docker registry credential](/v3/docker-registries/create-docker-registry-credential) | | `sevalla docker-registries update [--name ] [--registry ] [--username ] [--secret ] [--dry-run]` | Updates a registry credential. | [Update Docker registry credential](/v3/docker-registries/update-docker-registry-credential) | | `sevalla docker-registries delete --confirm [--dry-run]` | Deletes a registry credential. Applications that use it can no longer pull their private images. | [Delete Docker registry credential](/v3/docker-registries/delete-docker-registry-credential) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `docker-registries create` | `--name ` | string | None | Required. Display name, 1 to 255 characters. | | `docker-registries create` | `--username ` | string | None | Required. User name or access key for the registry. | | `docker-registries create` | `--secret ` | string | None | Required. Password or access token. | | `docker-registries create`, `docker-registries update` | `--registry ` | `dockerHub`, `gcr`, `ecr`, `github`, `gitlab`, `digitalOcean` or `custom` | API default on create: `dockerHub` | Registry: Docker Hub, Google Container Registry, Amazon ECR, GitHub, GitLab, DigitalOcean or another registry. | | `docker-registries update` | `--name `, `--username `, `--secret ` | string | None | New values. | ## Webhooks | Command | What it does | API operation | | - | - | - | | `sevalla webhooks list [--page ] [--per-page ]` | Lists webhooks. A company can have up to 10. | [List webhooks](/v3/webhooks/list-webhooks) | | `sevalla webhooks get ` | Shows a webhook with its events, endpoint and signing secret. | [Get webhook](/v3/webhooks/get-webhook) | | `sevalla webhooks create --endpoint --events [--description ] [--dry-run]` | Creates a webhook. It receives events at once, and the response includes its signing secret. | [Create webhook](/v3/webhooks/create-webhook) | | `sevalla webhooks update [--endpoint ] [--events ] [--description ] [--dry-run]` | Updates a webhook. Changes apply to the next delivery. | [Update webhook](/v3/webhooks/update-webhook) | | `sevalla webhooks delete --confirm [--dry-run]` | Deletes a webhook. | [Delete webhook](/v3/webhooks/delete-webhook) | | `sevalla webhooks toggle [--dry-run]` | Turns a webhook off or on. A disabled webhook gets no deliveries. | [Toggle webhook](/v3/webhooks/toggle-webhook) | | `sevalla webhooks roll-secret [--expire-in-hours ] [--dry-run]` | Creates a new signing secret. Both secrets verify signatures until the old one expires. | [Roll webhook secret](/v3/webhooks/roll-webhook-secret) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `webhooks create`, `webhooks update` | `--endpoint ` | URL | None | Required on create. Where Sevalla sends events with `POST`. | | `webhooks create`, `webhooks update` | `--events ` | list | None | Required on create. Any of `APP_CREATE`, `APP_UPDATE`, `APP_DELETE`, `APP_DEPLOY`, `DATABASE_CREATE`, `DATABASE_UPDATE`, `DATABASE_DELETE`, `STATIC_SITE_CREATE`, `STATIC_SITE_UPDATE`, `STATIC_SITE_DELETE` and `STATIC_SITE_DEPLOY`. Payloads are on [Webhook events](/v3/webhook-events). | | `webhooks create`, `webhooks update` | `--description ` | string | None | Description, up to 255 characters. | | `webhooks roll-secret` | `--expire-in-hours ` | integer | `0` | Hours the old secret stays valid, `0` to `24`. `0` expires it at once. | ### Webhook deliveries | Command | What it does | API operation | | - | - | - | | `sevalla webhooks deliveries list --webhook-id [--page ] [--per-page ]` | Lists the deliveries of a webhook, newest first. | [List webhook event deliveries](/v3/webhooks/list-webhook-event-deliveries) | | `sevalla webhooks deliveries get --webhook-id ` | Shows a delivery: the payload, the response, its status code and the response time. | [Get webhook event delivery](/v3/webhooks/get-webhook-event-delivery) | ## Projects | Command | What it does | API operation | | - | - | - | | `sevalla projects list [--page ] [--per-page ]` | Lists projects. | [List projects](/v3/projects/list-projects) | | `sevalla projects get ` | Shows a project. | [Get project](/v3/projects/get-project) | | `sevalla projects create --name [--dry-run]` | Creates a project. | [Create project](/v3/projects/create-project) | | `sevalla projects update --name [--dry-run]` | Renames a project. | [Update project](/v3/projects/update-project) | | `sevalla projects delete --confirm [--dry-run]` | Deletes a project. Its services stay, outside any project, and API key permissions limited to the project are removed. | [Delete project](/v3/projects/delete-project) | `--name` on `create` and `update` is required and takes 1 to 64 characters. ### Project services | Command | What it does | API operation | | - | - | - | | `sevalla projects services add --service-id [--service-type ] [--dry-run]` | Adds an application, database, pipeline or bucket to a project. Adding a pipeline also moves the applications in its stages. | [Add service to project](/v3/projects/add-service-to-project) | | `sevalla projects services remove [--service-type ] --confirm [--dry-run]` | Removes a service from a project without deleting it. Removing a pipeline also removes the applications in its stages. | [Remove service from project](/v3/projects/remove-service-from-project) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `projects services add` | `--service-id ` | UUID | None | Required. The service to add. | | `projects services add`, `projects services remove` | `--service-type ` | `app`, `database`, `pipeline` or `object-storage` | `app` | Type of the service. The API accepts only these four. | ## API keys | Command | What it does | API operation | | - | - | - | | `sevalla api-keys list [--page ] [--per-page ]` | Lists API keys, newest first, with masked tokens. | [List API keys](/v3/api-keys/list-api-keys) | | `sevalla api-keys get ` | Shows an API key with its roles and capabilities. | [Get API key](/v3/api-keys/get-api-key) | | `sevalla api-keys create --name [--capabilities ] [--expires-at ] [--dry-run]` | Creates an API key. The response shows the token once. | [Create API key](/v3/api-keys/create-api-key) | | `sevalla api-keys update [--name ] [--dry-run]` | Renames an API key. | [Update API key](/v3/api-keys/update-api-key) | | `sevalla api-keys delete --confirm [--dry-run]` | Deletes an API key, which revokes it at once. | [Delete API key](/v3/api-keys/delete-api-key) | | `sevalla api-keys toggle [--dry-run]` | Turns an API key off or on. A disabled key can't authenticate. | [Toggle API key](/v3/api-keys/toggle-api-key) | | `sevalla api-keys rotate [--ttl ] [--dry-run]` | Creates a new token for an API key. The response shows it once. | [Rotate API key](/v3/api-keys/rotate-api-key) | | `sevalla api-keys validate` | Checks the key the CLI uses and shows its name, company, expiration and status. | [Validate API key](/v3/api-keys/validate-api-key) | The API refuses `update`, `delete`, `toggle` and `rotate` on the key that sends the request, so run them with another key. The CLI can't assign a role or limit a capability to one resource: do that in the dashboard (see [API keys](https://docs.sevalla.com/developer-tools/api-keys)) or with [Create API key](/v3/api-keys/create-api-key). **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `api-keys create` | `--name ` | string | None | Required. Name, 1 to 255 characters. | | `api-keys create` | `--capabilities ` | list | None | Permissions in `RESOURCE:ACTION` form, such as `APP:READ,APP:UPDATE`, from `sevalla resources rbac-permissions`. The API needs at least one capability or role, and the CLI can't assign roles, so pass this flag. | | `api-keys create` | `--expires-at ` | ISO 8601 timestamp in UTC | Never expires | Expiration, such as `2026-12-31T23:59:59Z`. | | `api-keys update` | `--name ` | string | None | New name. | | `api-keys rotate` | `--ttl ` | integer | `0` | Hours the old token keeps working, `0` to `168`. `0` stops it at once. | ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} # A key for a CI job that deploys applications. Without --capabilities, the API rejects the request. sevalla api-keys create --name ci-deploy --capabilities APP:READ,APP:UPDATE --expires-at 2026-12-31T23:59:59Z ``` ## Resources | Command | What it does | API operation | | - | - | - | | `sevalla resources clusters` | Lists the clusters (locations) for applications and databases: ID, name and location. | [List clusters](/v3/resources/list-clusters) | | `sevalla resources db-types` | Lists the database sizes for `--resource-type` on `databases create` and `databases update`. | [List database resource types](/v3/resources/list-database-resource-types) | | `sevalla resources process-types` | Lists the process sizes for `--resource-type` on `apps processes create` and `apps processes update`. | [List process resource types](/v3/resources/list-process-resource-types) | | `sevalla resources rbac-permissions` | Lists the API key permissions for `api-keys create --capabilities`. | [List API key permissions](/v3/resources/list-api-key-permissions) | | `sevalla resources rbac-roles` | Lists the predefined API key roles. | [List API key roles](/v3/resources/list-api-key-roles) | ## Global environment variables | Command | What it does | API operation | | - | - | - | | `sevalla global-env-vars list [--page ] [--per-page ]` | Lists the global environment variables with their values. | [List global environment variables](/v3/global-environment-variables/list-global-environment-variables) | | `sevalla global-env-vars create --key --value [--dry-run]` | Adds a variable that every application in the company inherits, at build time and at runtime. An application variable with the same key overrides it. It applies at the next deployment of each application. | [Create global environment variable](/v3/global-environment-variables/create-global-environment-variable) | | `sevalla global-env-vars update [--key ] [--value ] [--dry-run]` | Changes the key or the value of a global variable. An empty value isn't sent. | [Update global environment variable](/v3/global-environment-variables/update-global-environment-variable) | | `sevalla global-env-vars delete --confirm [--dry-run]` | Deletes a global variable. It applies at the next deployment of each application. | [Delete global environment variable](/v3/global-environment-variables/delete-global-environment-variable) | `--key` takes 1 to 255 characters, unique among the global variables, and `--value` up to 32,768 characters. ## Git | Command | What it does | API operation | | - | - | - | | `sevalla git providers` | Lists the Git providers (GitHub, Bitbucket and GitLab) with the URLs that connect a Git account. | [List Git providers](/v3/git/list-git-providers) | ## Users | Command | What it does | API operation | | - | - | - | | `sevalla users list` | Lists the users of the company: ID, email, name and role. | [List company users](/v3/users/list-company-users) | ## Usage alerts | Command | What it does | API operation | | - | - | - | | `sevalla usage-alerts list [--project-id ] [--page ] [--per-page ]` | Lists usage alerts: the company-wide alert and the project alerts. `--project-id` limits the list to one project. | [List usage alert configs](/v3/usage-alerts/list-usage-alert-configs) | | `sevalla usage-alerts get ` | Shows a usage alert with its limit, recipients and triggers. | [Get usage alert config](/v3/usage-alerts/get-usage-alert-config) | | `sevalla usage-alerts create --limit-usd --emails --triggers [--project-id ] [--data ] [--dry-run]` | Creates a usage alert for the company or for one project. Sevalla checks it every hour against the current billing period, and the highest trigger reached emails the recipients once per period. | [Create usage alert config](/v3/usage-alerts/create-usage-alert-config) | | `sevalla usage-alerts update [--limit-usd ] [--emails ] [--triggers ] [--data ] [--dry-run]` | Updates a usage alert. Its project can't change. | [Update usage alert config](/v3/usage-alerts/update-usage-alert-config) | | `sevalla usage-alerts delete --confirm [--dry-run]` | Deletes a usage alert. | [Delete usage alert config](/v3/usage-alerts/delete-usage-alert-config) | **Flags** | Command | Flag | Type | Default | Description | | - | - | - | - | - | | `usage-alerts create`, `usage-alerts update` | `--limit-usd ` | number | None | Required on create. Spending limit in USD, at least `0.01`. | | `usage-alerts create`, `usage-alerts update` | `--emails ` | list | None | Required on create. Recipients. | | `usage-alerts create`, `usage-alerts update` | `--triggers ` | list of percentages | None | Required on create. Percentages of the limit, up to 10, such as `50,80,100`. A trailing `%` is accepted. On update, replaces all triggers. | | `usage-alerts create` | `--project-id ` | UUID | Company-wide | Project the alert covers. A company has one company-wide alert and one alert per project. | | `usage-alerts create`, `usage-alerts update` | `--data ` | JSON object | None | Request body to send instead of the flags. | ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} # Email two people at 50%, 80% and 100% of USD 500 in a billing period sevalla usage-alerts create --limit-usd 500 --emails ops@example.com,finance@example.com --triggers 50,80,100 ``` ## Shell completion | Command | What it does | API operation | | - | - | - | | `sevalla completion ` | Prints the completion script for `bash`, `zsh` or `fish`. | None | ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} eval "$(sevalla completion zsh)" # add to ~/.zshrc eval "$(sevalla completion bash)" # add to ~/.bashrc sevalla completion fish | source # add to ~/.config/fish/config.fish ``` ## Command schema | Command | What it does | API operation | | - | - | - | | `sevalla schema [command]` | Prints the command tree as JSON: each command with its path, description, arguments and options with defaults. `command` is a dot path, such as `apps.deployments.trigger`. It needs no sign-in. | None | In the schema, `"required": true` on an option means that the flag takes a value, not that you must pass it. The invocations on this page show which flags you must pass. ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} sevalla schema apps.deployments.trigger | jq -r '.options[].long' ``` The source code and release notes are on [GitHub](https://github.com/sevalla-hosting/cli). # 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. Databases created on OCI clusters use external backups instead, and this endpoint returns a 400 for them. # Create database backup target Source: https://api-docs.sevalla.com/v3/databases/create-database-backup-target https://api.sevalla.com/v3/openapi.json post /databases/{id}/backup-targets Attach a backup target to a database. A backup target is an S3-compatible bucket that receives scheduled and manual dump backups. Point it at a Sevalla object storage bucket with `object_storage_id`, or at any external S3-compatible storage with `bucket_name`, `access_key` and `secret_key`. The target configuration is applied to the database asynchronously; scheduled backups start once the apply completes. A database can have up to 5 backup targets. The database and its backups must be in a ready state. Databases that do not support external backups return a 400. # Create external database backup Source: https://api-docs.sevalla.com/v3/databases/create-external-database-backup https://api.sevalla.com/v3/openapi.json post /databases/{id}/external-backups Create a manual external backup of a database. The database is dumped and the file is uploaded to the backup target bucket asynchronously; the backup appears in the external backup list once the upload completes. Requires at least one backup target attached to the database, otherwise a 400 is returned. A target can hold at most 5 manual backups. The database and its backups must be in a ready state. Databases that do not support external backups return a 400. # 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 connection covers every process of the application, including cron and job processes. 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. The API key needs update access to both the database and the target. # 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 database backup target Source: https://api-docs.sevalla.com/v3/databases/delete-database-backup-target https://api.sevalla.com/v3/openapi.json delete /databases/{id}/backup-targets/{target_id} Detach a backup target from a database. Scheduled backups to this target stop and its backups disappear from the backup list, but the dump files already uploaded stay in the bucket. The removal is applied to the database asynchronously. Rejected with a 400 while a backup or a restore using this target is in progress. Databases that do not support external backups return a 400. # Delete external database backup Source: https://api-docs.sevalla.com/v3/databases/delete-external-database-backup https://api.sevalla.com/v3/openapi.json delete /databases/{id}/external-backups/{backup_id} Delete an external backup file from its backup target bucket. The file is removed immediately. Both automatic and manual backups can be deleted. Databases that do not support external backups return a 400. # 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. # Get external backup download URL Source: https://api-docs.sevalla.com/v3/databases/get-external-backup-download-url https://api.sevalla.com/v3/openapi.json get /databases/{id}/external-backups/{backup_id}/download-url Generate a short-lived presigned URL to download an external backup file from its backup target bucket. The URL is valid for 2 minutes. Databases that do not support external backups return a 400. # List database backup targets Source: https://api-docs.sevalla.com/v3/databases/list-database-backup-targets https://api.sevalla.com/v3/openapi.json get /databases/{id}/backup-targets Retrieve the backup targets attached to a database. A backup target is an S3-compatible bucket that receives scheduled and manual dump backups of the database. Storage credentials are never returned. Databases that do not support external backups return a 400. # 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 external database backups Source: https://api-docs.sevalla.com/v3/databases/list-external-database-backups https://api.sevalla.com/v3/openapi.json get /databases/{id}/external-backups Retrieve the external backups of a database across all of its backup targets. External backups are dump files stored in the backup target buckets; the bucket content is the source of truth, so this endpoint lists the buckets live. Databases without backup targets return an empty list. A target whose bucket cannot be listed, for example because its credentials were revoked, is skipped. Databases that do not support external backups return a 400. # 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, and must have snapshot backups too (databases created on OCI clusters use external backups instead). On OCI clusters, DB1 databases keep their data on a different storage backend than larger resource types, so a backup of a DB1 database cannot be restored into a larger one, or the other way round. 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. # Restore external database backup Source: https://api-docs.sevalla.com/v3/databases/restore-external-database-backup https://api.sevalla.com/v3/openapi.json post /databases/{id}/external-backups/{backup_id}/restore Restore a database from an external backup. The dump file is downloaded from the backup target bucket and replayed into the database asynchronously - the database status reflects the progress and ends in `ready`, or `restoringFailed` when the replay fails. The destination data is replaced by the backup content. By default the source database is restored in place. Optionally pass `target_database_id` to restore into a different database of the same type in the same cluster. Restores are attempted regardless of engine version; an incompatible dump fails the restore. Rejected with a 400 while another restore is in progress on the destination. Databases that do not support external backups return a 400. # 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 backup target Source: https://api-docs.sevalla.com/v3/databases/update-database-backup-target https://api.sevalla.com/v3/openapi.json put /databases/{id}/backup-targets/{target_id} Update a backup target of a database. Only the provided fields are changed. Changing connection fields switches the target between Sevalla object storage and external S3 storage. The new configuration is applied to the database asynchronously. The database and its backups must be in a ready state. Databases that do not support external backups return a 400. # 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. Send the optional `x-sevalla-client` header to name the client that requests access, for example `claude-code`. # 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: the JSON error body, every status code it returns, the messages to match, request IDs, and which errors to retry. When a request fails, the Sevalla API returns a `4xx` or `5xx` status code and a JSON body with three fields: `message`, `status` and `data`. The status code tells you what kind of error it is, and `message` says what went wrong. ## Error body ```json theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} { "message": "Application not found", "status": 404, "data": {} } ``` **message** `string` What went wrong, such as `Application not found` or `This API key is missing the APP:UPDATE permission. Grant it to the key or use a key that has it.` **status** `integer` The HTTP status code, the same as the response's. **data** `object` Details, when there are any. Usually empty (`{}`). On most `500` responses, it has `code`, the [request ID](#request-ids), and `message`, which asks you to contact support with that code. On some `400` responses, it has `issues`: see [Schema validation errors](#schema-validation-errors). A path or method that doesn't exist returns `404` with a different body: ```json theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} { "message": "Route GET:/v3/aplications not found", "error": "Not Found", "statusCode": 404 } ``` ## Status codes Successful requests return `200` or `201` with the object or list, `202` when the work continues in the background (see [Long-running operations](/v3/long-running-operations)), or `204` with no body. Errors use these codes: | Status | Meaning | Retry | | - | - | - | | `400` | The request is invalid: it doesn't match the schema, or the service's current state doesn't allow it, for example restarting a database while a backup is in progress. `message` says which. | No. Fix the request, or wait for the state to change. | | `401` | `Unauthorized`: the API key is missing, wrong, disabled, expired or deleted. See [Authentication errors](/v3/authentication#authentication-errors). | No | | `403` | The key lacks a permission, the company or service is suspended (`The service is suspended.`), or the company is being migrated or maintained, which blocks changes but not reads | No | | `404` | The resource doesn't exist, or it belongs to another company, for example `Application not found` | No | | `409` | A conflict with an existing resource, for example an internal connection that already exists | No | | `422` | A repository operation on a service that has no Git repository: `Application has no Git repository source` or `Static site has no Git repository source` | No | | `426` | [Open terminal session](/v3/applications/open-terminal-session-websocket) was called without a WebSocket upgrade (`Upgrade Required`) | No | | `429` | A [rate limit](/v3/rate-limits) was reached | Yes, after the number of seconds in `retry-after` | | `500` | `Internal Server Error`: an error on Sevalla's side | Yes, with backoff. See [Retry safely](#retry-safely). | ## Schema validation errors A body, query parameter or path parameter that doesn't match the operation's schema returns `400` with the message `Request doesn't match the schema`. The API checks the schema before the API key, so a malformed request gets `400` even without a valid key. On operations whose reference page doesn't list a `400` response, such as [Get application](/v3/applications/get-application), `data.issues` describes each problem: ```json theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} { "message": "Request doesn't match the schema", "status": 400, "data": { "issues": [ { "keyword": "invalid_format", "instancePath": "/id", "schemaPath": "#/id/invalid_format", "message": "Invalid UUID", "params": { "origin": "string", "format": "uuid" } } ], "method": "GET", "url": "/v3/applications/storefront" } } ``` On operations that list a `400` response, such as [Create application](/v3/applications/create-application), `data` is empty. Compare the request with the operation's body and parameters in this reference. ## Request IDs Every response has an `x-request-id` header. If you send your own `x-request-id` header, the response carries the same value, so you can match your logs with Sevalla's. On most `500` responses, `data.code` holds the same ID, and `data.message` asks you to contact support with it. Include the request ID when you [contact support](https://docs.sevalla.com/support/get-help). ## Handle errors in code Check the status code first, then read `message`. This helper throws an error that carries both, with the request ID: ```typescript sevalla.ts theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} export class SevallaError extends Error { constructor( readonly status: number, message: string, readonly requestId: string | null, ) { super(message); } } export async function sevalla(path: string, init: RequestInit = {}): Promise { const res = await fetch(`https://api.sevalla.com/v3${path}`, { ...init, headers: { Authorization: `Bearer ${process.env.SEVALLA_API_KEY}`, "Content-Type": "application/json", ...init.headers, }, }); const text = await res.text(); const body = text ? JSON.parse(text) : undefined; if (!res.ok) { throw new SevallaError(res.status, body?.message ?? res.statusText, res.headers.get("x-request-id")); } return body as T; } ``` ```typescript theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} try { await sevalla("/applications/7f3c2b1a-9e8d-4c7b-a6f5-4e3d2c1b0a9f/deployments", { method: "POST", body: JSON.stringify({ branch: "main" }), }); } catch (error) { if (error instanceof SevallaError && error.status === 404) { console.error(`No such application (request ${error.requestId})`); } else { throw error; } } ``` ## Retry safely * `4xx` errors fail again until you change the request or the state it depends on. Don't retry them unchanged, except `429`. * `429`: wait the number of seconds in `retry-after`, then retry. See [Handle 429 responses](/v3/rate-limits#handle-429-responses). * `500`: retry `GET` requests with exponential backoff. Before you retry a write, check whether it took effect, for example by listing the application's deployments before you trigger another one. # 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. # 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. # Long-running operations Source: https://api-docs.sevalla.com/v3/long-running-operations Which Sevalla API operations return before the work finishes, what they return, and how to poll deployments, databases, backups, restores and deletions until they end. A long-running operation starts work that Sevalla finishes in the background: the request returns as soon as the work is queued, and you poll another operation to learn how it ended. Deployments, database changes, backups, restores, suspensions and most deletions work this way. ## How it works A long-running operation returns one of two things: * **The new object, with a status.** [Trigger deployment](/v3/applications/trigger-deployment) returns the deployment with `status` `waiting`, and [Create database](/v3/databases/create-database) returns the database with `status` `creating`. Poll the object's `GET` operation until the status is final. * **A message.** [Restore database backup](/v3/databases/restore-database-backup) returns `202` with `{"message": "Database backup restore started"}`, and [Suspend application](/v3/applications/suspend-application) returns `200` with a message. Poll the service the operation acts on. Poll every 10 seconds or more, and stop at a final status or after a timeout you choose. Polling counts toward the read [rate limit](/v3/rate-limits) of 400 requests per minute for the company. For deployments, a [webhook](/v3/webhook-events) on `APP_DEPLOY` or `STATIC_SITE_DEPLOY` tells you when they end, without polling. ## Deployments | Operation | Returns | Poll | | - | - | - | | [Trigger deployment](/v3/applications/trigger-deployment), [Rollback deployment](/v3/applications/rollback-deployment) | The deployment | [Get deployment](/v3/applications/get-deployment) | | [Promote pipeline](/v3/pipelines/promote-pipeline) | A `target_app_id` and a `deployment_id` for each target application | [Get deployment](/v3/applications/get-deployment) for each target | | [Deploy static site](/v3/static-sites/deploy-static-site) | The static site deployment | [Get static site deployment](/v3/static-sites/get-static-site-deployment) | | [Create static site](/v3/static-sites/create-static-site) | The static site. Its first deployment starts on its own. | [List static site deployments](/v3/static-sites/list-static-site-deployments), newest first | Application and static site deployments have the same statuses: | `status` | Meaning | Final | | - | - | - | | `waiting` | Queued, not started yet | No | | `inProgress` | Building or rolling out | No | | `success` | Deployed | Yes | | `failed` | The build or the rollout failed. Read the deployment's logs with [Get application deployment logs](/v3/applications/get-application-deployment-logs). | Yes | | `cancelled` | Stopped while in progress | Yes | | `skipped` | Never ran, for example because it was cancelled while `waiting` | Yes | An application deployment's `finished_at` is set when it succeeds, fails or is cancelled. To stop a deployment, call [Cancel deployment](/v3/applications/cancel-deployment) or [Cancel static site deployment](/v3/static-sites/cancel-static-site-deployment). ### Wait for a deployment Trigger the deployment, keep its `id`, then get it until the status is final: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} curl -X POST "https://api.sevalla.com/v3/applications/$APP_ID/deployments" \ -H "Authorization: Bearer $SEVALLA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"branch": "main"}' ``` ```json theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} { "id": "3b2a1c0d-8e7f-4a6b-9c5d-2e1f0a9b8c7d", "app_id": "7f3c2b1a-9e8d-4c7b-a6f5-4e3d2c1b0a9f", "status": "waiting", "type": "manual", "branch": "main", "started_at": null, "finished_at": null, "created_at": "2026-10-15T09:12:44.000Z", "updated_at": "2026-10-15T09:12:44.000Z" } ``` The response has more fields, such as `steps`, `repo_url` and `commit_sha`: see [Trigger deployment](/v3/applications/trigger-deployment). In code: ```typescript wait-for-deployment.ts theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} const API = "https://api.sevalla.com/v3"; const headers = { Authorization: `Bearer ${process.env.SEVALLA_API_KEY}`, "Content-Type": "application/json" }; const FINAL = ["success", "failed", "cancelled", "skipped"]; type Deployment = { id: string; status: string | null }; async function waitForDeployment(appId: string, deploymentId: string, timeoutMs = 30 * 60_000): Promise { const deadline = Date.now() + timeoutMs; while (Date.now() < deadline) { const res = await fetch(`${API}/applications/${appId}/deployments/${deploymentId}`, { headers }); if (!res.ok) throw new Error(`Get deployment returned ${res.status}: ${(await res.json()).message}`); const deployment = (await res.json()) as Deployment; if (deployment.status && FINAL.includes(deployment.status)) return deployment; await new Promise((resolve) => setTimeout(resolve, 10_000)); } throw new Error(`Deployment ${deploymentId} didn't finish within ${timeoutMs / 60_000} minutes`); } const appId = process.env.APP_ID!; const res = await fetch(`${API}/applications/${appId}/deployments`, { method: "POST", headers, body: JSON.stringify({ branch: "main" }), }); if (!res.ok) throw new Error(`Trigger deployment returned ${res.status}: ${(await res.json()).message}`); const { id } = (await res.json()) as Deployment; const deployment = await waitForDeployment(appId, id); console.log(`Deployment ${deployment.id}: ${deployment.status}`); process.exit(deployment.status === "success" ? 0 : 1); ``` ## Databases Poll [Get database](/v3/databases/get-database) and read `status`: | Operation | `status` while it runs | When it's done | When it fails | | - | - | - | - | | [Create database](/v3/databases/create-database) | `creating` | `ready` | `error` | | [Update database](/v3/databases/update-database) with a new `resource_type_id` | `updating` | `ready` | `error` | | [Restart database](/v3/databases/restart-database) | `updating` | `ready` | `error` | | [Reset database password](/v3/databases/reset-database-password) | `passwordChange` | `ready` | `passwordChangeFailed` | | [Restore database backup](/v3/databases/restore-database-backup), and `POST /databases/{id}/external-backups/{backup_id}/restore` for external backups | `restoring`, on the database restored into | `ready` | `restoringFailed` | | [Toggle external connection](/v3/databases/toggle-external-connection) | `updatingExternalConnection` | `ready` | `ready` too: check `external_hostname` and `external_port` to see whether the change applied | [Suspend database](/v3/databases/suspend-database) and [Activate database](/v3/databases/activate-database) don't change `status`: `is_suspended` changes to `true` or `false` when they finish. For [Delete database](/v3/databases/delete-database), see [Deletions](#deletions). Restarting, updating, suspending, restoring and deleting a database are rejected with `400` while the database is busy, for example while a backup is in progress. Wait for `ready` before you start the next operation. ## Backups | Operation | Returns | When it's done | | - | - | - | | [Create database backup](/v3/databases/create-database-backup) | `202` with `{"message": "Database backup creation started"}` | The backup appears in [List database backups](/v3/databases/list-database-backups) | | `POST /databases/{id}/external-backups` | `202` with a message | The backup appears in `GET /databases/{id}/external-backups` once its upload to the backup target finishes | Backups have no status of their own: poll the list until a backup with your `display_name` appears. ## Deletions | Operation | Returns | Poll | When it's done | When it fails | | - | - | - | - | - | | [Delete application](/v3/applications/delete-application) | `200` with a message | [Get application](/v3/applications/get-application) | `404` (`Application not found`) | `status` `appDeletionFailed` | | [Delete database](/v3/databases/delete-database) | `200` with a message | [Get database](/v3/databases/get-database) | `404` (`Database not found`) | `status` `dbDeletionFailed` | | [Delete object storage bucket](/v3/object-storages/delete-object-storage-bucket) | `202` with no body | [Get object storage bucket](/v3/object-storages/get-object-storage-bucket) | `404` (`Object storage not found`) | `status` `deletionFailed` | While the deletion runs, `status` is `deleting`. Deleting a static site or a project finishes before the response. ## Other background operations | Operation | Poll | When it's done | | - | - | - | | [Suspend application](/v3/applications/suspend-application), [Activate application](/v3/applications/activate-application) | [Get application](/v3/applications/get-application) | `is_suspended` is `true` or `false` | | [Create TCP proxy](/v3/applications/create-tcp-proxy), [Create private port](/v3/applications/create-private-port) | [List TCP proxies](/v3/applications/list-tcp-proxies), [List private ports](/v3/applications/list-private-ports) | `status` changes from `creating` to `ready`, or to `failed` | | [Add application domain](/v3/applications/add-application-domain), and the same operation for static sites and load balancers | [Get application domain](/v3/applications/get-application-domain) | `status` changes from `VERIFICATION` to `POINTING` to `ACTIVE` as your DNS records are found, or to `TIMED_OUT` when verification doesn't finish within 7 days. See [Custom domains](https://docs.sevalla.com/domains/overview). | ## Changes that wait for a deployment Some operations finish at once but take effect only at the application's next deployment: creating a process, changing a process's resource type, scaling or probes, deleting a process, and changing environment variables. [Trigger a deployment](/v3/applications/trigger-deployment) to apply them. With `is_restart` set to `true`, the deployment reuses the last successful build instead of building again. # 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 Page through Sevalla API list operations with limit and offset, read every item using total, and page objects in a bucket with a cursor. List operations in the Sevalla API return one page of results at a time. You set the page size with `limit` and the position with `offset`, and the response says in `total` how many items match. ## Parameters | Parameter | Default | Range | What it does | | - | - | - | - | | `limit` | `25` | `1` to `100` | Maximum number of items in the page | | `offset` | `0` | `0` to `10000` | Number of items to skip | A value outside the range returns `400` with `Request doesn't match the schema`. ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} curl "https://api.sevalla.com/v3/applications?limit=50&offset=50" \ -H "Authorization: Bearer $SEVALLA_API_KEY" ``` ## Response Every paginated list has the same shape: ```json theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} { "data": [], "total": 42, "offset": 0, "limit": 25 } ``` **data** `array` The items in this page. **total** `integer` How many items match the request across all pages, after filters. **offset** `integer` The `offset` used for this page. **limit** `integer` The `limit` used for this page. The order depends on the operation and is given in its description: [List applications](/v3/applications/list-applications) is ordered by name, [List deployments](/v3/applications/list-deployments) newest first. ## Read every page Add `limit` to `offset` until `offset` reaches `total`: ```typescript list-all.ts theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} type Page = { data: T[]; total: number; offset: number; limit: number }; export async function listAll(path: string): Promise { const items: T[] = []; const limit = 100; for (let offset = 0; ; offset += limit) { const separator = path.includes("?") ? "&" : "?"; const res = await fetch(`https://api.sevalla.com/v3${path}${separator}limit=${limit}&offset=${offset}`, { headers: { Authorization: `Bearer ${process.env.SEVALLA_API_KEY}` }, }); if (!res.ok) { throw new Error(`${res.status}: ${(await res.json()).message}`); } const page = (await res.json()) as Page; items.push(...page.data); if (offset + limit >= page.total) { return items; } } } const applications = await listAll<{ id: string; display_name: string }>("/applications"); ``` `offset` can't go past `10000`. To reach items beyond that, narrow the list with a filter. ## Filter lists Some list operations take filters that narrow the results before they're paged, so `total` counts only the matching items. When you pass more than one filter, an item must match all of them. | Operation | Filters | | - | - | | [List applications](/v3/applications/list-applications) | `status`, `source`, `project_id`, `search` | | [List databases](/v3/databases/list-databases) | `status`, `type`, `project_id`, `search` | | [List pipelines](/v3/pipelines/list-pipelines) | `type`, `project_id`, `search` | | [List projects](/v3/projects/list-projects) | `search` | | [List usage alert configs](/v3/usage-alerts/list-usage-alert-configs) | `project_id` | `search` returns items whose name or display name contains the text, ignoring case. ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} curl "https://api.sevalla.com/v3/applications?search=storefront&status=deploymentFailed" \ -H "Authorization: Bearer $SEVALLA_API_KEY" ``` ## Lists without pages These operations don't take `limit` and `offset`: | Operations | Response | | - | - | | [List objects](/v3/object-storages/list-objects) in a bucket | `data` and a `cursor`. Pass `cursor` back to get the next page; it's `null` on the last page. `limit` defaults to `25` and goes up to `200`. | | Runtime, access and deployment logs, such as [Get application runtime logs](/v3/applications/get-application-runtime-logs) | An array of entries between `from` and `to` (by default the last hour), at most `limit` (default `1000`, up to `5000`). When more entries match, you get the most recent ones: move `to` back to read earlier entries. | | [List database backups](/v3/databases/list-database-backups), List internal connections of an [application](/v3/applications/list-internal-connections) or a [database](/v3/databases/list-internal-connections), the [resources](/v3/resources/list-clusters) and metrics operations | The whole list as an array | | [List company users](/v3/users/list-company-users), [List CORS policies](/v3/object-storages/list-cors-policies) | The whole list in `data` | # 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. Preview app settings are configured in the dashboard, so turn on auto_create_app afterwards with the update preview settings endpoint. # 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. Turning on auto_create_app requires the preview app settings to be configured in the dashboard first. # 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 The Sevalla API's request limits: six tiers counted per company or per service, the x-ratelimit headers on every response, and how to handle a 429. The Sevalla API limits how many requests a company can make in a time window. Every operation belongs to one of six tiers, and a request over its tier's limit gets `429` instead of a result. ## Limits | Tier | Limit | Counted per | What it covers | | - | - | - | - | | Service creation | 20 per hour | Company | Creating or cloning applications; creating databases, static sites, buckets, load balancers and usage alerts; adding, updating, deleting, refreshing or making primary a custom domain; turning a bucket's CDN domain on or off | | Service mutation | 10 per minute | Service and company | Updating, suspending, activating and deleting a service, and changes such as cache purges, IP restrictions, maintenance mode, database restarts and password resets, and running a command in a process | | Deployment | 10 per minute | Service and company | Triggering, rolling back and cancelling deployments of applications and static sites | | General write | 30 per minute | Company | Other writes: environment variables, processes, backups and restores, internal connections, pipelines and promotions, projects, webhooks, API keys, registry credentials | | Logs | 30 per minute | Company | Deployment, runtime and access logs, repository browsing, process exit codes, backup download URLs | | Read | 400 per minute | Company | Every other request | How requests are counted: * **Per company.** Requests count against the company of the API key, so every key in the company, and every tool that uses one (the CLI, the MCP server, Terraform), shares the same limits. Requests without a valid key are counted per IP address. * **Per service.** In the service mutation and deployment tiers, each service has its own count: the service is the ID in the path, such as `{id}` in `POST /applications/{id}/deployments`. * **Per operation.** In the first five tiers, each operation has its own count: creating 20 applications in an hour doesn't stop you from creating a database. All operations in the read tier share one count. * **Every request.** A request counts when it arrives, before it's checked, so requests that fail with `4xx` count too. Each window starts with the first request counted in it and lasts 1 minute, or 1 hour for service creation. ## Response headers Each response carries the state of the limit that applied to it: | Header | Value | | - | - | | `x-ratelimit-limit` | The limit of the tier, such as `400` | | `x-ratelimit-remaining` | Requests left in the current window | | `x-ratelimit-reset` | Seconds until the window ends and the count starts again | | `retry-after` | On `429` only: seconds to wait before the next request | ```text theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} x-ratelimit-limit: 400 x-ratelimit-remaining: 397 x-ratelimit-reset: 52 ``` ## Handle 429 responses A request over the limit returns `429`: ```json theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} { "message": "Rate limit exceeded, retry in 45 seconds", "status": 429, "data": {} } ``` Wait the number of seconds in `retry-after`, then send the request again. If it fails again, wait longer each time and add jitter, so that parallel workers don't retry in step: ```typescript retry.ts theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} export async function fetchWithRetry(url: string, init: RequestInit = {}, maxAttempts = 5): Promise { for (let attempt = 1; ; attempt++) { const res = await fetch(url, { ...init, headers: { Authorization: `Bearer ${process.env.SEVALLA_API_KEY}`, ...init.headers }, }); if (res.status !== 429 || attempt === maxAttempts) { return res; } const retryAfter = Number(res.headers.get("retry-after") ?? res.headers.get("x-ratelimit-reset") ?? 1); const backoff = retryAfter * 1000 * 2 ** (attempt - 1); const jitter = Math.random() * 1000; await new Promise((resolve) => setTimeout(resolve, backoff + jitter)); } } ``` To stay under the limits: * Watch `x-ratelimit-remaining` and slow down before it reaches `0`. * Poll long-running operations every 10 seconds or more, not in a tight loop. See [Long-running operations](/v3/long-running-operations). * Use [webhooks](/v3/webhook-events) to learn when a deployment ends, instead of polling. # 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 database versions Source: https://api-docs.sevalla.com/v3/resources/list-database-versions https://api.sevalla.com/v3/openapi.json get /resources/database-versions List the database engine versions you can use when creating a database on a cluster. Supported versions differ between clusters, so pick the cluster first and pass one of the returned versions as `version` to the Create Database endpoint. 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. If Sevalla cannot access the Git repository, the request fails with a 400 error that explains why and links to the page where access can be granted (for example the repository access settings of the GitHub App used by Sevalla). # 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 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. Returns the most recent `limit` entries in the time range, oldest first by default (set `order=desc` for newest first). Use `search` for a case-insensitive text match on the message, and `filters` for filtering by severity, message, 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. Returns the most recent `limit` entries in the time range, oldest first by default (set `order=desc` for newest first). Use `search` for a case-insensitive text match on the message, and `filters` for filtering by severity, message, 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 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 What a Sevalla webhook sends to your endpoint: the request and its headers, the payload of each event type, verifying the svl-signature header, and retries. A webhook event is an HTTP `POST` that Sevalla sends to a webhook's endpoint each time one of the events it subscribes to happens in your company, such as a deployment of an application finishing. This page describes the request your endpoint receives. To create webhooks, roll their secret and check deliveries in the dashboard, see [Webhooks](https://docs.sevalla.com/developer-tools/webhooks) in the platform docs. ## Request | Property | Value | | - | - | | Method | `POST` to the webhook's endpoint | | `content-type` header | `application/json` | | `svl-signature` header | The webhook's signing secret (`whsec_` followed by 30 characters). See [Verify requests](#verify-requests). | | Success | Any `2xx` response. Anything else, or no response, is a failed delivery. | | Retries | A failed event is retried up to 10 times over about 2 days and 8 hours. See [Retries](#retries). | | Order | Not guaranteed. Use the timestamps in your own system, or call the API for the current state. | | Scope | Every application and static site in the company. Filter on the IDs in `data`. | ```json theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} { "webhook_id": "d5f8a1c2-3b4e-4f6a-8b8c-9d0e1f2a3b4c", "event_id": "a1b2c3d4-5e6f-4a8b-9c0d-1e2f3a4b5c6d", "event_delivery_id": "f1e2d3c4-b5a6-4788-9a0b-c1d2e3f4a5b6", "type": "APP_DEPLOY", "data": { "company_id": "0c9e3f5a-7b2d-4e1f-8a6c-5d4b3a2f1e0d", "app_id": "7f3c2b1a-9e8d-4c7b-a6f5-4e3d2c1b0a9f", "app_name": "storefront-x7k2m", "app_display_name": "storefront", "deployment_id": "3b2a1c0d-8e7f-4a6b-9c5d-2e1f0a9b8c7d", "status": "success", "commit": "9fceb02d0ae598e95dc970b74767f19372d61af8", "stage": "", "is_preview": false } } ``` **webhook\_id** `string` ID of the webhook that sent the request. **event\_id** `string` ID of the event. The same on every retry, so use it to drop duplicates. **event\_delivery\_id** `string` ID of this delivery attempt. A new one on every retry. **type** `string` The [event type](#event-types), such as `APP_DEPLOY`. **data** `object` The event's details. Its fields depend on `type`: see [Event data](#event-data). ## Event types Set the events a webhook receives in `allowed_events` when you [create](/v3/webhooks/create-webhook) or [update](/v3/webhooks/update-webhook) it. | Event | Sent when | | - | - | | `APP_CREATE` | An application is created | | `APP_DEPLOY` | An application's deployment starts (`status` `inProgress`), and again when it ends (`success`, `failed` or `cancelled`) | | `APP_UPDATE` | An application's name, default branch, automatic deployments, hibernation or project is changed in the dashboard. Changes made through the API don't send it. | | `APP_DELETE` | An application is deleted | | `STATIC_SITE_CREATE` | A static site is created | | `STATIC_SITE_DEPLOY` | A static site's deployment starts (`inProgress`), and again when it ends (`success`, `failed` or `cancelled`) | | `STATIC_SITE_UPDATE` | A static site's settings are updated | | `STATIC_SITE_DELETE` | A static site is deleted | | `DATABASE_CREATE`, `DATABASE_UPDATE`, `DATABASE_DELETE` | Not sent at the moment | > [!NOTE] > > `allowed_events` accepts the three database events, but Sevalla doesn't send them yet. A webhook subscribed only to database events receives no deliveries. Deployments of [preview apps](https://docs.sevalla.com/pipelines/preview-apps) and pull request previews of static sites send deploy events too, with `is_preview` set to `true`. ## Event data ### APP\_CREATE **id** `string` Application ID. **company\_id** `string` Company ID. **name** `string` The application's system name, such as `storefront-x7k2m`. **display\_name** `string` The name shown in the dashboard. **location** `string` The location's region ID, such as `europe-west3`. ### APP\_UPDATE and APP\_DELETE **id** `string` Application ID. **company\_id** `string` Company ID. **name** `string` The application's system name. In `APP_UPDATE`, the value from before the update. **display\_name** `string` The name shown in the dashboard. In `APP_UPDATE`, the value from before the update. ### APP\_DEPLOY **company\_id** `string` Company ID. **app\_id** `string` Application ID. **app\_name** `string` The application's system name. **app\_display\_name** `string` The name shown in the dashboard. **deployment\_id** `string` Deployment ID. Pass it to [Get deployment](/v3/applications/get-deployment) for the details. **status** `string` `inProgress`, `success`, `failed` or `cancelled`. **commit** `string` The full commit SHA. Absent or `null` for Docker image deployments. **stage** `string` The [pipeline](https://docs.sevalla.com/pipelines/overview) stage's name, or an empty string when the application isn't in a pipeline. **is\_preview** `boolean` `true` for a preview app. ### STATIC\_SITE\_CREATE, STATIC\_SITE\_UPDATE and STATIC\_SITE\_DELETE **id** `string` Static site ID. **company\_id** `string` Company ID. **name** `string` The static site's system name. **display\_name** `string` The name shown in the dashboard. ### STATIC\_SITE\_DEPLOY **company\_id** `string` Company ID. **static\_site\_id** `string` Static site ID. **static\_site\_name** `string` The static site's system name. **static\_site\_display\_name** `string` The name shown in the dashboard. **deployment\_id** `string` Deployment ID. Pass it to [Get static site deployment](/v3/static-sites/get-static-site-deployment) for the details. **status** `string` `inProgress`, then `success`, `failed` or `cancelled`. **repo\_url** `string` The repository URL. **branch** `string` The deployed branch. `null` unless pull request previews are turned on for the static site. **commit** `string` The commit SHA. `null` unless pull request previews are turned on for the static site. **is\_preview** `boolean` `true` for a pull request preview. ## Verify requests The `svl-signature` header contains the webhook's signing secret itself, not a hash of the body. To check that a request comes from Sevalla, compare the header with the secret you stored, in constant time, and reject the request with `401` when it doesn't match. [Get webhook](/v3/webhooks/get-webhook) returns the secret in `secret`. While a secret rollover is under way, deliveries carry the old secret until the period you chose ends, then the new one, so accept both. [Roll webhook secret](/v3/webhooks/roll-webhook-secret) takes `expire_in_hours` from `0` (the default, which switches at once) to `24`. ```typescript server.ts theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} import { createServer } from "node:http"; import { timingSafeEqual } from "node:crypto"; // The current secret, and during a rollover the old one too. const secrets = [process.env.SEVALLA_WEBHOOK_SECRET, process.env.SEVALLA_WEBHOOK_SECRET_OLD].filter( (secret): secret is string => Boolean(secret), ); function isFromSevalla(header: string | string[] | undefined): boolean { if (typeof header !== "string") return false; const received = Buffer.from(header); return secrets.some((secret) => { const expected = Buffer.from(secret); return expected.length === received.length && timingSafeEqual(expected, received); }); } type SevallaEvent = { event_id: string; type: string; data: Record }; createServer(async (req, res) => { if (req.method !== "POST" || req.url !== "/sevalla") { res.writeHead(404).end(); return; } if (!isFromSevalla(req.headers["svl-signature"])) { res.writeHead(401).end(); return; } let body = ""; for await (const chunk of req) body += chunk; res.writeHead(200).end(); // Answer first, then do the work. const event = JSON.parse(body) as SevallaEvent; if (event.type === "APP_DEPLOY" && event.data.status === "failed") { console.log(`Deployment ${event.data.deployment_id} of ${event.data.app_display_name} failed (event ${event.event_id})`); } }).listen(Number(process.env.PORT ?? 8080)); ``` ## Retries When a delivery fails, Sevalla retries the event after 1 minute, 5 minutes, 10 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 8 hours, 16 hours and 1 day, each counted from the previous attempt. It retries only during the 4 days after the event, so the 10th retry, about 2 days and 8 hours after the event, is the last. If it fails too, the event isn't sent again. See [Retries](https://docs.sevalla.com/developer-tools/webhooks#retries) in the platform docs. * Each retry is a new delivery with a new `event_delivery_id` and the same `event_id`. Retries stop as soon as one delivery succeeds. * Retries go to the endpoint the webhook had when the event happened, and carry the current signing secret. * Respond with a `2xx` as soon as you've checked the signature, and do slow work afterwards, so a slow handler isn't counted as a failure. ## Manage webhooks with the API | Task | Operation | | - | - | | Create a webhook | [Create webhook](/v3/webhooks/create-webhook): `endpoint`, `allowed_events`, optional `description` | | Get a webhook and its secret | [Get webhook](/v3/webhooks/get-webhook) | | Change the endpoint or events | [Update webhook](/v3/webhooks/update-webhook) | | Disable or enable a webhook | [Toggle webhook](/v3/webhooks/toggle-webhook) | | Roll the secret | [Roll webhook secret](/v3/webhooks/roll-webhook-secret) | | List deliveries, with their payload and your endpoint's response | [List webhook event deliveries](/v3/webhooks/list-webhook-event-deliveries), [Get webhook event delivery](/v3/webhooks/get-webhook-event-delivery) | | Delete a webhook and its deliveries | [Delete webhook](/v3/webhooks/delete-webhook) | A delivery's `status` is `PENDING` while Sevalla sends it, `SUCCESS` when your endpoint answered with a `2xx`, and `FAILED` otherwise. # 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.