Skip to main content
POST
Create Database
The body is JSON, not multipart — unlike POST /v1/apps. The database is created empty by default; to create it from an existing snapshot, send snapshot_id.
string
required
The database display name. Maximum 50 characters.
string
A database description. Maximum 128 characters.
integer
The database engine: 1 (PostgreSQL), 2 (MongoDB), 3 (Redis) or 4 (MySQL).Required when snapshot_id is omitted. When snapshot_id is present, this field is optional; the engine comes from the snapshot resource_type. If provided, it must match or creation fails with SNAPSHOT_TYPE_MISMATCH.
string
The major version of the engine, for example "18" or "8.4". Defaults to the recommended version of the engine. Valid values per engine are returned by List Database Versions. A value outside that list fails with INVALID_DATABASE_VERSION. With snapshot_id, the database is born on the snapshot’s major version; version may be the same or newer, and an older one fails with SNAPSHOT_VERSION_NEWER.
integer
required
The amount of RAM to allocate to the database, in MB. Minimum 1,024 MB (512 MB for Redis, type: 3). Provisioned storage is 6 GB + 1 GB for every 512 MB of RAM (rounded up to a whole GB), or ram × 3 if that is larger (e.g. 1,024 MB → 8 GB; 2,048 MB → 10 GB; 4,096 MB → 14 GB).
string
The ID of the workspace to associate with the database, if applicable.
string
Creates the database from an existing database snapshot. The engine comes from the snapshot resource_type, and its volume is restored after provisioning. If restoration fails after the database is created, the new database is deleted instead of leaving an empty database that could be mistaken for the restored copy.

Response

object
Details of the created database.

Error Responses

string
The error code indicating the reason for failure. Possible values:
  • VALIDATION_ERROR: The body failed validation (400), including a missing type when snapshot_id is omitted.
  • USER_NOT_FOUND: The request is not authenticated (401).
  • PLAN_REQUIRED: The owner has no active plan, so a new database can’t be created (403).
  • MAX_DATABASES_REACHED: The plan’s database limit has been reached (403).
  • INVALID_RAM_LIMIT: ram is below the minimum for this database type — 1,024 MB, or 512 MB for Redis (400).
  • USER_LIMITS_NOT_FOUND: The owner’s limits could not be loaded (404).
  • MEMORY_LIMIT_EXCEEDED: The requested RAM exceeds the memory remaining on the plan (400).
  • SNAPSHOT_NOT_FOUND: The snapshot_id does not exist or does not belong to the caller (404).
  • SNAPSHOT_TYPE_MISMATCH: The snapshot is for an application, not a database, or the supplied type does not match its engine (400).
  • INVALID_DATABASE_VERSION: version is not available for this engine (400).
  • SNAPSHOT_VERSION_NEWER: version is older than the snapshot’s major version (400).
  • SNAPSHOT_TOO_LARGE: The snapshot exceeds the same size limit as database creation (400).
  • DB_CREATION_FAILED: The platform could not provision the database (500).
  • DATABASE_PERSISTENCE_FAILED: The database was created but could not be read back (500).
  • INTERNAL_SERVER_ERROR: An unexpected failure occurred (500).
string
A descriptive message with additional error details. Present for VALIDATION_ERROR and INVALID_RAM_LIMIT.
Last modified on November 1, 2026