Builds API

Deploy your application by creating builds through the API.

GET/organizations/:orgId/projects/:projectId/endpoints

Returns the URLs for each stage of a project.

Response

{
  "endpoints": [
    {
      "stage": "production",
      "endpoint": "https://abc123.justdeploy.site",
      "domains": [
        { "domain": "www.example.com", "type": "subdomain" }
      ]
    },
    {
      "stage": "development",
      "endpoint": "https://abc123-test.justdeploy.site",
      "domains": []
    }
  ]
}

The domains array contains any custom domains connected to that stage. Custom domains are only available for the Live stage.

GET/organizations/:orgId/projects/:projectId/builds

Returns the most recent builds for a project (up to 50).

Response

{
  "builds": [
    {
      "id": "b1234567-abcd-...",
      "stage": "production",
      "commit": null,
      "version": "1.0.0",
      "runtime": "nodejs22.x",
      "size": 524288,
      "status": "ready",
      "error": null,
      "createdAt": "2026-03-20T...",
      "updatedAt": "2026-03-20T..."
    }
  ]
}

POST/organizations/:orgId/projects/:projectId/builds

Create a new build. Returns a presigned upload URL for uploading your application code as a .zip file.

Request body

{
  "stage": "production"
}

Response

{
  "build": {
    "id": "b2345678-efgh-...",
    "stage": "production",
    "commit": null,
    "version": null,
    "runtime": null,
    "size": null,
    "status": "pending",
    "error": null,
    "createdAt": "2026-03-20T...",
    "updatedAt": "2026-03-20T..."
  },
  "url": "https://upload.justdeploy.net/..." // Presigned upload URL
}

Upload your zip file to the presigned URL:

Upload

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/zip" \
  --data-binary @app.zip

If a build for this project and stage is already in progress, the request returns 409 Conflict with the existing build so you can poll it and retry once it finishes.

Conflict response (409)

{
  "status": "Conflict",
  "message": "A build is already in progress for this stage.",
  "build": {
    "id": "b1234567-abcd-...",
    "stage": "production",
    "status": "building",
    "createdAt": "2026-05-05T..."
  }
}

GET/organizations/:orgId/projects/:projectId/builds/:buildId

Check the status of a build. Poll this endpoint until the status reaches ready or error.

Response

{
  "build": {
    "id": "b2345678-efgh-...",
    "stage": "production",
    "commit": null,
    "version": "1.0.0",
    "runtime": "nodejs22.x",
    "size": 524288,
    "status": "ready",
    "error": null,
    "createdAt": "2026-03-20T...",
    "updatedAt": "2026-03-20T..."
  }
}

Full deployment flow

Complete example

# 1. Create a build
BUILD=$(curl -s -X POST \
  "https://api.justdeploy.net/organizations/ORG_ID/projects/PROJECT_ID/builds" \
  -H "X-Access-Key: $ACCESS_KEY" \
  -H "X-Secret-Key: $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stage": "production"}')

UPLOAD_URL=$(echo $BUILD | jq -r '.url')
BUILD_ID=$(echo $BUILD | jq -r '.build.id')

# 2. Upload your code
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/zip" \
  --data-binary @app.zip

# 3. Poll for completion
curl -s \
  "https://api.justdeploy.net/organizations/ORG_ID/projects/PROJECT_ID/builds/$BUILD_ID" \
  -H "X-Access-Key: $ACCESS_KEY" \
  -H "X-Secret-Key: $SECRET_KEY"

Supported runtimes

JustDeploy detects your runtime automatically from your project. The runtime field returned in the build response is one of:

nodejs24.x
nodejs22.x
python3.14
python3.13
python3.12
java21
java17