Appwrite PostgreSQL API

openapi: 3.0.0
info:
  title: Appwrite Postgresql API
  description: Appwrite backend as a service cuts up to 70% of the time and costs required for building a modern application. We abstract and simplify common development tasks behind a REST APIs, to help you develop your app in a fast and secure way. For full API documentation and tutorials go to [https://appwrite.io/docs](https://appwrite.io/docs)
  version: 2.0.0
  termsOfService: https://appwrite.io/policy/terms
  contact:
    name: Appwrite Team
    url: https://appwrite.io/support
    email: team@appwrite.io
  license:
    name: BSD-3-Clause
    url: https://raw.githubusercontent.com/appwrite/appwrite/master/LICENSE
servers:
- url: https://cloud.appwrite.io/v1
  description: Appwrite Cloud endpoint.
- url: https://{region}.cloud.appwrite.io/v1
  description: Appwrite Cloud regional endpoint. Replace `{region}` with your project region.
  variables:
    region:
      default: fra
      description: Appwrite Cloud region.
tags:
- name: postgresql
  description: Appwrite postgresql service.
paths:
  /postgresql:
    get:
      summary: List databases
      operationId: postgresqlList
      tags:
      - postgresql
      description: List all dedicated databases. Results support pagination.
      responses:
        '200':
          description: Dedicated databases list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dedicatedDatabaseList'
      deprecated: false
      x-appwrite:
        group: postgresql
        demo: postgresql/list.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: queries
        description: Array of query strings.
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
        in: query
    post:
      summary: Create database
      operationId: postgresqlCreate
      tags:
      - postgresql
      description: Create a new dedicated database with the chosen engine and configuration. Status will be 'provisioning' until the database is ready.
      responses:
        '201':
          description: DedicatedDatabase
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dedicatedDatabase'
      deprecated: false
      x-appwrite:
        group: postgresql
        demo: postgresql/create.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                databaseId:
                  description: Database ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.
                  type: string
                  example: <DATABASE_ID>
                  x-appwrite:
                    idGenerator: ID.unique
                name:
                  description: 'Database display name. Max length: 128 chars.'
                  type: string
                  example: <NAME>
                version:
                  description: Database engine version. Defaults to latest for selected engine.
                  type: string
                  example: '17'
                  nullable: true
                specification:
                  description: Specification identifier. Drives the allocated CPU, memory, storage, storage class, and connection ceiling.
                  type: string
                  default: s-1vcpu-1gb
                  example: <SPECIFICATION>
                replicas:
                  description: Number of high availability replicas (0-5). High availability is enabled when greater than 0.
                  type: integer
                  default: 0
                  example: 0
                  format: int32
                syncMode:
                  description: 'Replication sync mode preference. Allowed values: async, sync, quorum.'
                  type: string
                  example: async
                  nullable: true
                networkIdleTimeoutSeconds:
                  description: Connection idle timeout in seconds.
                  type: integer
                  default: 900
                  example: 60
                  format: int32
                networkIPAllowlist:
                  description: IP addresses/CIDR ranges allowed to connect.
                  type: array
                  items:
                    type: string
                  nullable: true
                idleTimeoutMinutes:
                  description: Minutes of inactivity before container scales to zero.
                  type: integer
                  default: 15
                  example: 5
                  format: int32
                pitr:
                  description: Enable point-in-time recovery (PITR). Continuously archives changes so the database can be restored to any moment within the retention window.
                  type: boolean
                  default: true
                  example: false
                pitrRetentionDays:
                  description: Number of days to retain PITR data.
                  type: integer
                  default: 7
                  example: 1
                  format: int32
                storageAutoscaling:
                  description: Enable automatic storage expansion when usage exceeds threshold.
                  type: boolean
                  default: true
                  example: false
                storageAutoscalingThresholdPercent:
                  description: Storage usage percentage (50-95) that triggers automatic expansion.
                  type: integer
                  default: 85
                  example: 50
                  format: int32
                storageAutoscalingMaxGb:
                  description: Maximum storage size in GB for autoscaling. Defaults to 3 times the specification's storage. 0 means no limit.
                  type: integer
                  example: 0
                  format: int32
                  nullable: true
              required:
              - databaseId
              - name
  /postgresql/specifications:
    get:
      summary: List specifications
      operationId: postgresqlListSpecifications
      tags:
      - postgresql
      description: List the dedicated database specifications available on the current plan. Each specification reports its resource limits, its own prices and overage rates, and whether it is enabled for the organization.
      responses:
        '200':
          description: SpecificationList
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dedicatedDatabaseSpecificationList'
      deprecated: false
      x-appwrite:
        group: postgresql
        demo: postgresql/list-specifications.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
  /postgresql/{databaseId}:
    get:
      summary: Get database
      operationId: postgresqlGet
      tags:
      - postgresql
      description: Get a dedicated database by its unique ID. Returns the database configuration and current status.
      responses:
        '200':
          description: DedicatedDatabase
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dedicatedDatabase'
      deprecated: false
      x-appwrite:
        group: postgresql
        demo: postgresql/get.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
    patch:
      summary: Update database
      operationId: postgresqlUpdate
      tags:
      - postgresql
      description: Update a dedicated database configuration. All changes are applied with zero downtime. Specification changes (cpu, memory, storage) are handled via rolling cutover. Storage expansion is done online. All other settings are applied in-place.
      responses:
        '200':
          description: DedicatedDatabase
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dedicatedDatabase'
      deprecated: false
      x-appwrite:
        group: postgresql
        demo: postgresql/update.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Database display name.
                  type: string
                  example: <NAME>
                  nullable: true
                status:
                  description: 'Database status. Allowed values: ready, paused, inactive. Set to "paused" to pause, "ready" to resume (also recovers a failed database whose infrastructure is healthy), or "inactive" to spin down a shared-pool database.'
                  type: string
                  example: ready
                  nullable: true
                specification:
                  description: Specification. Changes cpu, memory, storage, connection ceiling, and node pool based on specification config. Resource changes are applied via rolling cutover with zero downtime.
                  type: string
                  example: <SPECIFICATION>
                  nullable: true
                replicas:
                  description: Number of high availability replicas (0-5). High availability is enabled when greater than 0.
                  type: integer
                  example: 0
                  format: int32
                  nullable: true
                syncMode:
                  description: 'Replication sync mode preference. Allowed values: async, sync, quorum.'
                  type: string
                  example: async
                  nullable: true
                networkIdleTimeoutSeconds:
                  description: Connection idle timeout in seconds (60-86400).
                  type: integer
                  example: 60
                  format: int32
                  nullable: true
                networkIPAllowlist:
                  description: IP addresses/CIDR ranges allowed to connect.
                  type: array
                  items:
                    type: string
                  nullable: true
                idleTimeoutMinutes:
                  description: Minutes before container scales to zero.
                  type: integer
                  example: 5
                  format: int32
                  nullable: true
                pitr:
                  description: Enable or disable point-in-time recovery (PITR).
                  type: boolean
                  example: false
                  nullable: true
                pitrRetentionDays:
                  description: Days to retain PITR data.
                  type: integer
                  example: 1
                  format: int32
                  nullable: true
                storageAutoscaling:
                  description: Enable automatic storage expansion when usage exceeds threshold.
                  type: boolean
                  example: false
                  nullable: true
                storageAutoscalingThresholdPercent:
                  description: Storage usage percentage (50-95) that triggers automatic expansion.
                  type: integer
                  example: 50
                  format: int32
                  nullable: true
                storageAutoscalingMaxGb:
                  description: Maximum storage size in GB for autoscaling. 0 means no limit.
                  type: integer
                  example: 0
                  format: int32
                  nullable: true
                metricsTraceSampleRate:
                  description: Fraction of queries to trace (0.0–1.0). Forwarded to the sidecar.
                  type: number
                  format: float
                  nullable: true
                metricsSlowQueryLogThresholdMs:
                  description: Threshold in ms above which queries are logged as slow. Forwarded to the sidecar.
                  type: integer
                  example: 0
                  format: int32
                  nullable: true
                sqlApiEnabled:
                  description: Enable the SQL API sidecar for this database.
                  type: boolean
                  example: false
                  nullable: true
                sqlApiAllowedStatements:
                  description: 'Statement types the SQL API accepts. Allowed values: SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, TRUNCATE, GRANT, REVOKE.'
                  type: array
                  items:
                    type: string
                  nullable: true
                sqlApiMaxRows:
                  description: Maximum rows returned per SQL API execution (1-1000000).
                  type: integer
                  example: 1
                  format: int32
                  nullable: true
                sqlApiMaxBytes:
                  description: Maximum serialised SQL API result payload in bytes (1024-104857600).
                  type: integer
                  example: 1024
                  format: int32
                  nullable: true
                sqlApiTimeoutSeconds:
                  description: Per-call SQL API execution timeout in seconds (1-300).
                  type: integer
                  example: 1
                  format: int32
                  nullable: true
    delete:
      summary: Delete database
      operationId: postgresqlDelete
      tags:
      - postgresql
      description: Delete a dedicated database. This action is irreversible. The database status will be set to 'deleting' and all resources will be cleaned up. Deletion is allowed from any state, and repeating the call re-dispatches the cleanup.
      responses:
        '204':
          description: No content
      deprecated: false
      x-appwrite:
        group: postgresql
        demo: postgresql/delete.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
  /postgresql/{databaseId}/backups:
    get:
      summary: List backups
      operationId: postgresqlListBackups
      tags:
      - postgresql
      description: List all backups for a dedicated database. Results can be filtered by status and type.
      responses:
        '200':
          description: BackupList
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dedicatedDatabaseBackupList'
      deprecated: false
      x-appwrite:
        group: backups
        demo: postgresql/list-backups.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
      - name: queries
        description: 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: status, type, databaseId'
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
        in: query
    post:
      summary: Create backup
      operationId: postgresqlCreateBackup
      tags:
      - postgresql
      description: Create a manual backup of a dedicated database. The backup will be created asynchronously and its status can be checked via the get backup endpoint.
      responses:
        '202':
          description: Backup
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dedicatedDatabaseBackup'
      deprecated: false
      x-appwrite:
        group: backups
        demo: postgresql/create-backup.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  description: 'Backup type: full or incremental.'
                  type: string
                  default: full
                  example: full
  /postgresql/{databaseId}/backups/policies:
    get:
      summary: List backup policies
      operationId: postgresqlListBackupPolicies
      tags:
      - postgresql
      description: List scheduled backup policies for a dedicated database.
      responses:
        '200':
          description: Backup policy list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/backupPolicyList'
      deprecated: false
      x-appwrite:
        group: policies
        demo: postgresql/list-backup-policies.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
      - name: queries
        description: Array of query strings generated using the Query class provided by the SDK.
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
        in: query
    post:
      summary: Create backup policy
      operationId: postgresqlCreateBackupPolicy
      tags:
      - postgresql
      description: Create a scheduled backup policy for a dedicated database.
      responses:
        '201':
          description: backup
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/backupPolicy'
      deprecated: false
      x-appwrite:
        group: policies
        demo: postgresql/create-backup-policy.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                policyId:
                  description: Policy ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.
                  type: string
                  example: <POLICY_ID>
                  x-appwrite:
                    idGenerator: ID.unique
                name:
                  description: 'Policy name. Max length: 128 chars.'
                  type: string
                  example: <NAME>
                schedule:
                  description: Schedule CRON syntax.
                  type: string
                retention:
                  description: Days to keep backups before deletion.
                  type: integer
                  example: 1
                  format: int32
                type:
                  description: 'Backup type: full or incremental.'
                  type: string
                  default: full
                  example: full
                enabled:
                  description: Is policy enabled? When disabled, no backups will be taken.
                  type: boolean
                  default: true
                  example: false
              required:
              - policyId
              - name
              - schedule
              - retention
  /postgresql/{databaseId}/backups/policies/{policyId}:
    get:
      summary: Get backup policy
      operationId: postgresqlGetBackupPolicy
      tags:
      - postgresql
      description: Get a scheduled backup policy for a dedicated database.
      responses:
        '200':
          description: backup
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/backupPolicy'
      deprecated: false
      x-appwrite:
        group: policies
        demo: postgresql/get-backup-policy.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
      - name: policyId
        description: Policy ID.
        required: true
        schema:
          type: string
          example: <POLICY_ID>
        in: path
    patch:
      summary: Update backup policy
      operationId: postgresqlUpdateBackupPolicy
      tags:
      - postgresql
      description: Update a scheduled backup policy for a dedicated database.
      responses:
        '200':
          description: backup
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/backupPolicy'
      deprecated: false
      x-appwrite:
        group: policies
        demo: postgresql/update-backup-policy.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
      - name: policyId
        description: Policy ID.
        required: true
        schema:
          type: string
          example: <POLICY_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: 'Policy name. Max length: 128 chars.'
                  type: string
                  example: <NAME>
                  nullable: true
                schedule:
                  description: Schedule CRON syntax.
                  type: string
                retention:
                  description: Days to keep backups before deletion.
                  type: integer
                  example: 1
                  format: int32
                  nullable: true
                enabled:
                  description: Is policy enabled? When disabled, no backups will be taken.
                  type: boolean
                  example: false
                  nullable: true
    delete:
      summary: Delete backup policy
      operationId: postgresqlDeleteBackupPolicy
      tags:
      - postgresql
      description: Delete a scheduled backup policy for a dedicated database. Backups already taken by the policy are kept until their retention expires.
      responses:
        '204':
          description: No content
      deprecated: false
      x-appwrite:
        group: policies
        demo: postgresql/delete-backup-policy.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
      - name: policyId
        description: Policy ID.
        required: true
        schema:
          type: string
          example: <POLICY_ID>
        in: path
  /postgresql/{databaseId}/backups/storage:
    put:
      summary: Update backup storage
      operationId: postgresqlUpdateBackupStorage
      tags:
      - postgresql
      description: Configure off-cluster backup storage for a dedicated database. Supports S3, GCS, and Azure Blob Storage destinations. Backups will be stored to the configured destination in addition to on-cluster storage.
      responses:
        '200':
          description: BackupStorageConfig
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dedicatedDatabaseBackupStorage'
      deprecated: false
      x-appwrite:
        group: backups
        demo: postgresql/update-backup-storage.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                provider:
                  description: 'Storage provider for off-cluster backups. Allowed values: s3 (Amazon S3 or S3-compatible), gcs (Google Cloud Storage), azure (Azure Blob Storage).'
                  type: string
                  example: s3
                bucket:
                  description: Storage bucket or container name.
                  type: string
                  example: <BUCKET>
                region:
                  description: Storage region.
                  type: string
                  default: ''
                  example: <REGION>
                prefix:
                  description: Object key prefix for backups.
                  type: string
                  default: backups/
                  example: <PREFIX>
                endpoint:
                  description: Custom endpoint for S3-compatible storage (e.g. MinIO).
                  type: string
                  default: ''
                  example: <ENDPOINT>
                accessKey:
                  description: Access key or client ID for authentication.
                  type: string
                  example: <ACCESS_KEY>
                secretKey:
                  description: Secret key or service account JSON for authentication.
                  type: string
                  example: <SECRET_KEY>
              required:
              - provider
              - bucket
              - accessKey
              - secretKey
  /postgresql/{databaseId}/backups/{backupId}:
    get:
      summary: Get backup
      operationId: postgresqlGetBackup
      tags:
      - postgresql
      description: Get details of a specific database backup including its status, size, and timestamps.
      responses:
        '200':
          description: Backup
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dedicatedDatabaseBackup'
      deprecated: false
      x-appwrite:
        group: backups
        demo: postgresql/get-backup.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
      - name: backupId
        description: Backup ID.
        required: true
        schema:
          type: string
          example: <BACKUP_ID>
        in: path
    delete:
      summary: Delete backup
      operationId: postgresqlDeleteBackup
  

# --- truncated at 32 KB (125 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/appwrite/refs/heads/main/openapi/appwrite-postgresql-api-openapi.yml