HTTP API

The dply HTTP API lets you deploy, roll back, manage previews, domains, access rules and environment variables, tail logs, and read usage and billing from outside the dashboard. Use it from CI pipelines, deploy scripts or your own tooling. The CLI and the MCP server use the same tokens and abilities.

Every endpoint is listed with parameters and example responses in the API reference.

Base URL#

All endpoints live under a versioned prefix:

https://edge.dply.io/api/v1

Authentication#

Send an API token as a bearer token on every request, and ask for JSON:

curl https://edge.dply.io/api/v1/account \
  -H "Authorization: Bearer dply_your_token_here" \
  -H "Accept: application/json"

Tokens start with dply_. The API also accepts the token in an X-API-Key header, but Authorization: Bearer is the recommended form.

How a token is scoped#

Each token belongs to one user and one organization. A request succeeds only when all of these hold:

1. The token is valid. It exists and has not passed its expiry date.
2. The caller's IP is allowed. If the token has an IP allow-list, the request must come from an address on it.
3. The user still belongs to the organization. If the token's owner leaves or is removed from the organization, the token stops working immediately (403).
4. The token has the ability. Each endpoint requires one ability, such as edge.deploy.
5. The user's role allows it on that app. A token never outranks its owner. Read requests need permission to view the app; every other request needs permission to change it. See Roles & permissions.

If the owner's role in the organization is Deployer, the token is limited to the deployer abilities at request time, whatever abilities it was created with. The deployer abilities are account.read, account.write, edge.read, edge.deploy, edge.env.read, sites.read and servers.read.

Create a token#

1. Open Profile, then API keys.
2. Choose Add API token.
3. Pick the organization the token belongs to. Only organizations where you are an owner or admin are listed.
4. Enter a name that says where the token is used, for example github-actions-deploy.
5. Optionally set an expiry date. It must be after today. Without one, the token never expires.
6. Optionally add an IP allow-list: one IP address or IPv4 CIDR range per line (or separated by commas). IPv6 addresses must be exact.
7. Select at least one permission, then create the token.

dply shows the token once, under Copy this token now — you won't see it again. Store it in your CI secret store or a password manager.

If the page shows Pro plan required to create tokens, the organization needs an active plan before you can add tokens. Existing tokens can still be revoked.

Revoke a token#

On Profile → API keys, choose Revoke next to the token. It stops working immediately. Owners and admins can also see and revoke every token in the organization from the organization's settings. See Organizations.

Creating and revoking tokens is recorded in the Activity log.

Abilities#

Grant each token only what the integration needs.

Rate limits#

Requests are limited per token.

Both limits apply to Edge endpoints, so in practice a single token can make 60 requests per minute. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining headers. Over the limit, the API returns 429 Too Many Requests with a Retry-After header giving the seconds to wait.

Errors#

Errors are JSON objects with a message. Validation errors add an errors object keyed by field.

{
  "message": "The hostname field is required.",
  "errors": {
    "hostname": ["The hostname field is required."]
  }
}

Lists and pagination#

List endpoints return a data array and are not paginated. Endpoints that can grow return the most recent items, with a query parameter to widen the window:

IDs and timestamps#

IDs are ULID strings, such as 01j9z3k6x8m2q4r5t7v9w0y1a2. Find an app's ID with GET /api/v1/edge/sites or in the id field of any app response. Timestamps are ISO 8601 with a UTC offset.

Versioning#

The version is part of the path (/api/v1). Fields may be added to v1 responses; build clients that ignore fields they do not recognize. There is no version header.

What the API does not cover#

Create and delete apps, databases and queues in the dashboard. The API manages apps that already exist.

Next steps#

• API reference
• CLI
• MCP server
• Roles & permissions