common.yaml

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

    identifier:
      description: Identifier
      type: string
      maxLength: 32
      example: 023e105f4ecef8ad9ca31a8372d0c353

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

    # API response envelopes
    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
        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

    api-response-collection:
      type: object
      allOf:
        - $ref: "#/components/schemas/api-response-common"
        - properties:
            result_info:
              $ref: "#/components/schemas/result_info"
    messages:
      type: array
      items:
        type: object
        required:
          - code
          - message
        properties:
          code:
            type: integer
            minimum: 1000
          message:
            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"
        - 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
        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
            use_account_custom_ns_by_default:
              type: boolean
              description: |-
                Indicates whether new zones should use the account-level custom
                nameservers by default
              default: false
        created_on:
          description: Timestamp for the creation of the account
          type: string
          format: date-time
          readOnly: true
          example: 2014-03-01T12:21:02.0000Z

    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

    # 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
        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
        original_name_servers:
          description: |-
            Original name servers before moving to Cloudflare
            Notes: Is this only available for full zones?
          type: array
          items:
            type: string
            format: hostname
          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
        original_dnshost:
          description: DNS host at the time of switching to Cloudflare
          type: string
          maxLength: 50
          readOnly: true
          example: NameCheap
          nullable: true
        created_on:
          description: When the zone was created
          type: string
          format: date-time
          readOnly: true
          example: 2014-01-01T05:20:00.12345Z
        modified_on:
          description: When the zone was last modified
          type: string
          format: date-time
          readOnly: true
          example: 2014-01-01T05:20:00.12345Z
        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
    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
      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
        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
        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
        modified_on:
          description: Last time the user was modified
          readOnly: true
          type: string
          format: date-time
          example: 2014-01-01T05:20:00Z

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