openapi: 3.0.3
info:
  title: Common
  description: Cloudflare Common API Components
  version: 4.0.0
paths: {}
components:
  schemas:
    uuid:
      description: UUID.
      type: string
      maxLength: 36
      example: f174e90a-fafe-4643-bbbc-4a0ed4fc8415
      x-auditable: true

    identifier:
      description: Identifier.
      type: string
      maxLength: 32
      example: 023e105f4ecef8ad9ca31a8372d0c353
      x-auditable: true

    timestamp:
      type: string
      format: date-time
      example: "2014-01-01T05:20:00.12345Z"
      x-auditable: true

    # API response envelopes
    api-response-collection:
      type: object
      allOf:
        - $ref: "#/components/schemas/api-response-common"
        - type: object
          properties:
            result_info:
              type: object
              properties:
                page:
                  description: Current page within paginated list of results.
                  type: number
                  example: 1
                per_page:
                  description: Number of results per page of results.
                  type: number
                  example: 20
                total_pages:
                  description: The number of total pages in the entire result set.
                  type: number
                  example: 100
                count:
                  description: Total number of results for the requested service.
                  type: number
                  example: 1
                total_count:
                  description: Total results available without any search parameters.
                  type: number
                  example: 2000

    messages:
      type: array
      items:
        type: object
        required:
          - code
          - message
        properties:
          code:
            type: integer
            minimum: 1000
          message:
            type: string
          documentation_url:
            type: string
          source:
            type: object
            properties:
              pointer:
                type: string
        uniqueItems: true
      example: []

    api-response-common:
      type: object
      required:
        - success
        - errors
        - messages
      properties:
        success:
          description: Whether the API call was successful.
          type: boolean
          enum:
            - true
          example: true
        errors:
          $ref: "#/components/schemas/messages"
        messages:
          $ref: "#/components/schemas/messages"

    api-response-common-failure:
      type: object
      required:
        - success
        - errors
        - messages
        - result
      properties:
        success:
          description: Whether the API call was successful.
          type: boolean
          enum:
            - false
          example: false
        errors:
          allOf:
            - $ref: "#/components/schemas/messages"
          minLength: 1
          example:
            - code: 7003
              message: No route for the URI
        messages:
          allOf:
            - $ref: "#/components/schemas/messages"
          example: []
        result:
          enum:
            - null
          example: null
          type: object
          nullable: true

    api-response-single-id:
      type: object
      allOf:
        - $ref: "#/components/schemas/api-response-common"
        - type: object
          properties:
            result:
              type: object
              required:
                - id
              properties:
                id:
                  $ref: "#/components/schemas/identifier"
              nullable: true

    api-response-single:
      type: object
      allOf:
        - $ref: "#/components/schemas/api-response-common"

    # Account
    account:
      type: object
      required:
        - id
        - name
      properties:
        id:
          $ref: "#/components/schemas/identifier"
        name:
          description: Account name.
          type: string
          maxLength: 100
          example: Demo Account
          x-auditable: true
        settings:
          type: object
          description: Account settings.
          properties:
            enforce_twofactor:
              type: boolean
              description: |-
                Indicates whether membership in this account requires that
                Two-Factor Authentication is enabled.
              default: false
              x-auditable: true
            use_account_custom_ns_by_default:
              type: boolean
              description: |-
                Indicates whether new zones should use the account-level custom
                nameservers by default.
              default: false
              x-auditable: true
        created_on:
          description: Timestamp for the creation of the account.
          type: string
          format: date-time
          readOnly: true
          example: 2014-03-01T12:21:02.0000Z
          x-auditable: true

    scope:
      description: All zones owned by the account will have the rule applied.
      type: object
      properties:
        id:
          $ref: "#/components/schemas/identifier"
        name:
          $ref: "#/components/schemas/account/properties/name"
        type:
          type: string
          enum:
            - account
          description: The scope of the rule.
          readOnly: true
          example: account
          x-auditable: true

    # Zone
    zone:
      type: object
      required:
        - id
        - name
        - development_mode
        - owner
        - account
        - meta
        - original_name_servers
        - original_registrar
        - original_dnshost
        - created_on
        - modified_on
        - activated_on
      properties:
        id:
          $ref: "#/components/schemas/identifier"
        name:
          description: The domain name.
          type: string
          pattern: ^([a-zA-Z0-9][\-a-zA-Z0-9]*\.)+[\-a-zA-Z0-9]{2,20}$
          maxLength: 253
          readOnly: true
          example: example.com
          x-auditable: true
        development_mode:
          description: |-
            The interval (in seconds) from when development mode expires
            (positive integer) or last expired (negative integer) for the
            domain. If development mode has never been enabled, this value is 0.
          type: number
          readOnly: true
          example: 7200
          x-auditable: true
        original_name_servers:
          description: |-
            Original name servers before moving to Cloudflare.
          type: array
          items:
            type: string
            format: hostname
            x-auditable: true
          readOnly: true
          example:
            - ns1.originaldnshost.com
            - ns2.originaldnshost.com
          nullable: true
        original_registrar:
          description: Registrar for the domain at the time of switching to Cloudflare.
          type: string
          readOnly: true
          example: GoDaddy
          nullable: true
          x-auditable: true
        original_dnshost:
          description: DNS host at the time of switching to Cloudflare.
          type: string
          maxLength: 50
          readOnly: true
          example: NameCheap
          nullable: true
          x-auditable: true
        created_on:
          description: When the zone was created.
          type: string
          format: date-time
          readOnly: true
          example: 2014-01-01T05:20:00.12345Z
          x-auditable: true
        modified_on:
          description: When the zone was last modified.
          type: string
          format: date-time
          readOnly: true
          example: 2014-01-01T05:20:00.12345Z
          x-auditable: true
        activated_on:
          description: |-
            The last time proof of ownership was detected and the zone was made
            active.
          type: string
          format: date-time
          readOnly: true
          example: 2014-01-02T00:01:00.12345Z
          nullable: true
          x-auditable: true
    vanity_name_servers:
      description: |-
        An array of domains used for custom name servers. This is only
        available for Business and Enterprise plans.
      type: array
      items:
        type: string
        format: hostname
        maxLength: 253
        x-auditable: true
      example:
        - ns1.example.com
        - ns2.example.com

    # User
    user:
      type: object
      required:
        - id
        - email
        - last_name
        - first_name
        - telephone
        - country
        - zipcode
        - two_factor_authentication_enabled
        - created_on
        - modified_on
      properties:
        id:
          $ref: "#/components/schemas/identifier"
        email:
          description: The contact email address of the user..
          type: string
          maxLength: 90
          example: user@example.com
          x-auditable: true
        first_name:
          description: User's first name.
          type: string
          maxLength: 60
          example: John
          nullable: true
        last_name:
          description: User's last name.
          type: string
          maxLength: 60
          example: Appleseed
          nullable: true
        username:
          description: A username used to access other cloudflare services, like support.
          type: string
          pattern: ^[a-z0-9]+([\-\._]?[a-z0-9]+)+$
          minLength: 3
          maxLength: 90
          example: cfuser12345
          x-auditable: true
        telephone:
          description: User's telephone number.
          type: string
          maxLength: 20
          example: +1 123-123-1234
          nullable: true
        country:
          description: The country in which the user lives..
          type: string
          maxLength: 30
          example: US
          nullable: true
        zipcode:
          description: The zipcode or postal code where the user lives..
          type: string
          maxLength: 20
          example: "12345"
          nullable: true
        created_on:
          description: When the user signed up..
          readOnly: true
          type: string
          format: date-time
          example: 2014-01-01T05:20:00Z
          x-auditable: true
        modified_on:
          description: Last time the user was modified.
          readOnly: true
          type: string
          format: date-time
          example: 2014-01-01T05:20:00Z
          x-auditable: true

    # Plan
    plan:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/identifier"
        name:
          description: The plan name.
          type: string
          maxLength: 80
          readOnly: true
          example: Pro Plan
          x-auditable: true
        price:
          description: The price of the subscription that will be billed, in US dollars.
          type: number
          readOnly: true
          example: 20
          x-auditable: true
        currency:
          description: The monetary unit in which pricing information is displayed.
          type: string
          readOnly: true
          example: USD
          x-auditable: true
        frequency:
          description: The frequency at which you will be billed for this plan.
          type: string
          enum:
            - weekly
            - monthly
            - quarterly
            - yearly
            - ""
          readOnly: true
          example: monthly
          x-auditable: true
        legacy_id:
          description: |-
            A 'friendly' identifier to indicate to the UI what plan the
            object is.
          type: string
          enum:
            - free
            - pro
            - business
            - enterprise
          example: pro
        is_subscribed:
          description: If the zone is subscribed to this plan.
          type: boolean
          example: true
          x-auditable: true
        can_subscribe:
          description: If the zone is allowed to subscribe to this plan.
          type: boolean
          example: true
          x-auditable: true