Aiven API

The Aiven API provides programmatic access to the Aiven platform, allowing you to automate service management, integrate with existing systems, and build custom workflows.

Use cases

The Aiven API is ideal for:

CI/CD integration

Create test services during CI runs and tear them down automatically

Custom automation

Build custom tools and scripts for your specific workflows

Scheduled operations

Deploy and manage development or demo environments on a schedule

Dynamic scaling

Scale disk space based on metrics or events

Getting started

Create an authentication token

Generate a personal token from the Aiven Console:

Click your user icon and select Tokens
Click Generate token
Provide a description and click Generate
Copy the token immediately (it won’t be shown again)

Try the API with Postman

Use the Aiven Postman workspace to explore the API:

Fork the Postman collection and environment
Add your token to the authToken variable in the environment
Send requests to explore the API

Make your first API call

Test authentication by listing your projects:

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

Authentication

All API requests require authentication using a bearer token in the Authorization header:

Authorization: aivenv1 YOUR_TOKEN

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

Common API operations

List projects

Retrieve all projects you have access to:

Request
Response

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

{
  "projects": [
    {
      "project_name": "my-project",
      "account_id": "a225dad8d3c4",
      "account_name": "My Account",
      "billing_currency": "USD",
      "default_cloud": "google-europe-north1",
      "estimated_balance": "4.11",
      "payment_method": "card"
    }
  ]
}

List cloud regions

Get available cloud regions (no authentication required):

Request
Response

curl https://api.aiven.io/v1/clouds

{
  "clouds": [
    {
      "cloud_description": "Africa, South Africa - Amazon Web Services: Cape Town",
      "cloud_name": "aws-af-south-1",
      "geo_latitude": -33.92,
      "geo_longitude": 18.42,
      "geo_region": "africa"
    },
    {
      "cloud_description": "Europe, Finland - Google Cloud: Finland",
      "cloud_name": "google-europe-north1",
      "geo_latitude": 60.17,
      "geo_longitude": 24.94,
      "geo_region": "europe"
    }
  ]
}

Create a service

Create a new PostgreSQL service:

Request
Response

curl -X POST \
  -H "Authorization: aivenv1 YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cloud": "google-europe-north1",
    "plan": "startup-4",
    "service_name": "my-postgres",
    "service_type": "pg"
  }' \
  https://api.aiven.io/v1/project/PROJECT_NAME/service

{
  "service": {
    "service_name": "my-postgres",
    "service_type": "pg",
    "state": "REBUILDING",
    "cloud_name": "google-europe-north1",
    "plan": "startup-4",
    "service_uri": "postgres://...",
    "create_time": "2024-03-04T12:00:00Z"
  }
}

Get service details

Retrieve information about a specific service:

Request
Response

curl -H "Authorization: aivenv1 YOUR_TOKEN" \
  https://api.aiven.io/v1/project/PROJECT_NAME/service/SERVICE_NAME

{
  "service": {
    "service_name": "my-postgres",
    "service_type": "pg",
    "state": "RUNNING",
    "cloud_name": "google-europe-north1",
    "plan": "startup-4",
    "service_uri": "postgres://user:pass@host:port/db",
    "connection_info": {
      "pg": [
        {
          "host": "my-postgres-project.aivencloud.com",
          "port": 12345,
          "dbname": "defaultdb",
          "user": "avnadmin"
        }
      ]
    }
  }
}

Update a service

Modify service configuration (e.g., scale to a different plan):

Request
Response

curl -X PUT \
  -H "Authorization: aivenv1 YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "business-4"
  }' \
  https://api.aiven.io/v1/project/PROJECT_NAME/service/SERVICE_NAME

{
  "service": {
    "service_name": "my-postgres",
    "plan": "business-4",
    "state": "REBALANCING"
  }
}

Delete a service

Permanently delete a service:

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

curl -X DELETE \
  -H "Authorization: aivenv1 YOUR_TOKEN" \
  https://api.aiven.io/v1/project/PROJECT_NAME/service/SERVICE_NAME

API resources

Projects

/v1/project

GET

List all projects

/v1/project/{project}

GET

Get project details

Services

/v1/project/{project}/service

GET

List services in a project

/v1/project/{project}/service

POST

Create a new service

/v1/project/{project}/service/{service}

GET

Get service details

/v1/project/{project}/service/{service}

PUT

Update service configuration

/v1/project/{project}/service/{service}

DELETE

Delete a service

Service-specific operations

/v1/project/{project}/service/{service}/database

GET/POST

Manage databases (PostgreSQL, MySQL)

/v1/project/{project}/service/{service}/user

GET/POST

Manage service users

/v1/project/{project}/service/{service}/topic

GET/POST

Manage Kafka topics

/v1/project/{project}/service/{service}/acl

GET/POST

Manage Kafka ACLs

Rate limiting

The Aiven API implements rate limiting to ensure fair usage:

Rate limits: Vary by endpoint and authentication method
Headers: Check X-RateLimit-* headers in responses
Best practices: Implement exponential backoff for retries

Error handling

The API returns standard HTTP status codes:

200

Success

Request completed successfully

400

Bad Request

Invalid request parameters

401

Unauthorized

Invalid or missing authentication token

403

Forbidden

Insufficient permissions

404

Not Found

Resource not found

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Server error - retry with exponential backoff

Error responses include details:

{
  "errors": [
    {
      "message": "Service 'non-existent' does not exist",
      "status": 404
    }
  ]
}

Best practices

Token security

Store tokens in environment variables or secret managers
Never commit tokens to version control
Rotate tokens regularly
Use separate tokens for different applications

Error handling

Implement retry logic with exponential backoff
Handle rate limiting gracefully
Log errors for debugging
Validate responses before processing

Performance

Cache responses when appropriate
Use pagination for large result sets
Batch operations when possible
Monitor API usage and limits

SDKs and libraries

While the API is RESTful and language-agnostic, several community libraries are available:

Python: aiven-client (official CLI includes Python library)
Go: aiven-go-client
Terraform: Aiven Terraform Provider
Kubernetes: Aiven Operator

Get Started

Platform

Services

Developer Tools

Integrations

Use cases

CI/CD integration

Custom automation

Scheduled operations

Dynamic scaling

Getting started

Authentication

Common API operations

List projects

List cloud regions

Create a service

Get service details

Update a service

Delete a service

API resources

Projects

Services

Service-specific operations

Rate limiting

Error handling

Best practices

SDKs and libraries

Build docs developers (and LLMs) love

Get Started

Platform

Services

Developer Tools

Integrations

​Use cases

CI/CD integration

Custom automation

Scheduled operations

Dynamic scaling

​Getting started

​Authentication

​Common API operations

​List projects

​List cloud regions

​Create a service

​Get service details

​Update a service

​Delete a service

​API resources

​Projects

​Services

​Service-specific operations

​Rate limiting

​Error handling

​Best practices

​SDKs and libraries

​Related resources

Build docs developers (and LLMs) love

Use cases

Getting started

Authentication

Common API operations

List projects

List cloud regions

Create a service

Get service details

Update a service

Delete a service

API resources

Projects

Services

Service-specific operations

Rate limiting

Error handling

Best practices

SDKs and libraries

Related resources