> ## 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

> This endpoint lists the databases of the account or of a team.

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


## OpenAPI

````yaml GET /v1/databases
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:
    get:
      tags:
        - Databases
      description: >-
        Lists databases. Without `team` only the personal databases of the
        account are returned; with `team` the databases of that team are
        returned (you must be the owner or a member of the team). Passwords are
        never part of the response.
      parameters:
        - name: page
          in: query
          description: Page number, starting at 1.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Databases per page.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: team
          in: query
          description: >-
            ID of a team. Lists the databases of that team instead of the
            personal ones.
          schema:
            type: string
            pattern: ^[a-f0-9]{24}$
      responses:
        '200':
          description: A page of databases.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatabaseList'
        '400':
          description: A query parameter is invalid or unknown.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: '"limit" must be less than or equal to 100'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: You are not a member of the team.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: You do not have permission to access this team.
        '404':
          description: Team not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Team not found.
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    DatabaseList:
      type: object
      properties:
        databases:
          type: array
          items:
            $ref: '#/components/schemas/Database'
        totalUsedRAM:
          type: number
          description: >-
            Memory in MB allocated by all applications and databases of the
            account (or of the team owner when `team` is used).
          example: 1536
        pagination:
          $ref: '#/components/schemas/Pagination'
    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.
    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'
    Pagination:
      type: object
      properties:
        totalItems:
          type: integer
          description: Total number of applications matching the query.
          example: 12
        totalPages:
          type: integer
          description: Total number of pages (at least 1).
          example: 2
        currentPage:
          type: integer
          description: The page that was returned.
          example: 1
        itemsPerPage:
          type: integer
          description: The `limit` that was applied.
          example: 10
        hasNextPage:
          type: boolean
          description: Whether there is a next page.
          example: true
        hasPrevPage:
          type: boolean
          description: Whether there is a previous page.
          example: false
    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
    TooManyRequests:
      description: >-
        A rate limit was exceeded. See the `RateLimit-*` and `Retry-After`
        response headers.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Too many requests, please try again later
    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.