> ## Documentation Index
> Fetch the complete documentation index at: https://docs.camposcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# /v1/databases/create

> This endpoint creates a MySQL, PostgreSQL, MongoDB or Redis database.

> [!WARNING]
>
> This endpoint has a rate limit of 1 request every 3 seconds, shared with the other endpoints that change databases (create, update, update credentials and delete).

> [!NOTE]
>
> The password of a database is never returned by the API. Store it when you create the database or change its password.

## Connecting

Use `connection.host` and `connection.port` from the response of `GET /v1/databases/{databaseId}` once the status is `active`:

| Type | Connection string |
| - | - |
| `postgresql` | `postgresql://<username>:<password>@<host>:<port>/<database>` |
| `mysql` | `mysql://<username>:<password>@<host>:<port>/<database>` |
| `mongodb` | `mongodb://<username>:<password>@<host>:<port>/?authSource=admin` |
| `redis` | `redis://default:<password>@<host>:<port>` |


## OpenAPI

````yaml POST /v1/databases/create
openapi: 3.1.0
info:
  title: CamposCloud API Documentation
  description: >-
    This documentation provides an overview of the CamposCloud API, including
    authentication, endpoints, and data structures. It is designed to help
    developers integrate with the CamposCloud platform effectively.
  version: 1.0.0
servers:
  - url: https://api.camposcloud.com
security:
  - bearerAuth: []
paths:
  /v1/databases/create:
    post:
      tags:
        - Databases
      description: >-
        Creates a database. The account (or the owner of the team) must have an
        active plan with enough free memory. The database is returned
        immediately with the status `creating` and `connection.port: null`; it
        becomes `active` shortly after, so poll `GET /v1/databases/{databaseId}`
        until then.


        Fields that are not listed below are refused with `400`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDatabase'
      responses:
        '200':
          description: The database that is being created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
        '400':
          description: >-
            The body is invalid, the password is too weak, the memory is below
            the minimum, or the plan does not have enough free memory.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: password too weak. use a stronger password
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            No active plan, or you are not allowed to create databases in the
            team (`canCreateDatabase`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: User does not have an active plan.
        '404':
          description: Team not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Team not found for the provided ID.
        '429':
          description: >-
            A rate limit was exceeded. Creating, updating, changing the password
            of and deleting databases share a limit of 1 request every 3
            seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Database change limit reached, please try again later
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          description: No server is available to host the database right now.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: >-
                  No available worker found to deploy the application. Please
                  try again later.
components:
  schemas:
    CreateDatabase:
      type: object
      required:
        - name
        - type
        - memoryMB
        - password
      properties:
        name:
          type: string
          minLength: 3
          maxLength: 50
          pattern: ^[A-Za-z0-9][A-Za-z0-9 _.-]*$
          description: >-
            Display name: letters, numbers, spaces, `_`, `.` and `-`, starting
            with a letter or number, without leading or trailing spaces.
          example: main-db
        type:
          type: string
          enum:
            - mysql
            - postgresql
            - mongodb
            - redis
          example: postgresql
        memoryMB:
          type: integer
          minimum: 1
          description: >-
            Memory in MB. Must be a JSON number (not a string), at least the
            minimum allowed for databases (512 MB by default) and must fit in
            the memory left in the plan.
          example: 512
        team:
          type: string
          pattern: ^[a-f0-9]{24}$
          description: >-
            ID of the team to create the database in. Requires the
            `canCreateDatabase` permission. The memory is taken from the plan of
            the team owner. Omit to create a personal database.
        username:
          type: string
          pattern: ^[A-Za-z][A-Za-z0-9_]{2,31}$
          description: >-
            User that your applications will connect with. **Required for
            `mysql`, `postgresql` and `mongodb`, not allowed for `redis`.** 3 to
            32 letters, numbers or `_`, starting with a letter. Reserved names
            such as `root`, `admin`, `postgres` and `mysql` are refused.
          example: app_user
        password:
          $ref: '#/components/schemas/DatabasePassword'
        database:
          type: string
          pattern: ^[A-Za-z][A-Za-z0-9_]{0,62}$
          description: >-
            Name of the initial database. **Required for `mysql` and
            `postgresql`, not allowed for `mongodb` and `redis`.** Up to 63
            letters, numbers or `_`, starting with a letter. Reserved names such
            as `mysql`, `postgres`, `information_schema` and `admin` are
            refused.
          example: app_db
    Database:
      type: object
      properties:
        _id:
          type: string
          description: ID of the database.
          example: 64b7f0c2a1b2c3d4e5f60718
        name:
          type: string
          description: Display name.
          example: main-db
        type:
          type: string
          enum:
            - mysql
            - postgresql
            - mongodb
            - redis
          example: postgresql
        status:
          type: string
          enum:
            - creating
            - active
            - rebuilding
            - error
          description: >-
            `creating` right after creation, `active` when ready, `rebuilding`
            while the container is rebuilt, `error` when the last rebuild
            failed.
          example: active
        restartRequired:
          type: boolean
          description: >-
            Whether a change (memory, or the password of a Redis database) is
            waiting for the next start, stop or restart to be applied.
          example: false
        userId:
          type:
            - string
            - 'null'
          description: ID of the account that owns the database.
          example: 64b7f0c2a1b2c3d4e5f60700
        teamId:
          description: >-
            Team of the database: `null` for personal databases, otherwise the
            team ID or an object with the ID and name of the team.
          oneOf:
            - type: 'null'
            - type: string
            - type: object
              properties:
                _id:
                  type: string
                name:
                  type: string
          example: null
        workerNodeId:
          description: >-
            Server that runs the database: its ID, or an object with the ID and
            name.
          oneOf:
            - type: 'null'
            - type: string
            - type: object
              properties:
                _id:
                  type: string
                nodeName:
                  type: string
          example:
            _id: 64b7f0c2a1b2c3d4e5f60799
            nodeName: node-1
        allocatedMemoryMB:
          type: integer
          description: >-
            Memory reserved for the database, in MB. It counts towards the
            memory of the plan.
          example: 512
        allocatedVCpu:
          type: number
          description: vCPUs available to the database.
          example: 1
        diskLimitBytes:
          type: integer
          description: Disk limit in bytes.
          example: 10737418240
        diskUsageBytes:
          type:
            - integer
            - 'null'
          description: Latest measured disk usage in bytes. `null` when not measured yet.
          example: 52428800
        containerImage:
          type: string
          description: Image and version of the database engine.
          example: postgres:trixie
        connection:
          $ref: '#/components/schemas/DatabaseConnection'
        currentResourceMetrics:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/ResourceMetrics'
          description: Latest metrics. `null` when none were collected yet.
        createdAt:
          type: string
          format: date-time
          example: '2025-01-01T12:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          example: '2025-01-01T12:00:00.000Z'
    Error:
      type: object
      description: >-
        Every error returned by the API has this shape. The message can be in
        English or in Portuguese depending on the endpoint.
      required:
        - error
      properties:
        error:
          type: string
          description: Human readable description of the error.
          example: Application not found.
    DatabasePassword:
      type: string
      minLength: 12
      maxLength: 72
      pattern: ^[A-Za-z0-9][A-Za-z0-9_.@%+=-]*$
      description: >-
        Password of the database. 12 to 72 characters, only letters, numbers and
        `_ . @ % + = -`, starting with a letter or number. It must also be
        strong enough (zxcvbn score 3 or higher), otherwise the request is
        refused with `password too weak. use a stronger password`.
      example: Tr0ub4dor.Zebra-Lamp=91
    DatabaseConnection:
      type: object
      description: >-
        How to connect to the database. **The password is never returned by the
        API**: it is chosen when the database is created and can only be
        replaced, not read.
      properties:
        host:
          type: string
          description: Host name to connect to.
          example: db.camposcloud.com
        port:
          type:
            - integer
            - 'null'
          description: >-
            Port to connect to. `null` while the database is still being
            created.
          example: 30001
        username:
          type:
            - string
            - 'null'
          description: User name. `null` for Redis.
          example: app_user
        database:
          type:
            - string
            - 'null'
          description: Name of the initial database. Only for MySQL and PostgreSQL.
          example: app_db
    ResourceMetrics:
      type: object
      description: >-
        Latest resource metrics collected for the application. All counters are
        `0` while the application is offline.
      properties:
        timestamp:
          type:
            - string
            - 'null'
          format: date-time
          description: When the metrics were collected.
          example: '2025-01-01T12:00:00.000Z'
        online:
          type: boolean
          description: Whether the application is currently running.
          example: true
        uptime:
          type: integer
          description: Uptime in seconds.
          example: 35980
        startedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: When the application was started. `null` while it is offline.
          example: '2025-01-01T12:00:00.000Z'
        cpuUsagePercent:
          type: number
          description: CPU usage in percent.
          example: 0.42
        memoryUsageBytes:
          type: integer
          description: Memory in use, in bytes.
          example: 43671552
        memoryLimitBytes:
          type: integer
          description: Memory limit, in bytes.
          example: 268435456
        networkRxBytes:
          type: integer
          description: Bytes received over the network.
          example: 228961
        networkTxBytes:
          type: integer
          description: Bytes sent over the network.
          example: 228190
  responses:
    Unauthorized:
      description: >-
        The `Authorization` header is missing or malformed, or the API token is
        invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Invalid developer token
    InternalError:
      description: >-
        Unexpected error. On endpoints that do not document a `400` for it, this
        is also returned when an ID in the URL is not a valid identifier.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Internal server error. Please try again later.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your CamposCloud API token, sent as `Authorization: Bearer <token>`.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.