A deployment API is a programmatic way to send an application version to a target environment, apply configuration, start or promote it, and observe success or failure. It replaces clicks in a hosting panel with authenticated requests from a CI system, internal tool, or SaaS backend.
The term is ambiguous. Some deployment APIs record that a release should happen, while another system performs it. Others accept source files or an image and run the workload themselves. Check which contract a product means before designing around the name.
Three APIs often share the same label
| API TYPE | WHAT IT CONTROLS | TYPICAL CALLER |
|---|---|---|
| Deployment record API | A release request, environment, status, and links | CI system coordinating another deployer |
| Hosting deployment API | Artifact upload, runtime, configuration, process, URL, and lifecycle | A product that publishes customer apps |
| Infrastructure API | Machines, networks, load balancers, and storage primitives | A platform engineering or operations team |
GitHub's Deployments API is an example of the first type. It creates deployment objects and statuses that external systems can act on. Firebase Hosting's REST flow is closer to the second type for static content because it creates a version, uploads files, and releases that version to a site.
A complete deployment is a state machine
- 01Authenticate the callerUse a server credential with only the scopes this integration needs.
- 02Create an immutable versionIdentify the source bundle, image digest, or uploaded artifact so retries refer to the same bytes.
- 03Apply runtime configurationChoose the entry point, environment values, memory, and destination without placing secrets in the artifact.
- 04Build and startReturn a deployment identifier even if installation and startup continue asynchronously.
- 05Observe the resultExpose states, logs, errors, health, and the final URL in a machine-readable response.
- 06Promote or roll backMove traffic to a known version and keep a path back when the new process fails.
The contract matters more than the POST endpoint
| CAPABILITY | WHY IT MATTERS |
|---|---|
| Idempotency | A timed-out retry must not create a second app or second bill |
| Large artifact upload | Source bundles should not be forced through one JSON request body |
| Scoped credentials | A deploy key rarely needs permission to delete production apps |
| Tenant isolation | A SaaS must map its customer identifier to separate hosted resources |
| Status and logs | The caller needs enough evidence to explain a failed publish action |
| Rollback | A known version should be recoverable without rebuilding it |
| Domain lifecycle | Publishing often includes DNS verification and certificate state |
| Deletion recovery | Automation mistakes should not destroy customer work immediately |
| Usage and billing data | The platform must reconcile hosted resources with customer plans |
When to build on an API instead of a dashboard
Use a deployment API when publish is part of your product, when many similar apps must be provisioned, or when a CI pipeline must produce the same result every time. A dashboard is enough for occasional manual releases. Direct infrastructure APIs make sense when custom networking, compliance controls, or unusual runtimes justify owning the orchestration layer.
What Spocket exposes to a SaaS backend
Spocket's Platform API is a hosting deployment API. A backend can create an app and deploy its first version in one call, upload larger zip bundles through a signed URL, group apps by the caller's customer reference, read status and logs, control power, and manage custom domains.
Credentials have separate read, write, delete, and domain scopes. Idempotency keys protect create requests from duplicate retries. Deleting stops the app and billing immediately, while the underlying app remains recoverable for seven days.
The API runs on the Fleet plan, which includes 20 apps. Additional running apps cost $2.45 per month each at the current published rate. It supports Spocket's Node and Python hosting shape, not arbitrary virtual machines or a managed database. Read /documentation/platform-api for the request contract or /platform-hosting for the product decision.