API
Deployments

Deployments API

The Deployments API allows you to create, list, get, and destroy deployments.

Create Deployment

Create a new deployment.

POST /api/v1/deployments

Request Body:

{
  "app_type": "airflow",
  "name": "Production Airflow"
}

Fields:

  • app_type (required) - Application type: airflow or superset
  • name (optional) - Human-readable name. If omitted, auto-generated.

Example:

curl -X POST \
  -H "X-API-Key: onv_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"app_type": "superset", "name": "My Superset"}' \
  https://api.onvera.io/api/v1/deployments

Response (202 Accepted):

{
  "data": {
    "deployment_id": "550e8400-e29b-41d4-a716-446655440000",
    "operation_id": "op_660e8400-e29b-41d4-a716-446655440001",
    "links": {
      "deployment": "/api/v1/deployments/550e8400-e29b-41d4-a716-446655440000",
      "operation": "/api/v1/operations/op_660e8400-e29b-41d4-a716-446655440001"
    }
  }
}

Required Scope: deployments:write

ℹ️

Deployment is processed asynchronously. Poll the operation endpoint to track progress.

List Deployments

List all deployments for your organization.

GET /api/v1/deployments

Query Parameters:

  • page (optional, default: 1) - Page number (1-indexed)
  • per_page (optional, default: 50, max: 100) - Items per page

Example:

curl -H "X-API-Key: onv_sk_live_..." \
  "https://api.onvera.io/api/v1/deployments?page=1&per_page=50"

Response:

{
  "data": {
    "items": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Production Airflow",
        "app_type": "airflow",
        "status": "ready",
        "url": "https://airflow.abc123.onvera.io",
        "environment_id": "env_default",
        "created_at": "2024-01-20T12:00:00Z",
        "links": {
          "self": "/api/v1/deployments/550e8400-e29b-41d4-a716-446655440000",
          "operation": null
        }
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total": 1,
      "pages": 1
    }
  }
}

Required Scope: deployments:read

Get Deployment

Get details for a specific deployment.

GET /api/v1/deployments/{deployment_id}

Example:

curl -H "X-API-Key: onv_sk_live_..." \
  https://api.onvera.io/api/v1/deployments/550e8400-e29b-41d4-a716-446655440000

Response:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production Airflow",
    "app_type": "airflow",
    "status": "ready",
    "url": "https://airflow.abc123.onvera.io",
    "environment_id": "env_default",
    "created_at": "2024-01-20T12:00:00Z",
    "links": {
      "self": "/api/v1/deployments/550e8400-e29b-41d4-a716-446655440000",
      "operation": null
    }
  }
}

Required Scope: deployments:read

Delete Deployment

Destroy a deployment and remove all associated resources.

DELETE /api/v1/deployments/{deployment_id}

Example:

curl -X DELETE \
  -H "X-API-Key: onv_sk_live_..." \
  https://api.onvera.io/api/v1/deployments/550e8400-e29b-41d4-a716-446655440000

Response (202 Accepted):

{
  "data": {
    "operation_id": "op_660e8400-e29b-41d4-a716-446655440001",
    "links": {
      "operation": "/api/v1/operations/op_660e8400-e29b-41d4-a716-446655440001",
      "deployment": "/api/v1/deployments/550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Required Scope: deployments:write

⚠️

This operation is irreversible. All data and resources will be permanently deleted.

ℹ️

Destruction is processed asynchronously. Poll the operation endpoint to track progress.

Deployment Status

Deployments have the following statuses:

  • provisioning - Deployment is being created
  • ready - Deployment is ready and accessible
  • destroying - Deployment is being destroyed
  • failed - Deployment failed (cannot be recovered)
  • destroyed - Deployment has been destroyed

Deployment Properties

Each deployment includes:

  • id - Unique identifier (UUID)
  • name - Human-readable name
  • app_type - Application type (airflow or superset)
  • status - Current status
  • url - Access URL (when ready)
  • environment_id - Environment ID (typically env_default)
  • created_at - ISO 8601 timestamp
  • links - HATEOAS links to related resources

Error Responses

400 Bad Request

Invalid request (e.g., invalid app_type):

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid app_type. Must be 'airflow' or 'superset'"
  }
}

401 Unauthorized

Invalid or missing API key:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

403 Forbidden

Insufficient scope:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Insufficient scope. Required: deployments:write"
  }
}

404 Not Found

Deployment not found:

{
  "error": {
    "code": "DEPLOYMENT_NOT_FOUND",
    "message": "Deployment not found"
  }
}

Related Concepts

OperationsErrors