Deploy an application with the API
Create configuration, queue a release, and observe its deployment and runtime state.
This walkthrough assumes a connected GitHub repository, a workspace UUID, and a write-scoped key. Replace the example repository with one your workspace can access.
Create service configuration
Read GET /catalog to choose an available plan and runtime. This example saves a free Python web service without deploying it:
{
"name": "example-api",
"kind": "web",
"configuration": {
"sourceType": "repository",
"repository": "https://github.com/example/example-api",
"branch": "main",
"runtime": "python",
"buildMethod": "railpack",
"rootDirectory": "backend",
"plan": "free",
"port": 8000,
"startCommand": "gunicorn config.wsgi:application --bind 0.0.0.0:8000"
},
"deploy": false
}Save the body as service.json. Ensure backend/config/wsgi.py exists and Gunicorn is included in your application's dependencies, or adjust the path and start command.
curl --fail-with-body --request POST \
--header "Authorization: Bearer $OPENSTEAD_API_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: configure-example-api-001" \
--data-binary @service.json \
"https://api.openstead.tech/api/v1/workspaces/$OPENSTEAD_WORKSPACE_ID/services"Store the returned service.id as OPENSTEAD_SERVICE_ID. To place it in a project, provide both projectId and a compatible environmentId; project creation returns its Production environment. Omitting both creates an ungrouped service.
For a paid plan, save configuration first and complete checkout in the dashboard before deploying. API credentials cannot authorize a purchase.
Queue a deployment
curl --fail-with-body --request POST \
--header "Authorization: Bearer $OPENSTEAD_API_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: deploy-example-api-001" \
--data '{}' \
"https://api.openstead.tech/api/v1/workspaces/$OPENSTEAD_WORKSPACE_ID/services/$OPENSTEAD_SERVICE_ID/deploys"The empty body deploys the configured branch. To select a commit, provide commitSha as a full lowercase hexadecimal SHA of 40–64 characters. Source access and deployment permissions still apply.
Record deployment.id from the response. Reuse the same idempotency key after an uncertain response; a new key requests another deployment.
Observe progress
Read GET /workspaces/{workspaceId}/services/{serviceId}/deploys/{deploymentId} until it reaches a terminal state.
| State | Meaning |
|---|---|
queued | Waiting for execution; inspect blockedReason if present. |
preparing, cloning, building | Preparing source and producing the release. |
predeploy, deploying, checking | Running release preparation and checking the deployed application. |
live | Deployment succeeded. |
failed | Deployment failed; inspect its error and logs. |
cancelled | Cancellation completed. |
superseded | Another release replaced this deployment request. |
The last four states are terminal. SDK wait helpers return on live and raise for unsuccessful terminal states.
Read the service to inspect its public url, serving status, and liveDeploymentId. A new deployment can be building while an earlier release continues serving traffic.
Updates, cancellation, and rollback
PATCH merges supplied configuration fields; omitted fields retain their values. The service kind is immutable. Saving configuration does not itself create a deployment.
Cancellation requests return cancelRequested: true; continue observing until the deployment reaches a terminal state.
Rollback creates a new deployment from a retained successful release, using that release's saved configuration and secret snapshot. Supply the exact service name in confirm, then poll the new returned deployment ID. Review application/database compatibility before rolling back code.
Runtime operations
POST .../services/{serviceId}/actions with {"action":"restart"}, suspend, or resume returns a queued operation. Poll GET .../operations/{operationId} until complete or failed. The deploy and clear-cache actions return a deployment instead.
Archive prevents new deployments by setting a configuration flag. It does not suspend infrastructure. Restore clears that flag without deploying.