> ## Documentation Index > Fetch the complete documentation index at: https://docs.sevalla.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > These are the docs for Sevalla, a platform for deploying applications, databases, static sites, object storage and load balancers. The dashboard is at https://app.sevalla.com. > Bold text in steps is an exact dashboard label. > To act on a Sevalla account, prefer the Sevalla MCP server (https://mcp.sevalla.com/mcp, see https://docs.sevalla.com/ai-agents/overview.md), then the Sevalla CLI (https://docs.sevalla.com/developer-tools/cli.md), then the REST API (https://api-docs.sevalla.com, OpenAPI spec at https://api.sevalla.com/v3/openapi.json). > Every page index is at https://docs.sevalla.com/llms.txt. # Sevalla API > Call the Sevalla REST API v3: base URL, API key authentication, the OpenAPI spec, pagination, the error format and the rate limit tiers. 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](/developer-tools/api-keys). | What | Value | | - | - | | Base URL | `https://api.sevalla.com/v3` | | API reference | [api-docs.sevalla.com](https://api-docs.sevalla.com), with every operation, its parameters and examples | | OpenAPI spec | `https://api.sevalla.com/v3/openapi.json` (OpenAPI 3.1) | | Index for LLMs | `https://api-docs.sevalla.com/llms.txt` | | Authentication | `Authorization: Bearer ` | | Format | JSON request and response bodies, `snake_case` field names, UUIDs as IDs | ## Make your first request In the sidebar, under **Tools**, click **API keys**, then [create a key](/developer-tools/api-keys#create-an-api-key) with the permissions your script needs. **Company viewer** is enough to read. Keep the key in an environment variable and send it as a bearer token: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} export SEVALLA_API_KEY="svl_..." curl https://api.sevalla.com/v3/applications \ -H "Authorization: Bearer $SEVALLA_API_KEY" ``` The response lists the company's applications in a [paginated](#pagination) object with `data`, `total`, `offset` and `limit`. Each application's `id` is what other operations take, for example `POST /applications/{id}/deployments` to [trigger a deployment](https://api-docs.sevalla.com/v3/applications/trigger-deployment). The dashboard shows the same ID on a service's **Settings** tab, under **Details**. To see what the key can do, call [Get current API key](https://api-docs.sevalla.com/v3/api-keys/get-current-api-key) (`GET /api-keys/me`), which returns its effective permissions. ## Authentication Every request needs an API key in the `Authorization` header as a bearer token. A key belongs to one company and acts only on that company's services, with the [permissions](/developer-tools/api-keys#permissions) set on the key. Requests must use HTTPS. | Status | When | | - | - | | `401` | No key, or the key is wrong, disabled, expired or deleted | | `403` | The key is valid but lacks a permission: `This API key is missing the APP:UPDATE permission. Grant it to the key or use a key that has it.` | See [Authentication](https://api-docs.sevalla.com/v3/authentication) in the API reference. ## Long-running operations Deployments, restores and similar operations run in the background. The request returns right away, usually with the new object (a deployment with `status` `waiting` or `inProgress`). Poll the object's `GET` operation until its status is final. Deployment statuses are `waiting`, `inProgress`, `success`, `failed`, `cancelled` and `skipped`. ## Pagination List operations are paginated with two query parameters, and every list response has the same shape. | Parameter | Default | Range | | - | - | - | | `limit` | `25` | `1` to `100` | | `offset` | `0` | `0` to `10000` | ```json theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} { "data": [], "total": 42, "offset": 0, "limit": 25 } ``` To read every item, add `limit` to `offset` until `offset` reaches `total`. See [Pagination](https://api-docs.sevalla.com/v3/pagination). ## Errors Errors return an HTTP status code and a JSON body: ```json theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} { "message": "This API key is missing the APP:UPDATE permission. Grant it to the key or use a key that has it.", "status": 403, "data": {} } ``` | Status | Meaning | | - | - | | `400` | The request is invalid. A body or parameter that doesn't match the schema returns `Request doesn't match the schema`. On operations whose reference page doesn't list a `400` response, `data.issues` describes each problem; on the others, `data` is empty. | | `401` | Missing or invalid API key | | `403` | The key lacks a permission, the company is suspended (`The service is suspended.`), or the company is being migrated or maintained, which blocks changes but not reads (`Your company is being migrated to new infrastructure. Changes are disabled until the migration finishes.`) | | `404` | The resource doesn't exist, or the key can't see it | | `429` | A [rate limit](#rate-limits) was reached | | `500` | An error on Sevalla's side. Retry with exponential backoff. | Every response has an `x-request-id` header. Include it when you [contact support](/support/get-help). Don't retry `4xx` errors without changing the request. See [Errors](https://api-docs.sevalla.com/v3/errors). ## Rate limits The API limits how many requests a company can make. Requests are counted per company (the company of the API key), and per company and service for the tiers that act on one service. In every tier except reads, each operation has its own count: creating 20 applications in an hour doesn't stop you from creating a database. Requests without a valid key are counted per IP address. | 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, and adding, updating, deleting or refreshing custom domains | | 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 running a command in a process | | Deployment | 10 per minute | Service and company | Triggering, rolling back and cancelling deployments | | General write | 30 per minute | Company | Other writes: environment variables, processes, backups, internal connections, pipelines, projects, webhooks, API keys, registry credentials | | Logs | 30 per minute | Company | Deployment, runtime and access logs, repository browsing, process exit codes | | Read | 400 per minute | Company | Every other request | Each response carries `x-ratelimit-limit`, `x-ratelimit-remaining` and `x-ratelimit-reset` (seconds until the window resets). When you reach a limit, the API returns `429` with a `retry-after` header: wait that many seconds, then retry with exponential backoff and jitter. See [Rate limits](https://api-docs.sevalla.com/v3/rate-limits) in the API reference. ## Tools built on the API You don't always need to call the API by hand. These tools use it with the same API keys: | Tool | Use it for | | - | - | | [Sevalla CLI](/developer-tools/cli) | Commands in a terminal or a CI script, with JSON output | | [Sevalla MCP server](/ai-agents/overview) | AI agents that deploy, debug and manage services | | [Terraform provider](/developer-tools/terraform) | Services defined as code | | [GitHub Actions](/developer-tools/github-actions) | Deployments and promotions from a workflow | | [Webhooks](/developer-tools/webhooks) | Events pushed to your endpoint instead of polling | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.