Organization API: Organization deployments: Deployments

Part of Organization deployments.

GET /api/v1/orgs/{org_slug}/deployments

The caller's deployments of every kind, newest first. counts holds how many each status has and kinds how many each kind has, under the same filters (the one counted aside), so tiles and tabs add up to what the list shows. A kind switched off lists none.

GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}

One deployment with its instances, its domains and its five newest releases (releases_total counts them all). A template's instances are its servers, with their power state.

PATCH /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}

Change a deployment's settings in the order's words: name for every kind; build (preset, install_command, build_command, start_command, output_dir) and runtime (port, health_check_path) for the kinds that build or run; image.ref for an image deployment. A build.dockerfile_path that names a file answers 422 dockerfile_unsupported (Dockerfiles are not built: deploy the image your CI builds as a container image); a null one clears an old one. A template's servers change under /api/v1/client/servers (409 template_deployment); placement, git, processes and scaling have routes of their own (422 naming them). redeploy_required and rebuild_required say whether running instances pick the change up only with a new release or a new build.

application/json (required)

Type: Body.

DELETE /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}

Delete a deployment. One a service pays for (every template, and a deployment ordered through the services page) cancels that service now: its terminate job removes the servers or the replicas, its unpaid invoices are voided and, for a template, keep_snapshot saves the server's data first, as cancelling from the services page does. An Apps app with no service is deleted at once: releases on their way canceled, routes and domains removed, replicas drained, variables erased. It cannot be undone. A deployment already ending answers 409 already_ending. What its bindings made is revoked once the deletion commits (for one a service pays for, when that service ends).

GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/alerts

What the deployment's owner was alerted about, newest first: kind, at, summary, incident (the release, or the hour), emailed, held (a failed release inside the hour after another was emailed), webhooks (deliveries queued) and details.

GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/analytics

Page views and distinct visitors per UTC day of window (7d, 30d, 90d) for the deployment's hostnames, as the tracking collector saw them, with the totals per hostname. Only pages that load the tracking script are counted, by the hostname they report; notes say what that can and cannot attribute.

GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/instances

The deployment's running copies. A template's are its servers, each with its power state and server_uuid (its power, console and files are under /api/v1/client/servers/{server_uuid}); a stateless deployment's are its live replicas with the release each runs; a static deployment has none.

GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/metrics

Every hour of window (24h, 7d, 30d): requests, blocked, status (2xx to 5xx), bytes_in, bytes_out, latency_avg_ms, latency_p99_ms, websockets; the totals with error_rate; and each running or sleeping instance's cpu (percent of one core: now, avg_15m, avg_1h) and memory_bytes, from its latest reading, with its history: every step of instance_window (1h in five minutes, 24h in fifteen, 7d in hours), oldest first, each at, samples, cpu_avg, cpu_max, memory_avg_bytes and memory_max_bytes (0 samples and nulls where nothing was read). instance_history says the window, step_seconds, from, to and kept_days. notes say what the figures cannot show.

GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/placements

Where the deployment runs (placement), whether it can be changed here and the locations it could run in now.

PUT /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/placements

Change where the deployment runs, checked exactly as an order's placement is (422 naming the field, 402 past the plan's locations or autoscaling). The current release is re-placed at once: locations added get instances, instances beyond a location's count and those of a location left drain once another location serves. A template answers 409 template_placement; a static deployment takes only {"mode": "all"}.

application/json (required)

Type: Body.

GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/processes

The deployment's processes, each with its kind, command, schedule, instances per location and whether it is enabled, and what the production release runs of it: a worker's running instances; a cron's next time, its last run and whether one is going now. With none, the release runs its web only. A template or a static deployment has none (changeable false).

PUT /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/processes

Replace the deployment's processes with the list in processes, each checked as an order's runtime.processes are (422 naming the field) and taking enabled (true when left out). web serves the port, running its command instead of the image's own when it names one, as many as the placement says; a worker runs instances copies in every location; a cron runs at each time its schedule names, in the first location. The production release's heal is queued at once: the workers and crons it lacks start, and those removed, disabled or beyond their count drain. A changed command reaches a cron at its next run, and a worker or the web when it starts again (redeploy_required). A template or a static deployment answers 409.

application/json (required)

Type: Body.

POST /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/redeploy

Release the current build again (picking up variables, size, placement and scaling changes), or build the branch afresh with rebuild.

application/json

GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/requests

The requests every edge location sampled on the deployment's addresses in the last retention_days (3), newest first, the newest limit that match every filter given: status (a class), path (a prefix, without the query string), release, location and hostname. next is the cursor of the page after them (pass it as before), null at the oldest. Each: id, ts, hostname, method, path, status, latency_ms, bytes_out, release, location, cache (hit, miss, static or bypass), client_ip and country. sample says what an edge process keeps: every request up to full_per_second a second per address, then 1 in then_one_in and every 5xx, at most most_per_second. 422 invalid_cursor for a before that is not a page's next; 404 unknown_hostname; 429 past 120 pages a minute.

GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/rules

The deployment's own firewall rules and rate limits, oldest first, in the Websites shape (id is the rule's name). managed_rules counts the managed set's enabled rules; account counts the enabled rules of the owner's own across their websites and deployments, which is what the plan counts; limits is the plan's allowance while plans cover the account, else null (-1 is no limit).

PUT /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/rules

Make rules the deployment's own set on every one of its addresses. 409 while it has no address; 422 for a rule that does not check out (index names it) or past 200 rules or 50 rate limits; 402 when the owner's plan leaves no room, counted with their websites.

application/json (required)

GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/scaling

How the deployment scales: the targets one instance should carry (targets as set, effective_targets as applied: CPU 70% when it sets none), until when billing caps its bursts, sleep_after_seconds and the idle_seconds that apply, and each location's counts and sleep (under /placements), between which it scales and which decide whether a location sleeps. A template or a static deployment has none (changeable false).

PUT /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/scaling

Change the autoscaling targets and the idle time, checked as an order's scaling is: the whole block, a key left out being null (no targets: CPU 70%; no idle time: 15 minutes where a location sleeps). Targets need autoscaling on the plan (402). A cap billing holds on the bursts stays. The sweeps read the change within a minute; nothing starts or stops here. A location scales only when its max is above its min, and sleeps only when its sleep is idle: both change under /placements. A template or a static deployment answers 409.

application/json (required)

Type: Body.

POST /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/uploads

Release the uploaded archive: it is checked, a release is created and its build queued, and the archive is stored for the build container.

GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/usage

The deployment's metered use in a month (this month so far when month is left out), by meter and in each meter's unit: what it used, what its allowances included and what was billable. No money: what it cost is under /api/v1/billing/deployments/{uuid}, for the account's Billing role. A template is billed by its plan and meters nothing.