Create database

Provision a managed database in a project and environment using a supported engine and plan.

POST /api/databases HTTPS

Request & response examples

Request example Server-side

curl --fail-with-body --request POST \
  'https://app.helicarrier.xyz/api/databases' \
  -H "Authorization: Bearer $HELI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "name": "postgres",
  "engine": "postgres",
  "projectSlug": "my-project",
  "environmentSlug": "staging",
  "planKey": "heli-db-s1"
}'

const response = await fetch(
  "https://app.helicarrier.xyz/api/databases",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.HELI_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "postgres",
      "engine": "postgres",
      "projectSlug": "my-project",
      "environmentSlug": "staging",
      "planKey": "heli-db-s1"
    })
  }
);
const data = await response.json();
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${data.error}`);
}
// Inspect data; avoid logging secret responses.

import os
import requests

response = requests.request(
    "POST",
    "https://app.helicarrier.xyz/api/databases",
    headers={
        "Authorization": f"Bearer {os.environ['HELI_API_KEY']}"
    },
    json={
      "name": "postgres",
      "engine": "postgres",
      "projectSlug": "my-project",
      "environmentSlug": "staging",
      "planKey": "heli-db-s1"
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
# Inspect data; avoid logging secret responses.

Response example 201

{
  "id": "svc_example",
  "name": "postgres",
  "slug": "my-app",
  "sourceType": "database",
  "status": "idle",
  "planKey": "heli-db-s1",
  "projectId": "prj_example",
  "environmentId": "env_example"
}

Illustrative values · selected fields

Response details ↓ OpenAPI ↗

Authorization

An account key with access, or a project key with project:write. A service key cannot perform this operation.

Authorization: Bearer <key> Key setup ↗

Request body application/json

name string required

Database name.

engine string required

Engine key (e.g. postgres, redis, mysql, mongo).

projectSlug string optional

Target project slug. Set this explicitly for automation; project keys require their own project. An account key that omits it uses the default project, if one exists.

environmentSlug string optional

Target environment slug (e.g. dev, staging, production). Optional for a normal key — the project's default environment is used. REQUIRED when your API key is restricted to specific environments; call whoami to see whether yours is.

planKey string optional

Plan key from list_plans (e.g. heli-db-s1). Prefer passing this explicitly so the database runs on the intended plan; if omitted, the cheapest plan matching the engine is applied.

Response 201

Creates a billed database service. Engine keys and plan keys should come from the engine and plan catalog endpoints. Set the target project and environment explicitly for automation.

Examples show selected response fields with illustrative values. Your response can contain additional fields.

id string

Unique identifier of this resource.

name string

Human-readable resource name.

slug string

URL-safe resource identifier.

sourceType string

Source used to build or run the service.

status string

Current state of the resource or operation.

planKey string

Plan identifier from the plan catalog.

projectId string

Project that owns the resource.

environmentId string

Environment that contains the service.

Errors

400

Invalid parameters. Check the required fields, types, and resource configuration.

401

The API key is missing, invalid, or revoked.

403

The caller or key scope does not permit this operation.

404

The resource does not exist or is not visible to this caller.

Error handling and safe retries

ALSO AVAILABLE VIA MCP

`create_database`

Required MCP arguments: name, engine. Send path, query, and body fields together as tool arguments.

Connect your agent ↗