API reference

Create a user, team and default project

Log in and receive a session token

When the user has two factor sign in, the first call answers 401 totp_required; repeat it with totp set to the six digit authenticator code or an unused recovery code. Team owners must enable two factor when REQUIRE_TOTP_FOR_OWNERS is on; until then console sessions get 403 totp_setup_required on every route except the account and two factor endpoints. API tokens are exempt.

Confirm an email address with the token from the verification email

Send the verification email again for the signed in user

Send a password reset link

Always returns 204 so email addresses cannot be probed. Limited to 5 requests per 10 minutes per IP.

Set a new password with the token from the reset email

Start two factor enrollment

Returns a new secret and an otpauth:// URL to show as a QR code. Nothing is enforced until /auth/totp/enable confirms a code.

Confirm the authenticator and turn two factor on

Returns ten recovery codes exactly once. Each recovery code signs the user in a single time.

Turn two factor off (needs a current code or a recovery code)

Social sign in providers that are configured (the console shows a button for each)

Start sign in with Google or Microsoft (the browser navigates here)

Redirects to the provider with the authorization code flow, PKCE (S256), state and nonce, scopes openid email profile. Sets an HttpOnly, Secure, SameSite=Lax cookie that binds the sign in to this browser; the pending state lives on the server for 10 minutes. intent=link needs a ticket from POST /auth/oauth/link-ticket. Errors redirect to the console /auth/callback?error=<code>.

Provider redirect URI

Checks state and the browser cookie, exchanges the code with the PKCE verifier, verifies the id token (signature against the provider key set, audience, issuer, nonce) and redirects to the console /auth/callback?code=<one time code> (valid 60 seconds). Session tokens never appear in URLs. Error codes: state_invalid, cancelled, provider_error, token_invalid, link_from_security, identity_in_use, email_missing, account_exists, invite_email_mismatch, invite_invalid, link_session_invalid.

Redeem the one time code from the console callback

Same answer as /auth/login, plus created and returnTo. Accounts with two factor sign in get { totpRequired, ticket } instead; finish with /auth/oauth/totp.

Second factor for a social sign in

One time ticket (60 seconds) to link Google or Microsoft to the signed in user

Console sessions only; API tokens get 403. Pass it to /auth/oauth/{provider}/start?intent=link&ticket=….

Linked Google and Microsoft accounts, whether a password is set, and which providers can be linked

Unlink a Google or Microsoft account

Current user, team, role and scopes

List projects

Create a project

List API tokens

Create an API token (human or AI agent)

Agent-safe tokens set isAgent: true and may carry spendCapMinor (monthly hard cap) and requireApprovalFor (e.g. ["servers:delete","servers:resize-down"]). A token can never carry scopes its creator does not have.

Revoke a token

Team audit log (newest 200 entries)

Register interest in a roadmap product ("notify me when this launches")

List SSH keys

Add an SSH public key

Delete an SSH key

List approval requests (agents see only their own)

Get one approval request

Approve and run the parked request

Team owners and admins only, never an agent token. The request runs with the agent token's project scope and spending cap still applied; the audit log records both the person and the token.

Deny the parked request

Time series for a server

One point per minute for 1h, 6h and 24h; hourly averages (with the hour's CPU peak) for 7d and 30d. Network and disk are bytes per second; multiply by 8 and divide by a million for Mbps.

List alert rules

Create an alert rule

Fires when the metric, averaged over windowMinutes, is above or below the threshold on any matching server. Empty serverIds and tags means every server in the team. Owners and admins are emailed, plus any addresses in emails; webhooks get alert.triggered and alert.resolved.

Incidents (open and recent)

Get an alert rule with recent incidents

Update an alert rule (any field, including enabled to mute)

Delete an alert rule

List servers

Create a server

Returns 202 immediately with status: new. A durable workflow places the server, reserves a public IP, clones the image, waits for cloud-init, applies the firewall and starts metering. Watch status become active (30–60 s) or subscribe to server.active. The server is never billed unless it reaches active.

Get a server

Rename, retag, or turn backups or the managed tier on or off

Turning managed on also turns backups on. A server that never had the care agent gets it on its next rebuild, or right away with the install command from GET /servers/{id}/managed.

Delete a server

Returns 202; the server moves to deleting and is removed by a workflow. Metering stops immediately.

Managed tier status

Health from the care agent's last report, the report itself, and the install command while the agent is not reporting.

Care agent install script

Public, keyed by the server's managed token. Served as a shell script for curl | sh.

Care agent report

Posted by the agent inside a managed server every five minutes, authenticated by the X-Prgd-Managed-Token header.

List recent actions on a server

Run a lifecycle action

List regions

List server sizes

List images

Public price list (USD base; SAR converted at the current exchange rate)

List Git deployments

Deploy a Git repository onto a new server

Creates a server whose cloud-init installs Docker, clones the repo, builds (Dockerfile or docker-compose) and serves it on :80. Two ways to name the repository: repoUrl (public, or private with gitToken) returns a per deployment GitHub webhook URL and secret (shown once) to add to the repository; installationId + repo ("owner/name") uses the team's GitHub App installation, needs no token, and redeploys on every push through the app webhook (webhook is null).

Get a deployment (refreshes status from the server)

Redeploy now

GitHub push webhook (verified with X-Hub-Signature-256)

Tail of the last build log

Fetched live from the server when it is reachable, otherwise the last cached copy. Capped at 32 KB.

Whether the GitHub App integration is configured

URL to install the GitHub App for this team

Send the user there. GitHub returns them to the console callback with installation_id and the signed state, which the console posts to /github/installations.

GitHub App installations linked to the team

Link an installation after the GitHub redirect

Unlink and uninstall

Repositories the installation can reach

GitHub App webhook (push, installation)

One URL for every installation, verified with X-Hub-Signature-256 and the app webhook secret. A push redeploys every deployment on that repository and branch.

List firewalls

Create a firewall

Get a firewall

Delete a firewall

Replace all rules (re-applied to attached servers immediately)

Attach a server

Detach a server

List public IPs in a project

List snapshots

Delete a snapshot

List volumes

Create a volume

Allocates a block volume in the region. Returns 202; the volume becomes available within seconds, or attached when serverId is given.

Get a volume

Delete a volume

The volume must be detached. Data is gone for good.

Attach to a server

Hot plugs the volume. The server must be in the same region and active or off. The guest sees the disk at device.

Detach from its server

Unmount the file system in the guest first.

Grow a volume

Volumes only grow. An attached volume grows live; extend the file system in the guest afterwards.

List load balancers

Create a load balancer

Reserves a public IP, creates one to three HAProxy nodes and pushes the forwarding rules. Returns 202; status becomes active once every node runs the config.

Get a load balancer with target health

Change rules

Delete a load balancer

Deletes the nodes and releases the IP.

Add target servers

Remove a target server

List certificates

Add a certificate

Either an uploaded PEM pair (custom) or a list of domains the load balancer gets issued by Let's Encrypt (letsencrypt). Point the domains at the load balancer IP first.

Delete a certificate

List hosted zones

Add a domain

Creates the zone on our nameservers. Set the domain's nameservers at the registrar to the ones returned. Free.

Get a zone with its records

Delete a zone and its records

The zone in BIND format

Add a record

Change a record

Delete a record

Set reverse DNS (PTR) for a public IP

List buckets

Create a bucket

Names are global and DNS safe (3 to 63 lowercase letters, digits, hyphens). Billed per GB per month.

Get a bucket

Change public read

Delete an empty bucket

List objects under a prefix

Delete one object

Presigned URL for GET

List S3 access keys (no secrets)

Create an access key; the secret is returned once

Revoke an access key

List managed database clusters

Create a cluster

One node, or three nodes with automatic failover. Returns 202; the cluster becomes active in a few minutes. Priced per node per month.

Engines and versions on offer

Get a cluster with connection details and secrets

Change trusted sources or the backup hour

Delete a cluster and its nodes

Add a user (password returned once)

Delete a user

Reset a user's password (returned once)

Add a database

Remove a database from the cluster

List backups

Take a backup now

Kubernetes versions on offer

List clusters

Create a cluster

Returns 202 with status creating. One control plane node is included; ha gives three behind one address for a flat monthly fee. Worker pools are sized like servers (at least 2 GB of memory) and billed as servers. Bootstrapping takes about ten minutes; poll until active, then fetch the kubeconfig.

Get a cluster with its pools

Rename a cluster

Delete a cluster with its nodes and the load balancers and volumes it created

Admin kubeconfig as YAML

Needs kubernetes:write. Treat it like a password.

Add a worker pool

Scale a pool

Growing adds servers; shrinking drains and removes the highest numbered nodes first.

Remove a pool and its nodes

Container sizes

List apps

Create an app

Push code, get a URL. Returns 202 with status creating; the platform picks a shared host (or starts one), builds the repository (a Dockerfile at the root, or a generated one for Node, Python, Go and static projects), runs instances containers of size and serves them at https://<name>.<apps domain> with TLS. Name the repository with repoUrl (and gitToken for a private one) or with installationId and repo from the GitHub App, which also redeploys on every push. Poll until live; on failed, read the build log.

Get an app

Change configuration and deploy again

env replaces the whole set. A bigger size or more instances checks the spend limit and the host's room.

Delete an app

Build and deploy the branch head now

Stop the instances and the charge

Start a stopped app

Deploy history

Build or runtime log

Fetched live from the host when reachable; the build log is cached on the app otherwise. Capped at 32 KB.

Attach a custom domain

Point a CNAME at the app hostname; the certificate is issued on the first request.

Detach a custom domain

List marketplace apps

App categories with counts

Get an app (its `variables` describe the one-click form)

Start a card payment that becomes prepaid credit

Returns the hosted Moyasar payment page (mada, Visa, Mastercard, Apple Pay) to send the person to. Agents cannot call this.

Pay an open invoice by card

Invoice as PDF

Card payments of the team

Moyasar webhook (payment events

Moyasar callback after the hosted page (result verified by retrieving the invoice)

Credit balance

Rated usage per resource

List invoices

Get an invoice with its usage lines

Support plan catalog

Public. Plans with first response targets per priority (hours, null when the priority is not allowed on the plan) and the monthly price in the requested currency.

The team's support plan

Change the support plan

Needs billing:write. An upgrade checks the spend limit on the team's oldest project; a downgrade applies at once. Open tickets keep the targets of the plan they were opened under.

List tickets

Open a ticket

Priority must be allowed on the team's plan (400 with the allowed list otherwise). resource names what the ticket is about and must belong to the team. Owners and the opener get every answer by email.

Get a ticket with its messages

Reply on a ticket

Reopens a closed ticket for up to 14 days after it was closed.

Close a ticket

Active managed cloud plans

Prices exclude VAT. priceMinor is null for a custom plan. Targets are minutes per priority; on BUSINESS_HOURS plans they count working minutes (09:00 to 17:00 on working days of the contract calendar, public holidays excluded).

The team's contracts

Team owners only.

Request a managed cloud plan

Team owners only. Creates a DRAFT contract with the default responsibility matrix. A support lead reviews it, signs it and starts onboarding; the contract becomes ACTIVE, and billing starts, when onboarding is complete. One pending request per team.

Contract detail with SLA, responsibility matrix, onboarding progress and this month's engineer time

Team owners only.

Assets under management with health

Ask for an asset to be managed

Team owners only. The asset stays PENDING until an engineer approves it. PLATFORM_SERVER needs serverId; EXTERNAL_SERVER and SITE need address. Limited by the plan's maxAssets.

Every managed asset of the team

Monthly reports that were sent

Team owners only. Reports are drafted on the 1st and sent by the 3rd.

Download a monthly report as PDF

Managed cloud tickets

Open a ticket

Due times come from the plan's targets and the contract calendar. P1 and P2 page the engineer on call. contractId is needed only when the team has more than one contract; assetId implies it. Not allowed while the contract is suspended.

A ticket with its messages

Internal engineer notes are never included.

Reply on a ticket

Reopens a closed ticket for up to 14 days after it was closed.

Close a ticket

List webhooks

Create a webhook

Deliveries are signed with X-Prgd-Signature: sha256=<hmac> using the secret returned once at creation.

List subscribable event names

Delete a webhook