API docs by Redocly

DBtune Cloud API (0.1.0)

Download OpenAPI specification:

This is the internal REST API spec. Most endpoints here will require JWT authentication, in contrast with public API where it will be API key based.

JWT auth

Obtain JWT token.

Create a new JWT token (access/refresh) for a user. The token that is returned then should be used in the Authorization header (HTTP_AUTHORIZATION) for all subsequent requests.

Request Body schema: application/json
required
email
string
password
string

Responses

Request samples

Content type
application/json
{
  • "email": "user@company.com",
  • "password": "YourPassword"
}

Response samples

Content type
application/json
{
  • "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  • "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Refresh JWT access token.

More info can be found here.

Request Body schema: application/json
required
refresh
string

Responses

Request samples

Content type
application/json
{
  • "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...."
}

Response samples

Content type
application/json
{
  • "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Blacklisting specific JWT access tokens.

This is really useful when you want to invalidate a specific token or avoid misuse of a token. More info can be found here.

Request Body schema: application/json
required
refresh
string

Responses

Request samples

Content type
application/json
{
  • "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...."
}

User

Get user details.

Get user details.

The user model might change over time, so it is recommended to always check the backend model/serializer.

Authorizations:
JWTAuth

Responses

Response samples

Content type
application/json
{
  • "email": "user@company.com",
  • "first_name": "John",
  • "company_name": "DBtune",
  • "metadata": {
    },
  • "is_verified": true
}

Sign up user.

Responses

Response samples

Content type
application/json
{
  • "email": "user@company.com",
  • "password": "super_secret_password",
  • "first_name": "John",
  • "company_name": "DBtune",
  • "metadata": {
    }
}

Renew API token.

Authorizations:
JWTAuth

Responses

Response samples

Content type
application/json
{
  • "api_key": "1E23-4F56-7H89..."
}

Verify email.

Verify email by hitting the endpoint.

Request Body schema: application/json
required
code
string

Responses

Request samples

Content type
application/json
{
  • "code": "550e8400-e29b-41d4-a716-446655440000"
}

Resend verify email.

Resends verification code to the user's email.

Authorizations:
JWTAuth

Responses

Password reset email.

Send the password reset email to the user.

Request Body schema: application/json
required
email
string

Responses

Request samples

Content type
application/json
{
  • "email": "user@company.com"
}

Reset password.

Update the password by providing the new one.

Request Body schema: application/json
required
token
string
password
string

Responses

Request samples

Content type
application/json
{
  • "token": "c8z9n5-e7a5eb3ea6db58fc1ea9fda98b50a06c",
  • "password": "super_secret_updated_password"
}

Health check

Ping the server.

This endpoint is used to check if the server is up and running.

Responses

Database Operations

Send a heartbeat back to the server.

Authorizations:
APIKeyAuth
path Parameters
uuid
required
string <uuid>
Example: 3071dd11-91e6-4351-b445-81a6f121d6ee

The UUID of the database instance

Request Body schema: application/json
required
agent_start_time
number

Agent start time (unix timestamp UTC)

agent_version
string

Responses

Request samples

Content type
application/json
{
  • "agent_start_time": 1719243555,
  • "agent_version": "1.0.0"
}

Fetch all database instances.

Authorizations:
APIKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create database instance.

Authorizations:
APIKeyAuth
Request Body schema: application/json
required
name
string

The name of the database instance.

restart_policy
boolean

Defines whether the instance should have an automatic restart policy.

db_engine
string
Enum: "postgresql" "aurora_postgresql" "aurora_mysql" "mysql" "oracle" "sap_hana" "rds_postgresql"

The database engine to be used.

cloud_provider
string
Enum: "AWS" "Google" "Azure" "Aiven"

The cloud provider where the instance is hosted.

hosting
string
Enum: "managed" "on_prem"

The hosting environment for the instance.

db_flavour
string
Value: "epas"

Specifies the specific 'flavour' of the db_engine.

Responses

Request samples

Content type
application/json
{
  • "name": "Example Database Instance",
  • "restart_policy": false,
  • "db_engine": "postgresql",
  • "cloud_provider": "AWS",
  • "hosting": "on_prem",
  • "db_flavour": "epas"
}

Response samples

Content type
application/json
{
  • "uuid": "3071dd11-91e6-4351-b445-81a6f121d6ee",
  • "name": "Example Database Instance",
  • "hosting": "on_prem",
  • "db_engine": "postgresql",
  • "tuning_target": "transactions_per_second",
  • "cloud_provider": "AWS",
  • "agent_last_update": null,
  • "agent_start_time": null,
  • "agent_version": null,
  • "restart_policy": false,
  • "parameter_space": null,
  • "optimiser_config": null,
  • "iteration_duration": 5,
  • "number_of_iterations": 32,
  • "max_query_runtime_multiplier": 2,
  • "is_deleted": false,
  • "is_agent_alive": true,
  • "created_at": "2024-06-28T11:19:55.802847Z",
  • "updated_at": "2024-06-28T11:19:55.802847Z"
}

Fetch database instance.

Authorizations:
APIKeyAuth
path Parameters
uuid
required
string <uuid>
Example: 3071dd11-91e6-4351-b445-81a6f121d6ee

The UUID of the database instance

Responses

Response samples

Content type
application/json
{
  • "uuid": "3071dd11-91e6-4351-b445-81a6f121d6ee",
  • "name": "Example Database Instance",
  • "hosting": "on_prem",
  • "db_engine": "postgresql",
  • "tuning_target": "transactions_per_second",
  • "cloud_provider": "AWS",
  • "agent_last_update": null,
  • "agent_start_time": null,
  • "agent_version": null,
  • "restart_policy": false,
  • "parameter_space": null,
  • "optimiser_config": null,
  • "iteration_duration": 5,
  • "number_of_iterations": 32,
  • "max_query_runtime_multiplier": 2,
  • "is_deleted": false,
  • "is_agent_alive": true,
  • "created_at": "2024-06-28T11:19:55.802847Z",
  • "updated_at": "2024-06-28T11:19:55.802847Z"
}

Modify database instance.

Authorizations:
APIKeyAuth
path Parameters
uuid
required
string <uuid>
Example: 3071dd11-91e6-4351-b445-81a6f121d6ee

The UUID of the database instance

Request Body schema: application/json
required
name
string

The name of the database instance.

restart_policy
boolean

Defines whether the instance should have an automatic restart policy.

parameter_space
object

Parameter space to override the default parameter space.

optimiser_config
object

Defines whether the instance should have an automatic restart policy.

tuning_target
string
Enum: "average_query_runtime" "transactions_per_second"

The tuning target for the instance.

Responses

Request samples

Content type
application/json
{
  • "name": "Example Database Instance",
  • "restart_policy": true,
  • "parameter_space": { },
  • "optimiser_config": { },
  • "tuning_target": "average_query_runtime"
}

Response samples

Content type
application/json
{
  • "uuid": "3071dd11-91e6-4351-b445-81a6f121d6ee",
  • "name": "Example Database Instance",
  • "hosting": "on_prem",
  • "db_engine": "postgresql",
  • "tuning_target": "transactions_per_second",
  • "cloud_provider": "AWS",
  • "agent_last_update": null,
  • "agent_start_time": null,
  • "agent_version": null,
  • "restart_policy": false,
  • "parameter_space": null,
  • "optimiser_config": null,
  • "iteration_duration": 5,
  • "number_of_iterations": 32,
  • "max_query_runtime_multiplier": 2,
  • "is_deleted": false,
  • "is_agent_alive": true,
  • "created_at": "2024-06-28T11:19:55.802847Z",
  • "updated_at": "2024-06-28T11:19:55.802847Z"
}

Send system information back to the server.

Authorizations:
APIKeyAuth
path Parameters
uuid
required
string <uuid>
Example: 3071dd11-91e6-4351-b445-81a6f121d6ee

The UUID of the database instance

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "system_info": {
    }
}

Response samples

Content type
application/json
{
  • "message": "System info is changed"
}

Fetch metrics data for the selected database.

Authorizations:
APIKeyAuth
path Parameters
uuid
required
string <uuid>
Example: 3071dd11-91e6-4351-b445-81a6f121d6ee

The UUID of the database instance

Request Body schema: application/json
required
timestamp_from
required
string
timestamp_to
string

Responses

Request samples

Content type
application/json
{
  • "timestamp_from": "2023-06-26 17:02:51.302514+00",
  • "timestamp_to": "2100-06-26 17:02:51.302514+00"
}

Response samples

Content type
application/json
[
  • {
    }
]

Get a specific metric for the selected database.

Authorizations:
APIKeyAuth
path Parameters
uuid
required
string <uuid>
Example: 3071dd11-91e6-4351-b445-81a6f121d6ee

The UUID of the database instance

metric
required
string

The specific metric to retrieve (e.g. node_cpu_usage, perf_transactions_per_second)

Request Body schema: application/json
required
timestamp_from
string
timestamp_to
string

Responses

Request samples

Content type
application/json
{
  • "timestamp_from": "2023-06-26 17:02:51.302514+00",
  • "timestamp_to": "2100-06-26 17:02:51.302514+00"
}

Response samples

Content type
application/json
{
  • "type": "int",
  • "values": [
    ],
  • "timestamps": [
    ]
}

Post metrics data for the selected database to the server.

Authorizations:
APIKeyAuth
path Parameters
uuid
required
string <uuid>
Example: 3071dd11-91e6-4351-b445-81a6f121d6ee

The UUID of the database instance

Request Body schema: application/json
required
required
object (NormalisedMetricsObject)
timestamp
required
string <date-time>

When the metrics were collected

Responses

Request samples

Content type
application/json
{
  • "metrics": {
    },
  • "timestamp": "2019-08-24T14:15:22Z"
}

Get all configurations for the selected database.

Authorizations:
APIKeyAuth
path Parameters
uuid
required
string <uuid>
Example: 3071dd11-91e6-4351-b445-81a6f121d6ee

The UUID of the database instance

query Parameters
status
string
Enum: "active" "inactive" "recommended" "failed" "rejected"
Example: status=active

Filter configurations by status. Use 'recommended' to get only recommended configurations.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Post configurations for the selected database to the server.

Authorizations:
APIKeyAuth
path Parameters
uuid
required
string <uuid>
Example: 3071dd11-91e6-4351-b445-81a6f121d6ee

The UUID of the database instance

Request Body schema: application/json
required
Array
name
string
unit
string or null
context
string
setting
string
vartype
string

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get a specific configuration for the selected database.

Authorizations:
APIKeyAuth
path Parameters
uuid
required
string <uuid>
Example: 3071dd11-91e6-4351-b445-81a6f121d6ee

The UUID of the database instance

config_id
required
integer
Example: 1

The ID of the specific configuration to retrieve

Responses

Response samples

Content type
application/json
{
  • "config": [
    ],
  • "id": 1,
  • "status": "active",
  • "changed_at": "2024-06-28T11:19:55.802847Z",
  • "created_at": "2024-06-28T11:19:55.802847Z",
  • "applied_at": "2024-06-28T11:19:55.802847Z",
  • "knob_application": "reload",
  • "knobs_overrides": [
    ],
  • "performance": {
    },
  • "config_validity": "valid"
}

Get all configurations for the selected tuning_session_id.

Authorizations:
APIKeyAuth
path Parameters
uuid
required
string <uuid>
Example: 3071dd11-91e6-4351-b445-81a6f121d6ee

The UUID of the database instance

tuning_session_id
required
string

The ID of the specific tuning session to retrieve

query Parameters
status
string
Enum: "active" "inactive" "recommended" "failed" "rejected"
Example: status=active

Filter configurations by status. Use 'recommended' to get only recommended configurations.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get summaries of configurations for the selected database.

Authorizations:
APIKeyAuth
path Parameters
uuid
required
string <uuid>
Example: 3071dd11-91e6-4351-b445-81a6f121d6ee

The UUID of the database instance

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get all log events for the selected database.

Authorizations:
APIKeyAuth
path Parameters
uuid
required
string <uuid>
Example: 3071dd11-91e6-4351-b445-81a6f121d6ee

The UUID of the database instance

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Apply a specific configuration to the database.

Create a new recommended configuration based on a specific configuration. This will only work if there is no active tuning session for the database.

Authorizations:
APIKeyAuth
path Parameters
uuid
required
string <uuid>
Example: 3071dd11-91e6-4351-b445-81a6f121d6ee

The UUID of the database instance

config_id
required
integer
Example: 1

The ID of the configuration to apply

Responses

Response samples

Content type
application/json
{
  • "message": "Recommended configuration created successfully. 123"
}

Tuning

Start or stop a tuning session for the selected database.

Authorizations:
APIKeyAuth
path Parameters
uuid
required
string <uuid>
Example: 3071dd11-91e6-4351-b445-81a6f121d6ee

The UUID of the database instance

Request Body schema: application/json
required
operation
string
Enum: "start" "stop"

The operation to perform on the tuning session.

Responses

Request samples

Content type
application/json
{
  • "operation": "start"
}

Response samples

Content type
application/json
{
  • "message": "Tuning session started."
}

Get all tuning sessions for the selected database.

Authorizations:
APIKeyAuth
path Parameters
uuid
required
string <uuid>
Example: 3071dd11-91e6-4351-b445-81a6f121d6ee

The UUID of the database instance

query Parameters
status
string
Enum: "active" "finished" "failed" "cancelled"
Example: status=active

Filter tuning sessions by status. Use 'active' to get only active tuning sessions.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Handle guardrail request from agent

Handles a guardrail request from the agent. The agent can request either a critical action (revert to baseline) or a non-critical action (recommend new configuration) based on the system's performance.

Authorizations:
APIKeyAuth
path Parameters
uuid
required
string

The UUID of the database instance

Request Body schema: application/json
required
level
required
string
Enum: "critical" "non-critical"

The severity level of the guardrail request

Responses

Request samples

Content type
application/json
{
  • "level": "critical"
}

Notifications

Get all notifications for the current user.

Authorizations:
JWTAuth
query Parameters
read_status
string
Enum: "read" "unread"

Filter notifications by read status

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Mark all notifications as read.

Authorizations:
JWTAuth

Responses

Response samples

Content type
application/json
{
  • "detail": "5 notifications updated successfully."
}

Update a specific notification.

Authorizations:
JWTAuth
path Parameters
pk
required
integer
Example: 1

The ID of the notification to update

Request Body schema: application/json
required
read_at
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "read_at": "2024-06-28T11:19:55.802847Z"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "message": "New configuration available",
  • "type": "warning",
  • "notification_targets": [
    ],
  • "count": 1,
  • "context": {
    },
  • "log_code": "T001",
  • "db_instance": "3071dd11-91e6-4351-b445-81a6f121d6ee",
  • "user_id": "3071dd11-91e6-4351-b445-81a6f121d6ee",
  • "read_at": "2024-06-28T11:19:55.802847Z",
  • "created_at": "2024-06-28T11:19:55.802847Z",
  • "updated_at": "2024-06-28T11:19:55.802847Z"
}