Service Management

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

string

required

Project name

Request example

curl -X GET "https://api.aiven.io/v1/project/my-project/service" \
  -H "Authorization: aivenv1 YOUR_TOKEN"

import requests

project = "my-project"
headers = {"Authorization": "aivenv1 YOUR_TOKEN"}

response = requests.get(
    f"https://api.aiven.io/v1/project/{project}/service",
    headers=headers
)

services = response.json()["services"]
for service in services:
    print(f"{service['service_name']}: {service['service_type']} - {service['state']}")

const project = 'my-project';
const response = await fetch(
  `https://api.aiven.io/v1/project/${project}/service`,
  {
    headers: {
      'Authorization': 'aivenv1 YOUR_TOKEN'
    }
  }
);

const data = await response.json();
console.log(data.services);

Response

array

List of service objects

Show child attributes

string

Name of the service

string

Type of service (e.g., pg, kafka, mysql, opensearch)

string

Current state: RUNNING, REBUILDING, REBALANCING, POWEROFF

string

Cloud region where the service is deployed

string

Service plan (e.g., business-4, startup-8)

string

Connection URI for the service

object

Connection parameters (host, port, user, password, etc.)

string

ISO 8601 timestamp of service creation

string

ISO 8601 timestamp of last update

integer

Number of nodes in the service

integer

Disk space in megabytes

boolean

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:password@pg-demo-project.aivencloud.com:12345/defaultdb?sslmode=require"
    }
  ]
}

Get service details

Retrieve detailed information about a specific service.

GET /v1/project/{project}/service/{service_name}

string

required

Project name

string

required

Service name

Request example

curl -X GET "https://api.aiven.io/v1/project/my-project/service/pg-demo" \
  -H "Authorization: aivenv1 YOUR_TOKEN"

import requests

project = "my-project"
service = "pg-demo"
headers = {"Authorization": "aivenv1 YOUR_TOKEN"}

response = requests.get(
    f"https://api.aiven.io/v1/project/{project}/service/{service}",
    headers=headers
)

service_data = response.json()["service"]
print(f"Service: {service_data['service_name']}")
print(f"State: {service_data['state']}")
print(f"URI: {service_data['service_uri']}")

Response

object

Detailed service information (same structure as list services)

Create service

Create a new Aiven service.

POST /v1/project/{project}/service

string

required

Project name

Request body

string

required

Name for the new service (3-63 characters)

string

required

Service type: pg, mysql, kafka, opensearch, caching, clickhouse, grafana, etc.

string

required

Service plan (e.g., hobbyist, startup-4, business-4)

string

required

Cloud region (e.g., google-europe-west3, aws-us-east-1)

integer

Total disk space in megabytes (overrides plan default)

string

VPC ID to deploy the service in

boolean

Enable termination protection (default: false)

object

Service-specific configuration options

Request example

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
  }'

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": "kafka-prod",
    "service_type": "kafka",
    "plan": "business-4",
    "cloud": "aws-eu-west-1",
    "user_config": {
      "kafka_connect": true,
      "kafka_rest": true
    }
  }'

import requests

project = "my-project"
headers = {
    "Authorization": "aivenv1 YOUR_TOKEN",
    "Content-Type": "application/json"
}

data = {
    "service_name": "pg-prod",
    "service_type": "pg",
    "plan": "business-4",
    "cloud": "google-europe-west3",
    "termination_protection": True,
    "user_config": {
        "pg_version": "16"
    }
}

response = requests.post(
    f"https://api.aiven.io/v1/project/{project}/service",
    headers=headers,
    json=data
)

service = response.json()["service"]
print(f"Creating service: {service['service_name']}")
print(f"State: {service['state']}")

const project = 'my-project';
const response = await fetch(
  `https://api.aiven.io/v1/project/${project}/service`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'aivenv1 YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      service_name: 'pg-prod',
      service_type: 'pg',
      plan: 'business-4',
      cloud: 'google-europe-west3',
      termination_protection: true
    })
  }
);

const data = await response.json();
console.log('Created service:', data.service.service_name);

Response

object

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}

string

required

Project name

string

required

Service name

Request body

string

Change service plan

string

Migrate service to different cloud region

integer

Increase disk space (cannot be decreased)

boolean

Power service on (true) or off (false)

boolean

Enable or disable termination protection

object

Maintenance window configuration (dow, time)

object

Update service-specific configuration

Request example

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"
  }'

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 '{
    "powered": false
  }'

import requests

project = "my-project"
service = "pg-demo"
headers = {
    "Authorization": "aivenv1 YOUR_TOKEN",
    "Content-Type": "application/json"
}

data = {
    "user_config": {
        "ip_filter": ["10.0.0.0/8", "192.168.1.0/24"]
    }
}

response = requests.put(
    f"https://api.aiven.io/v1/project/{project}/service/{service}",
    headers=headers,
    json=data
)

print(f"Updated service: {response.json()['service']['service_name']}")

Response

object

The updated service object

Delete service

Permanently delete a service and all its data.

DELETE /v1/project/{project}/service/{service_name}

string

required

Project name

string

required

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"

import requests

project = "my-project"
service = "pg-demo"
headers = {"Authorization": "aivenv1 YOUR_TOKEN"}

response = requests.delete(
    f"https://api.aiven.io/v1/project/{project}/service/{service}",
    headers=headers
)

if response.status_code == 200:
    print(f"Service {service} deleted successfully")

Response

Returns 200 OK with an empty response body on success.

List service types

Get available service types and their descriptions.

GET /v1/service_types

Request example

curl -X GET "https://api.aiven.io/v1/service_types" \
  -H "Authorization: aivenv1 YOUR_TOKEN"

import requests

headers = {"Authorization": "aivenv1 YOUR_TOKEN"}
response = requests.get(
    "https://api.aiven.io/v1/service_types",
    headers=headers
)

for service_type in response.json()["service_types"]:
    print(f"{service_type['service_type']}: {service_type['description']}")

Response

array

List of available service types

Show child attributes

string

Service type identifier

string

Human-readable description

string

Latest version available

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

string

required

Project name

string

required

Service type (e.g., pg, kafka)

string

Filter by cloud region

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"

import requests

project = "my-project"
service_type = "pg"
cloud = "google-europe-west3"

headers = {"Authorization": "aivenv1 YOUR_TOKEN"}
response = requests.get(
    f"https://api.aiven.io/v1/project/{project}/service_types/{service_type}/plans",
    headers=headers,
    params={"cloud": cloud}
)

for plan in response.json()["plans"]:
    print(f"{plan['plan_name']}: ${plan['price_usd']}/hour")

Getting Started

Endpoints

Service Management

List services

Request example

Response

Response example

Get service details

Request example

Response

Create service

Request body

Request example

Response

Update service

Request body

Request example

Response

Delete service

Request example

Response

List service types

Request example

Response

Response example

List service plans

Request example

​List services

​Request example

​Response

​Response example

​Get service details

​Request example

​Response

​Create service

​Request body

​Request example

​Response

​Update service

​Request body

​Request example

​Response

​Delete service

​Request example

​Response

​List service types

​Request example

​Response

​Response example

​List service plans

​Request example

​Related resources

List services

Request example

Response

Response example

Get service details

Request example

Response

Create service

Request body

Request example

Response

Update service

Request body

Request example

Response

Delete service

Request example

Response

List service types

Request example

Response

Response example

List service plans

Request example

Related resources