Sevalla API

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.

What	Value
Base URL	`https://api.sevalla.com/v3`
API reference	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 <API key>`
Format	JSON request and response bodies, `snake_case` field names, UUIDs as IDs

Make your first request

Create an API key

In the sidebar, under Tools, click API keys, then create a key with the permissions your script needs. Company viewer is enough to read.

Call the API

Keep the key in an environment variable and send it as a bearer token:

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 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. 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 (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 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 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`

{
  "data": [],
  "total": 42,
  "offset": 0,
  "limit": 25
}

To read every item, add limit to offset until offset reaches total. See Pagination.

Errors

Errors return an HTTP status code and a JSON body:

{
  "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 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. Don’t retry 4xx errors without changing the request. See 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 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	Commands in a terminal or a CI script, with JSON output
Sevalla MCP server	AI agents that deploy, debug and manage services
Terraform provider	Services defined as code
GitHub Actions	Deployments and promotions from a workflow
Webhooks	Events pushed to your endpoint instead of polling

Get started

AI agents

Applications

Pipelines

Databases

Static sites

Object storage

Load balancers

Domains

Git providers

Projects

Developer tools

Company

Billing

Account

Platform

Security and compliance

Support

Make your first request

Authentication

Long-running operations

Errors

Rate limits

Tools built on the API

​Make your first request

​Authentication

​Long-running operations

​Pagination

​Errors

​Rate limits

​Tools built on the API

Make your first request

Authentication

Long-running operations

Pagination

Errors

Rate limits

Tools built on the API