Appwrite Domains API

openapi: 3.0.0
info:
  title: Appwrite Domains 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: domains
  description: Appwrite domains service.
paths:
  /domains:
    get:
      summary: List domains
      operationId: domainsList
      tags:
      - domains
      description: List all domains registered for this project. This endpoint supports pagination.
      responses:
        '200':
          description: Domains list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domainsList'
      deprecated: false
      x-appwrite:
        group: null
        demo: domains/list.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: domains.read
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: queries
        description: Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/databases#querying-documents). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on attributes such as domain name, teamInternalId, expiration, etc.
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
        in: query
      - name: search
        description: 'Search term to filter your list results. Max length: 256 chars.'
        required: false
        schema:
          type: string
          example: <SEARCH>
          default: ''
        in: query
    post:
      summary: Create a new domain.
      operationId: domainsCreate
      tags:
      - domains
      description: Create a new domain. Before creating a domain, you need to ensure that your DNS provider is properly configured. After creating the domain, you can use the verification endpoint to check if the domain is ready to be used.
      responses:
        '201':
          description: Domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domain'
      deprecated: false
      x-appwrite:
        group: null
        demo: domains/create.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: domains.write
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                teamId:
                  description: Team unique ID.
                  type: string
                  example: <TEAM_ID>
                domain:
                  description: Domain name (e.g. "example.com").
                  type: string
                  example: example.com
              required:
              - teamId
              - domain
  /domains/price:
    get:
      summary: Get domain price
      operationId: domainsGetPrice
      tags:
      - domains
      description: Get the registration price for a domain name.
      responses:
        '200':
          description: DomainPrice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domainPrice'
      deprecated: true
      x-appwrite:
        group: null
        demo: domains/get-price.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: domains.read
        platforms:
        - console
        packaging: false
        public: true
        deprecated:
          since: 2.0.0
          replaceWith: domains.listPrices
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: domain
        description: Domain name to get price for.
        required: true
        schema:
          type: string
          example: example.com
        in: query
      - name: periodYears
        description: Number of years to calculate the domain price for. Must be at least 1.
        required: false
        schema:
          type: integer
          format: uint32
          default: 1
        in: query
      - name: registrationType
        description: 'Type of registration pricing to fetch. Allowed values: new, transfer, renewal, trade.'
        required: false
        schema:
          type: string
          example: new
          title: DomainRegistrationType
          oneOf:
          - type: string
            enum:
            - new
            title: new
          - type: string
            enum:
            - transfer
            title: transfer
          - type: string
            enum:
            - renewal
            title: renewal
          - type: string
            enum:
            - trade
            title: trade
          default: new
        in: query
  /domains/prices:
    get:
      summary: List domain prices
      operationId: domainsListPrices
      tags:
      - domains
      description: Check availability and get the requested registration price for one or more domain names. Availability is resolved for all domains in a single registrar lookup. Unavailable domains have a null price for new registrations, but can still be priced for renewal, transfer, or trade. Every priced domain also carries its renewal price for the same period, so a separate renewal lookup is not needed. A domain whose price could not be resolved, for example because its TLD is not supported, is returned with a null price.
      responses:
        '200':
          description: Domain prices list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domainPricesList'
      deprecated: false
      x-appwrite:
        group: null
        demo: domains/list-prices.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: domains.read
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: domains
        description: Domain names to check availability and price for. Maximum of 50 domains per request.
        required: true
        schema:
          type: array
          items:
            type: string
        in: query
      - name: periodYears
        description: Number of years to calculate the domain price for. Must be at least 1.
        required: false
        schema:
          type: integer
          format: uint32
          default: 1
        in: query
      - name: registrationType
        description: 'Type of registration pricing to fetch. Allowed values: new, transfer, renewal, trade.'
        required: false
        schema:
          type: string
          example: new
          title: DomainRegistrationType
          oneOf:
          - type: string
            enum:
            - new
            title: new
          - type: string
            enum:
            - transfer
            title: transfer
          - type: string
            enum:
            - renewal
            title: renewal
          - type: string
            enum:
            - trade
            title: trade
          default: new
        in: query
  /domains/purchases:
    post:
      summary: Create a domain purchase
      operationId: domainsCreatePurchase
      tags:
      - domains
      description: Initiate a domain purchase by providing registrant details and a payment method. Authorizes the payment and returns a `clientSecret`. If 3D Secure is required, use the `clientSecret` on the client to complete the authentication challenge. Once authentication is complete (or if none is needed), call the Update Purchase endpoint to capture the payment and finalize the purchase.
      responses:
        '201':
          description: DomainPurchase
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domainPurchase'
      deprecated: false
      x-appwrite:
        group: null
        demo: domains/create-purchase.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: billing.write
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                domain:
                  description: Fully qualified domain name to purchase (for example, example.com).
                  type: string
                  example: example.com
                organizationId:
                  description: Team ID that will own the domain.
                  type: string
                  example: <ORGANIZATION_ID>
                firstName:
                  description: Registrant first name used for domain registration.
                  type: string
                  example: <FIRST_NAME>
                lastName:
                  description: Registrant last name used for domain registration.
                  type: string
                  example: <LAST_NAME>
                email:
                  description: Registrant email address for registration and notices.
                  type: string
                  example: email@example.com
                  format: email
                phone:
                  description: Registrant phone number in E.164 format (for example, +15555551234).
                  type: string
                  example: '+12065550100'
                  format: phone
                billingAddressId:
                  description: Billing address ID used for registration contact details.
                  type: string
                  example: <BILLING_ADDRESS_ID>
                addressLine3:
                  description: Additional address line for the registrant (line 3).
                  type: string
                  default: ''
                  example: <ADDRESS_LINE3>
                companyName:
                  description: Company or organization name for the registrant.
                  type: string
                  default: ''
                  example: <COMPANY_NAME>
                periodYears:
                  description: Registration term in years (1-10).
                  type: integer
                  default: 1
                  example: 1
                  format: int32
                autoRenewal:
                  description: Whether the domain should renew automatically after purchase.
                  type: boolean
                  default: true
                  example: false
                paymentMethodId:
                  description: Payment method ID to authorize and capture the purchase.
                  type: string
                  example: <PAYMENT_METHOD_ID>
              required:
              - domain
              - organizationId
              - firstName
              - lastName
              - email
              - phone
              - billingAddressId
              - paymentMethodId
  /domains/purchases/{invoiceId}:
    patch:
      summary: Confirm a domain purchase
      operationId: domainsUpdatePurchase
      tags:
      - domains
      description: Finalize a domain purchase initiated with Create Purchase. Verifies that any required 3D Secure authentication is complete, registers the domain, captures the payment, and provisions default DNS records. Returns a 402 error if authentication is still pending.
      responses:
        '200':
          description: DomainPurchase
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domainPurchase'
      deprecated: false
      x-appwrite:
        group: null
        demo: domains/update-purchase.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: billing.write
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: invoiceId
        description: Invoice ID.
        required: true
        schema:
          type: string
          example: <INVOICE_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                organizationId:
                  description: Team ID that owns the domain.
                  type: string
                  example: <ORGANIZATION_ID>
              required:
              - organizationId
  /domains/suggestions:
    get:
      summary: List domain suggestions
      operationId: domainsListSuggestions
      tags:
      - domains
      description: List domain suggestions.
      responses:
        '200':
          description: Domain suggestions list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domainSuggestionsList'
      deprecated: false
      x-appwrite:
        group: null
        demo: domains/list-suggestions.md
        rate-limit: 50
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: public
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: query
        description: 'Query to find available domains and suggestions. Max length: 256 chars.'
        required: true
        schema:
          type: string
          example: <QUERY>
        in: query
      - name: tlds
        description: TLDs to suggest.
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
        in: query
      - name: limit
        description: Maximum number of suggestions to return.
        required: false
        schema:
          type: integer
          format: int32
        in: query
      - name: filterType
        description: 'Filter type: premium, suggestion.'
        required: false
        schema:
          type: string
          example: premium
          title: DomainSuggestionType
          oneOf:
          - type: string
            enum:
            - premium
            title: premium
          - type: string
            enum:
            - suggestion
            title: suggestion
        in: query
      - name: priceMax
        description: Filter premium domains by maximum price. Only premium domains at or below this price will be returned. Does not affect regular domain suggestions.
        required: false
        schema:
          type: integer
          format: int32
        in: query
      - name: priceMin
        description: Filter premium domains by minimum price. Only premium domains at or above this price will be returned. Does not affect regular domain suggestions.
        required: false
        schema:
          type: integer
          format: int32
        in: query
  /domains/transfers/in:
    post:
      summary: Create a domain transfer in.
      operationId: domainsCreateTransferIn
      tags:
      - domains
      description: Initiate a domain transfer-in by providing an authorization code, registrant details, and a payment method. Authorizes the payment and returns a `clientSecret`. If 3D Secure is required, use the `clientSecret` on the client to complete the authentication challenge. Once authentication is complete (or if none is needed), call the Update Transfer In endpoint to capture the payment and submit the transfer.
      responses:
        '201':
          description: DomainPurchase
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domainPurchase'
      deprecated: false
      x-appwrite:
        group: null
        demo: domains/create-transfer-in.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: billing.write
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                domain:
                  description: Domain name to transfer in.
                  type: string
                  example: example.com
                organizationId:
                  description: Organization ID that this domain will belong to.
                  type: string
                  example: <ORGANIZATION_ID>
                authCode:
                  description: Authorization code for the domain transfer.
                  type: string
                  example: <AUTH_CODE>
                autoRenewal:
                  description: Whether the domain should renew automatically after transfer.
                  type: boolean
                  default: true
                  example: false
                paymentMethodId:
                  description: Payment method ID to authorize and capture the transfer.
                  type: string
                  example: <PAYMENT_METHOD_ID>
              required:
              - domain
              - organizationId
              - authCode
              - paymentMethodId
  /domains/transfers/in/{invoiceId}:
    patch:
      summary: Confirm a domain transfer in
      operationId: domainsUpdateTransferIn
      tags:
      - domains
      description: Finalize a domain transfer-in initiated with Create Transfer In. Verifies that any required 3D Secure authentication is complete, submits the transfer with the authorization code, captures the payment, and sends a confirmation email. Returns a 402 error if authentication is still pending.
      responses:
        '200':
          description: DomainPurchase
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domainPurchase'
      deprecated: false
      x-appwrite:
        group: null
        demo: domains/update-transfer-in.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: billing.write
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: invoiceId
        description: Invoice ID.
        required: true
        schema:
          type: string
          example: <INVOICE_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                organizationId:
                  description: Team ID that owns the domain.
                  type: string
                  example: <ORGANIZATION_ID>
              required:
              - organizationId
  /domains/transfers/out:
    post:
      summary: Create a domain transfer out.
      operationId: domainsCreateTransferOut
      tags:
      - domains
      description: Initiate a domain transfer-out by generating an authorization code for the specified domain. The returned `authCode` should be provided to the gaining provider to complete the transfer. If the domain has auto-renewal enabled, it will be automatically disabled as part of this operation.
      responses:
        '202':
          description: domainTransferOut
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domainTransferOut'
      deprecated: false
      x-appwrite:
        group: null
        demo: domains/create-transfer-out.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: billing.write
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                domainId:
                  description: Domain unique ID.
                  type: string
                  example: <DOMAIN_ID>
                organizationId:
                  description: Organization ID that this domain belongs to.
                  type: string
                  example: <ORGANIZATION_ID>
              required:
              - domainId
              - organizationId
  /domains/{domainId}:
    get:
      summary: Get a single domain by its unique ID.
      operationId: domainsGet
      tags:
      - domains
      description: Get a domain by its unique ID.
      responses:
        '200':
          description: Domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domain'
      deprecated: false
      x-appwrite:
        group: null
        demo: domains/get.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: domains.read
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: domainId
        description: Domain unique ID.
        required: true
        schema:
          type: string
          example: <DOMAIN_ID>
        in: path
    delete:
      summary: Delete a domain by its unique ID.
      operationId: domainsDelete
      tags:
      - domains
      description: 'Delete a domain by its unique ID. This endpoint can be used to delete a domain from your project.

        Once deleted, the domain will no longer be available for use and all associated resources will be removed.'
      responses:
        '204':
          description: No content
      deprecated: false
      x-appwrite:
        group: null
        demo: domains/delete.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: domains.write
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: domainId
        description: Domain unique ID.
        required: true
        schema:
          type: string
          example: <DOMAIN_ID>
        in: path
  /domains/{domainId}/auto-renewal:
    patch:
      summary: Update domain auto-renewal setting.
      operationId: domainsUpdateAutoRenewal
      tags:
      - domains
      description: Enable or disable auto-renewal for a domain.
      responses:
        '200':
          description: Domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domain'
      deprecated: false
      x-appwrite:
        group: null
        demo: domains/update-auto-renewal.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: domains.write
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: domainId
        description: Domain unique ID.
        required: true
        schema:
          type: string
          example: <DOMAIN_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                autoRenewal:
                  description: Whether the domain should renew automatically.
                  type: boolean
                  example: false
              required:
              - autoRenewal
  /domains/{domainId}/nameservers:
    patch:
      summary: Update the registrar nameservers for the given domain.
      operationId: domainsUpdateNameservers
      tags:
      - domains
      description: 'Update the registrar nameservers for the given domain. When nameservers are not provided,

        the domain will be updated to use Appwrite nameservers.'
      responses:
        '200':
          description: Domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domain'
      deprecated: false
      x-appwrite:
        group: null
        demo: domains/update-nameservers.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: domains.write
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: domainId
        description: Domain unique ID.
        required: true
        schema:
          type: string
          example: <DOMAIN_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                nameservers:
                  description: Nameservers to set for the domain. Defaults to Appwrite nameservers when omitted.
                  type: array
                  default: []
                  items:
                    type: string
  /domains/{domainId}/nameservers/verification:
    patch:
      summary: Verify which NS records are used and update the domain accordingly.
      operationId: domainsVerifyNameservers
      tags:
      - domains
      description: 'Verify which NS records are used and update the domain accordingly. This will check the domain''s

        nameservers and update the domain''s status based on whether the nameservers match the expected

        Appwrite nameservers.'
      responses:
        '200':
          description: Domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domain'
      deprecated: false
      x-appwrite:
        group: null
        demo: domains/verify-nameservers.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: domains.write
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: domainId
        description: Domain unique ID.
        required: true
        schema:
          type: string
          example: <DOMAIN_ID>
        in: path
  /domains/{domainId}/presets/google-workspace:
    get:
      summary: Get Google Workspace preset (Records)
      operationId: domainsGetPresetGoogleWorkspace
      tags:
      - domains
      description: List Google Workspace DNS records.
      responses:
        '201':
          description: DNS records list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dnsRecordsList'
      deprecated: false
      x-appwrite:
        group: null
        demo: domains/get-preset-google-workspace.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: domains.write
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: domainId
        description: Domain unique ID.
        required: true
        schema:
          type: string
          example: <DOMAIN_ID>
        in: path
    post:
      summary: Create Google Workspace preset (Records)
      operationId: domainsCreatePresetGoogleWorkspace
      tags:
      - domains
      description: "Add Google Workspace DNS records to the domain. This will create the required MX records \nfor Google Workspace email hosting."
      responses:
        '201':
          description: DNS records list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dnsRecordsList'
      deprecated: false
      x-appwrite:
        group: null
        demo: domains/create-preset-google-workspace.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: domains.write
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: domainId
        description: Domain unique ID.
        required: true
        schema:
          type: string
          example: <DOMAIN_ID>
        in: path
  /domains/{domainId}/presets/icloud:
    get:
      summary: Get iCloud preset (Records)
      operationId: domainsGetPresetICloud
      tags:
      - domains
      description: List iCloud DNS records.
      responses:
        '201':
          description: DNS records list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dnsRecordsList'
      deprecated: false
      x-appwrite:
        group: null
        demo: domains/get-preset-i-cloud.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: domains.write
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: domainId
        description: Domain unique ID.
        required: true
        schema:
          type: string
          example: <DOMAIN_ID>
        in: path
    post:
      summary: Create iCloud preset (Records)
      operationId: domainsCreatePresetICloud
      tags:
      - domains
      description: 'Add iCloud DNS records to the domain. This will create the required MX and SPF records

        for using iCloud email services with your domain.'
      responses:
        '201':
          description: DNS records list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dnsRecordsList'
      deprecated: false
      x-appwrite:
        group: null
        demo: domains/create-preset-i-cloud.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: domains.write
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: domainId
        description: Domain unique ID.
        required: true
        schema:
          type: string
          example: <DOMAIN_ID>
        in: path
  /domains/{domainId}/presets/mailgun:
    get:
      summary: Get Mailgun preset (Records)
      operationId: domainsGetPresetMailgun
      tags:
      - domains
      description: List Mailgun DNS records.
      responses:
        '201':
          description: DNS records list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dnsRecordsList'
      deprecated: false
      x-appwrite:
        group: null
        demo: domains/get-prese

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