Services are the core resources in Aiven, including databases like PostgreSQL and MySQL, streaming platforms like Apache Kafka, and other data infrastructure services.
List services Retrieve all services in a project.
GET /v1/project/{project}/service
Request example curl -X GET "https://api.aiven.io/v1/project/my-project/service" \ -H "Authorization: aivenv1 YOUR_TOKEN"
Response List of service objects Type of service (e.g., pg, kafka, mysql, opensearch)
Current state: RUNNING, REBUILDING, REBALANCING, POWEROFF
Cloud region where the service is deployed
Service plan (e.g., business-4, startup-8)
Connection URI for the service
Connection parameters (host, port, user, password, etc.)
ISO 8601 timestamp of service creation
ISO 8601 timestamp of last update
Number of nodes in the service
Whether termination protection is enabled
Response example { "services" : [ { "service_name" : "pg-demo" , "service_type" : "pg" , "state" : "RUNNING" , "cloud_name" : "google-europe-west3" , "plan" : "business-4" , "create_time" : "2024-01-15T10:30:00Z" , "update_time" : "2024-03-01T14:20:00Z" , "node_count" : 3 , "disk_space_mb" : 81920 , "termination_protection" : false , "service_uri" : "postgres://avnadmin:[email protected] :12345/defaultdb?sslmode=require" } ] }
Get service details Retrieve detailed information about a specific service.
GET /v1/project/{project}/service/{service_name}
Request example curl -X GET "https://api.aiven.io/v1/project/my-project/service/pg-demo" \ -H "Authorization: aivenv1 YOUR_TOKEN"
Response Detailed service information (same structure as list services)
Create service Create a new Aiven service.
POST /v1/project/{project}/service
Request body Name for the new service (3-63 characters)
Service type: pg, mysql, kafka, opensearch, caching, clickhouse, grafana, etc.
Service plan (e.g., hobbyist, startup-4, business-4)
Cloud region (e.g., google-europe-west3, aws-us-east-1)
Total disk space in megabytes (overrides plan default)
VPC ID to deploy the service in
Enable termination protection (default: false)
Service-specific configuration options
Request example cURL - PostgreSQL
cURL - Kafka
Python
JavaScript
curl -X POST "https://api.aiven.io/v1/project/my-project/service" \ -H "Authorization: aivenv1 YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "service_name": "pg-prod", "service_type": "pg", "plan": "business-4", "cloud": "google-europe-west3", "termination_protection": true }'
Response The newly created service object with state REBUILDING
Services start in the REBUILDING state and transition to RUNNING when ready. This typically takes 5-15 minutes depending on the service type and plan.
Update service Update service configuration, plan, or cloud region.
PUT /v1/project/{project}/service/{service_name}
Request body Migrate service to different cloud region
Increase disk space (cannot be decreased)
Power service on (true) or off (false)
Enable or disable termination protection
Maintenance window configuration (dow, time)
Update service-specific configuration
Request example cURL - Scale up
cURL - Power off
Python - Update config
curl -X PUT "https://api.aiven.io/v1/project/my-project/service/pg-demo" \ -H "Authorization: aivenv1 YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "plan": "business-8" }'
Response The updated service object
Delete service Permanently delete a service and all its data.
DELETE /v1/project/{project}/service/{service_name}
This operation is irreversible. All service data will be permanently deleted. Services with termination protection enabled cannot be deleted until protection is disabled.
Request example curl -X DELETE "https://api.aiven.io/v1/project/my-project/service/pg-demo" \ -H "Authorization: aivenv1 YOUR_TOKEN"
Response Returns 200 OK with an empty response body on success.
List service types Get available service types and their descriptions.
Request example curl -X GET "https://api.aiven.io/v1/service_types" \ -H "Authorization: aivenv1 YOUR_TOKEN"
Response List of available service types Human-readable description
Response example { "service_types" : [ { "service_type" : "pg" , "description" : "PostgreSQL - Object-Relational Database Management System" , "latest_available_version" : "16" }, { "service_type" : "kafka" , "description" : "Kafka - High-Throughput Distributed Messaging System" , "latest_available_version" : "3.7" }, { "service_type" : "opensearch" , "description" : "OpenSearch - Search & Analyze Data in Real Time" , "latest_available_version" : "2.11" } ] }
List service plans Get available plans for a service type in a specific cloud region.
GET /v1/project/{project}/service_types/{service_type}/plans
Service type (e.g., pg, kafka)
Request example curl -X GET "https://api.aiven.io/v1/project/my-project/service_types/pg/plans?cloud=google-europe-west3" \ -H "Authorization: aivenv1 YOUR_TOKEN"
