openapi: 3.2.0
info:
  title: 'Forward: Endpoint Profiles API'
  summary: Configure the profiles used to collect from network endpoints
  description: |-
    Use these resources to define the CLI, HTTP, and SNMP endpoint profiles that specify how to collect from a
    network's endpoints.
  contact:
    email: support@forwardnetworks.com
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  version: 26.8
servers:
  - url: /api
security:
  - api_token: []
tags:
  - name: Network Collection
    description: Configure and run the collection of configuration and state from a network
  - name: Endpoint Profiles
    description: Configure the profiles used to collect from network endpoints
    parent: Network Collection
paths:
  /endpoint-profiles:
    get:
      tags:
        - Endpoint Profiles
      summary: Get all endpoint profiles
      operationId: getEndpointProfiles
      x-position: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndpointProfiles'
  /endpoint-profiles?type=CLI:
    post:
      tags:
        - Endpoint Profiles
      summary: Add a CLI endpoint profile
      operationId: createCliEndpointProfile
      x-position: 2
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CliEndpointProfileDef'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndpointProfile'
  /endpoint-profiles?type=HTTP:
    post:
      tags:
        - Endpoint Profiles
      summary: Add an HTTP endpoint profile
      operationId: createHttpEndpointProfile
      x-position: 3
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HttpEndpointProfileDef'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndpointProfile'
  /endpoint-profiles?type=SNMP:
    post:
      tags:
        - Endpoint Profiles
      summary: Add an SNMP endpoint profile
      operationId: createSnmpEndpointProfile
      x-position: 4
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SnmpEndpointProfileDef'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndpointProfile'
  /endpoint-profiles/CLI-{profileId}:
    patch:
      tags:
        - Endpoint Profiles
      summary: Update a CLI endpoint profile
      operationId: updateCliEndpointProfile
      x-position: 6
      parameters:
        - name: profileId
          in: path
          description: Profile ID (the numeric part)
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CliEndpointProfilePatch'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndpointProfile'
  /endpoint-profiles/HTTP-{profileId}:
    patch:
      tags:
        - Endpoint Profiles
      summary: Update an HTTP endpoint profile
      operationId: updateHttpEndpointProfile
      x-position: 7
      parameters:
        - name: profileId
          in: path
          description: Profile ID (the numeric part)
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HttpEndpointProfilePatch'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndpointProfile'
  /endpoint-profiles/SNMP-{profileId}:
    patch:
      tags:
        - Endpoint Profiles
      summary: Update an SNMP endpoint profile
      operationId: updateSnmpEndpointProfile
      x-position: 8
      parameters:
        - name: profileId
          in: path
          description: Profile ID (the numeric part)
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SnmpEndpointProfilePatch'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndpointProfile'
  /endpoint-profiles/{profileId}:
    get:
      tags:
        - Endpoint Profiles
      summary: Get an endpoint profile
      operationId: getEndpointProfile
      x-position: 5
      parameters:
        - name: profileId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndpointProfile'
    delete:
      tags:
        - Endpoint Profiles
      summary: Delete an endpoint profile
      operationId: deleteEndpointProfile
      x-position: 9
      parameters:
        - name: profileId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content
          content: {}
components:
  schemas:
    CliEndpointProfileDef:
      type: object
      required:
        - type
        - name
      properties:
        type:
          type: string
          const: CLI
        name:
          type: string
          description: Name of this profile ("HpPrinter", "SamsungTV", etc.).
          examples:
            - sentry_pdu_ssh
        detectorCommand:
          type: string
          description: |-
            CLI command to run to detect a network endpoint of this type. If absent, the profile can be manually
            assigned to a network endpoint, but not auto-detected.
          examples:
            - version
        detectorPatterns:
          type: array
          items:
            type: string
          description: |-
            Patterns matching on output of `detectorCommand` to determine whether the device is of this type. Absent if
            `detectorCommand` is absent. Never empty.
          examples:
            - - Sentry Switched PDU
        detectorErrorPatterns:
          type: array
          items:
            type: string
          description: Patterns matching an error message if a device doesn’t recognize `detectorCommand`.
          examples:
            - - Invalid command
              - 'Switched PDU commands:'
        nameDetectorCommand:
          type: string
          description: |-
            Command to use to detect the name of a network endpoint of this type. If absent, the name cannot be
            detected.
          examples:
            - show network
        nameDetectorPatterns:
          type: array
          items:
            type: string
          description: |-
            Glob patterns used to extract the device name from the output of `nameDetectorCommand`. The word immediately
            after a matched glob pattern is the desired name. If no glob patterns are specified, the first word/token in
            the `nameDetectorCommand` output will be used.
          examples:
            - - FQDN:*enabled
        prompt:
          type: string
          description: |-
            A case-insensitive glob pattern used to identify an interactive console menu prompt. When this pattern
            matches the end of the prompt, ignoring any trailing whitespace, the Collector will enter the configured
            `promptResponse`.
          examples:
            - y/n
        promptResponse:
          type: string
          description: |-
            What the Collector should enter in response to an interactive console menu prompt matching `prompt` in order
            to proceed. Required if `prompt` is set.
          examples:
            - 'y'
        pagePrompt:
          type: string
          description: |-
            Case-insensitive glob pattern used to identify a new page banner. Works like `prompt`. If the device doesn’t
            generate paginated command output or if paging is like the “more” command, omit this property.
          examples:
            - continue\?
        pagePromptResponse:
          type: string
          description: |-
            What the Collector should enter in response to an interactive pagination prompt detected via `pagePrompt` in
            order to proceed. Required if `pagePrompt` is set.
          examples:
            - c
        ptyType:
          type: string
          description: Device’s terminal type ("xterm-256color", "vt100", etc.).
          examples:
            - vt100
        ptyColumnSize:
          type: integer
          format: int32
          description: Column size of the output. Defaults to 500.
          examples:
            - 240
        clearPrompt:
          type: string
          description: |-
            Command to clear the prompt. Can be specified like "ctrl-[a-z]" or "ctrl+[a-z]". Defaults to
            "ctrl+c".
          examples:
            - ctrl+z
        responseTimeoutSec:
          type: integer
          format: int32
          description: Timeout in seconds applied to this profile’s CLI commands run during discovery and collection.
          examples:
            - 15
        commandSets:
          type: array
          items:
            $ref: '#/components/schemas/CommandSet'
          description: |-
            Predefined command sets to run on network endpoints with this profile. The "UNIX" set includes the commands
            "ifconfig", "netstat -ln", "hostname", and "uname -a".
          examples:
            - - UNIX
        customCommands:
          type: array
          items:
            type: string
          description: |-
            Additional commands to run on network endpoints with this profile. Commands should be
            read-only.
          examples:
            - - uptime
              - iptables -L
    CliEndpointProfilePatch:
      type: object
      properties:
        name:
          type: string
          description: Name of this profile ("HpPrinter", "SamsungTV", etc.). Omit to leave this property alone.
          examples:
            - sentry_pdu_ssh
        detectorCommand:
          type: string
          description: |-
            CLI command to run to detect a network endpoint of this type. If absent, the profile can be manually
            assigned to a network endpoint, but not auto-detected. Use `null` to clear. Omit to leave this property
            alone.
          examples:
            - version
        detectorPatterns:
          type: array
          items:
            type: string
          description: |-
            Patterns matching on output of `detectorCommand` to determine whether the device is of this type. Absent if
            `detectorCommand` is absent. Never empty. Use `null` to clear. Omit to leave this property alone.
          examples:
            - - Sentry Switched PDU
        detectorErrorPatterns:
          type: array
          items:
            type: string
          description: |-
            Patterns matching an error message if a device doesn’t recognize `detectorCommand`. Use `null` to clear.
            Omit to leave this property alone.
          examples:
            - - Invalid command
              - 'Switched PDU commands:'
        nameDetectorCommand:
          type: string
          description: |-
            Command to use to detect the name of a network endpoint of this type. If absent, the name cannot be
            detected. Use `null` to clear. Omit to leave this property alone.
          examples:
            - show network
        nameDetectorPatterns:
          type: array
          items:
            type: string
          description: |-
            Glob patterns used to extract the device name from the output of `nameDetectorCommand`. The word immediately
            after a matched glob pattern is the desired name. If no glob patterns are specified, the first word/token in
            the `nameDetectorCommand` output will be used. Use `null` to clear. Omit to leave this property alone.
          examples:
            - - FQDN:*enabled
        prompt:
          type: string
          description: |-
            A case-insensitive glob pattern used to identify an interactive console menu prompt. When this pattern
            matches the end of the prompt, ignoring any trailing whitespace, the Collector will enter the configured
            `promptResponse`. Use `null` to clear. Omit to leave this property alone.
          examples:
            - y/n
        promptResponse:
          type: string
          description: |-
            What the Collector should enter in response to an interactive console menu prompt matching `prompt` in order
            to proceed. Required if `prompt` is set. Use `null` to clear. Omit to leave this property alone.
          examples:
            - 'y'
        pagePrompt:
          type: string
          description: |-
            Case-insensitive glob pattern used to identify a new page banner. Works like `prompt`. If the device doesn’t
            generate paginated command output or if paging is like the “more” command, omit this property. Use `null` to
            clear. Omit to leave this property alone.
          examples:
            - continue\?
        pagePromptResponse:
          type: string
          description: |-
            What the Collector should enter in response to an interactive pagination prompt detected via `pagePrompt` in
            order to proceed. Required if `pagePrompt` is set. Use `null` to clear. Omit to leave this property alone.
          examples:
            - c
        ptyType:
          type: string
          description: |-
            Device’s terminal type ("xterm-256color", "vt100", etc.). Use `null` to clear. Omit to leave this property
            alone.
          examples:
            - vt100
        ptyColumnSize:
          type: integer
          format: int32
          description: |-
            Column size of the output. Defaults to 500. Use `null` to clear. Omit to leave this property
            alone.
          examples:
            - 240
        clearPrompt:
          type: string
          description: |-
            Command to clear the prompt. Can be specified like "ctrl-[a-z]" or "ctrl+[a-z]". Defaults to "ctrl+c". Use
            `null` to clear. Omit to leave this property alone.
          examples:
            - ctrl+z
        responseTimeoutSec:
          type: integer
          format: int32
          description: |-
            Timeout in seconds applied to this profile’s CLI commands run during discovery and collection. Use `null` to
            clear. Omit to leave this property alone.
          examples:
            - 15
        commandSets:
          type: array
          items:
            $ref: '#/components/schemas/CommandSet'
          description: |-
            Predefined command sets to run on network endpoints with this profile. The "UNIX" set includes the commands
            "ifconfig", "netstat -ln", "hostname", and "uname -a". Use `null` to clear. Omit to leave this property
            alone.
          examples:
            - - UNIX
        customCommands:
          type: array
          items:
            type: string
          description: |-
            Additional commands to run on network endpoints with this profile. Commands should be read-only. Use `null`
            to clear. Omit to leave this property alone.
          examples:
            - - uptime
              - iptables -L
    EndpointProfile:
      allOf:
        - type: object
          oneOf:
            - $ref: '#/components/schemas/CliEndpointProfile'
            - $ref: '#/components/schemas/SnmpEndpointProfile'
            - $ref: '#/components/schemas/HttpEndpointProfile'
          discriminator:
            propertyName: type
            mapping:
              CLI: '#/components/schemas/CliEndpointProfile'
              SNMP: '#/components/schemas/SnmpEndpointProfile'
              HTTP: '#/components/schemas/HttpEndpointProfile'
        - $ref: '#/components/schemas/Attribution'
    EndpointProfiles:
      type: object
      required:
        - profiles
      properties:
        profiles:
          type: array
          items:
            $ref: '#/components/schemas/EndpointProfile'
    HttpEndpointProfileDef:
      type: object
      required:
        - type
        - name
        - https
        - authType
        - endpoints
      properties:
        type:
          type: string
          const: HTTP
        name:
          type: string
          description: Name of this profile ("HpPrinter", "SamsungTV", etc.)
          examples:
            - nsxt_https
        https:
          type: boolean
          description: Whether to use HTTPS to connect rather than HTTP.
          examples:
            - true
        authType:
          $ref: '#/components/schemas/HttpAuthStrategy'
          description: The type of HTTP authentication that devices of this type require for API requests.
          examples:
            - BASIC_AUTH
        headers:
          type: object
          additionalProperties:
            type: string
          description: |-
            HTTP headers to send in API requests to devices of this type. These headers should not contain sensitive
            data. Authentication should be handled separately if required using credentials assigned or discovered on a
            per-device basis. Use `authType` to specify what type of HTTP authentication this device type requires.
          examples:
            - accept: application/json
        detectorUri:
          type: string
          description: |-
            HTTP GET URI (path and optional query string) used to detect whether a device of unknown type is this kind
            of network endpoint. If absent, the profile can be manually assigned to a network endpoint, but not
            auto-detected.
          examples:
            - /login.jsp
        detectorPatterns:
          type: array
          items:
            type: string
          description: |-
            Case-insensitive glob patterns used on the response of a request to `detectorUri` to determine whether a
            device of unknown type is of this type. Absent if `detectorUri` is absent. Never empty.
          examples:
            - - VMware NSX
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/HttpEndpoint'
          description: HTTP GET endpoints to collect from network endpoints with this profile. Never empty.
          examples:
            - - name: compute_managers
                path: /api/v1/fabric/compute-managers
              - name: logical_router_ports
                path: /api/v1/logical-router-ports
                paginationModel:
                  type: OFFSET
                  itemsArrayField:
                    - ports
                  parameterName: page
                  offsetIncrementExpression:
                    operator: PLUS_ONE
    HttpEndpointProfilePatch:
      type: object
      properties:
        authType:
          $ref: '#/components/schemas/HttpAuthStrategy'
          description: |-
            The type of HTTP authentication that devices of this type require for API requests. Omit to leave this
            property alone.
          examples:
            - BASIC_AUTH
        detectorPatterns:
          type: array
          items:
            type: string
          description: |-
            Case-insensitive glob patterns used on the response of a request to `detectorUri` to determine whether a
            device of unknown type is of this type. Absent if `detectorUri` is absent. Never empty. Use `null` to clear.
            Omit to leave this property alone.
          examples:
            - - VMware NSX
        detectorUri:
          type: string
          description: |-
            HTTP GET URI (path and optional query string) used to detect whether a device of unknown type is this kind
            of network endpoint. If absent, the profile can be manually assigned to a network endpoint, but not
            auto-detected. Use `null` to clear. Omit to leave this property alone.
          examples:
            - /login.jsp
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/HttpEndpoint'
          description: |-
            HTTP GET endpoints to collect from network endpoints with this profile. Never empty. Omit to leave this
            property alone.
          examples:
            - - name: compute_managers
                path: /api/v1/fabric/compute-managers
              - name: logical_router_ports
                path: /api/v1/logical-router-ports
                paginationModel:
                  type: OFFSET
                  itemsArrayField:
                    - ports
                  parameterName: page
                  offsetIncrementExpression:
                    operator: PLUS_ONE
        headers:
          type: object
          additionalProperties:
            type: string
          description: |-
            HTTP headers to send in API requests to devices of this type. These headers should not contain sensitive
            data. Authentication should be handled separately if required using credentials assigned or discovered on a
            per-device basis. Use `authType` to specify what type of HTTP authentication this device type requires. Use
            `null` to clear. Omit to leave this property alone.
          examples:
            - accept: application/json
        https:
          type: boolean
          description: Whether to use HTTPS to connect rather than HTTP. Omit to leave this property alone.
          examples:
            - true
        name:
          type: string
          description: Name of this profile ("HpPrinter", "SamsungTV", etc.) Omit to leave this property alone.
          examples:
            - nsxt_https
    SnmpEndpointProfileDef:
      type: object
      required:
        - type
        - name
      properties:
        type:
          type: string
          const: SNMP
        name:
          type: string
          description: Name of this profile ("HpPrinter", "SamsungTV", etc.).
          examples:
            - esxi_snmp
        detectorOid:
          type: string
          description: |-
            OID to collect to detect a network endpoint of this type. If absent, the profile can be manually assigned to
            a network endpoint, but not auto-detected.
          examples:
            - 1.3.6.1.2.1.1.1.0
        detectorPatterns:
          type: array
          items:
            type: string
          description: |-
            Patterns matching on output of `detectorOid` to determine whether the device is of this type. Absent if
            `detectorOid` is absent. Never empty.
          examples:
            - - ESXi
        nameDetectorOid:
          type: string
          description: |-
            OID to collect to detect the name of a network endpoint of this type. If absent, the name cannot be
            detected.
          examples:
            - 1.3.6.1.2.1.1.5
        nameDetectorPatterns:
          type: array
          items:
            type: string
          description: |-
            Glob patterns used to extract the device name from the collected value for `nameDetectorOid`. The word
            immediately after a matched glob pattern is the desired name. If no glob patterns are specified, the first
            word/token in the `nameDetectorOid` value will be used.
          examples:
            - - FQDN:*enabled
        responseTimeoutSec:
          type: integer
          format: int32
          description: |-
            Timeout in seconds for retrieving the value of one of this profile’s OIDs during discovery or collection.
            Defaults to 5.
          examples:
            - 10
        oidSets:
          type: array
          items:
            $ref: '#/components/schemas/OidSet'
          description: |-
            Predefined OID sets to collect from network endpoints with this profile. The "STANDARD" set includes OIDs
            for system name, system description, TCP info, UDP info, host address, and interface info.
          examples:
            - - STANDARD
        customOids:
          type: array
          items:
            $ref: '#/components/schemas/CustomOid'
          description: |-
            Additional OIDs to collect from network endpoints with this profile. The output of each OID is saved to a
            file with the associated name.
          examples:
            - - name: system_desc
                oid: 1.3.6.1.2.1.1.1
              - name: hostname
                oid: 1.3.6.1.2.1.1.5
    SnmpEndpointProfilePatch:
      type: object
      properties:
        name:
          type: string
          description: Name of this profile ("HpPrinter", "SamsungTV", etc.). Omit to leave this property alone.
          examples:
            - esxi_snmp
        detectorOid:
          type: string
          description: |-
            OID to collect to detect a network endpoint of this type. If absent, the profile can be manually assigned to
            a network endpoint, but not auto-detected. Use `null` to clear. Omit to leave this property alone.
          examples:
            - 1.3.6.1.2.1.1.1.0
        detectorPatterns:
          type: array
          items:
            type: string
          description: |-
            Patterns matching on output of `detectorOid` to determine whether the device is of this type. Absent if
            `detectorOid` is absent. Never empty. Use `null` to clear. Omit to leave this property alone.
          examples:
            - - ESXi
        nameDetectorOid:
          type: string
          description: |-
            OID to collect to detect the name of a network endpoint of this type. If absent, the name cannot be
            detected. Use `null` to clear. Omit to leave this property alone.
          examples:
            - 1.3.6.1.2.1.1.5
        nameDetectorPatterns:
          type: array
          items:
            type: string
          description: |-
            Glob patterns used to extract the device name from the collected value for `nameDetectorOid`. The word
            immediately after a matched glob pattern is the desired name. If no glob patterns are specified, the first
            word/token in the `nameDetectorOid` value will be used. Use `null` to clear. Omit to leave this property
            alone.
          examples:
            - - FQDN:*enabled
        responseTimeoutSec:
          type: integer
          format: int32
          description: |-
            Timeout in seconds for retrieving the value of one of this profile’s OIDs during discovery or collection.
            Defaults to 5. Use `null` to clear. Omit to leave this property alone.
          examples:
            - 10
        oidSets:
          type: array
          items:
            $ref: '#/components/schemas/OidSet'
          description: |-
            Predefined OID sets to collect from network endpoints with this profile. The "STANDARD" set includes OIDs
            for system name, system description, TCP info, UDP info, host address, and interface info. Use `null` to
            clear. Omit to leave this property alone.
          examples:
            - - STANDARD
        customOids:
          type: array
          items:
            $ref: '#/components/schemas/CustomOid'
          description: |-
            Additional OIDs to collect from network endpoints with this profile. The output of each OID is saved to a
            file with the associated name. Use `null` to clear. Omit to leave this property alone.
          examples:
            - - name: system_desc
                oid: 1.3.6.1.2.1.1.1
              - name: hostname
                oid: 1.3.6.1.2.1.1.5
    CommandSet:
      type: string
      const: UNIX
    CliEndpointProfile:
      allOf:
        - type: object
          required:
            - id
          properties:
            id:
              type: string
              description: System-assigned identifier of this endpoint profile. Always begins with "CLI-".
              examples:
                - CLI-7
        - $ref: '#/components/schemas/CliEndpointProfileDef'
    OidSet:
      type: string
      const: STANDARD
    CustomOid:
      type: object
      required:
        - name
        - oid
      properties:
        name:
          type: string
          description: |-
            A concise name for the OID’s value. Used in the name of the file the Collector creates when it retrieves the
            OID’s value from a device. Can contain only letters, digits, underscores, and hyphens.
          examples:
            - system_desc
        oid:
          type: string
          description: |-
            A numeric object identifier (OID) from the Management Information Base (MIB) for the Simple Network
            Management Protocol (SNMP).
          examples:
            - 1.3.6.1.2.1.1.1
    SnmpEndpointProfile:
      allOf:
        - type: object
          required:
            - id
          properties:
            id:
              type: string
              description: System-assigned identifier of this endpoint profile. Always begins with "SNMP-".
              examples:
                - SNMP-5
        - $ref: '#/components/schemas/SnmpEndpointProfileDef'
    HttpAuthStrategy:
      type: string
      enum:
        - NONE
        - BASIC_AUTH
    OffsetIncrementExpression:
      type: object
      required:
        - operator
      properties:
        operator:
          type: string
          description: |-
            "IDENTITY" means to add the number at `path` in the previous request’s response to the previous request’s
            offset value. "LENGTH" means to add the length of the array at `path` in the previous request’s response to
            the previous request’s offset value. "PLUS_ONE" means to simply add one to the previous request’s offset
            value.
          examples:
            - LENGTH
          enum:
            - IDENTITY
            - LENGTH
            - PLUS_ONE
        path:
          type: array
          items:
            type: string
          description: |-
            JSON property name(s) that must be accessed, starting from the top level of the HTTP response, to reach the
            value or array needed to calculate the next offset value. Required if `operator` is "IDENTITY" or "LENGTH";
            absent otherwise.
          examples:
            - - items
    OffsetBasedPagination:
      type: object
      required:
        - type
        - itemsArrayField
        - parameterName
        - offsetIncrementExpression
      properties:
        type:
          type: string
          const: OFFSET
        itemsArrayField:
          type: array
          items:
            type: string
          description: |-
            JSON property name(s) that must be accessed, starting from the top level of the HTTP response, to reach the
            paginated data array.
          examples:
            - - items
        parameterName:
          type: string
          description: |-
            The name of the URL query parameter to populate with the offset value that increases with each
            request.
          examples:
            - skip
        offsetIncrementExpression:
          $ref: '#/components/schemas/OffsetIncrementExpression'
          description: |-
            What to add to the previous request’s offset value to get the next request’s offset value. The first
            request’s offset value is always zero.
          examples:
            - operator: LENGTH
              path:
                - items
        maxPages:
          type: integer
          format: int32
          description: Maximum number of pages to collect. Defaults to 1000.
          examples:
            - 100
    UrlCursorBasedPagination:
      type: object
      required:
        - type
        - itemsArrayField
        - urlField
      properties:
        type:
          type: string
          const: URL_CURSOR
        itemsArrayField:
          type: array
          items:
            type: string
          description: |-
            JSON property name(s) that must be accessed, starting from the top level of the HTTP response, to reach the
            paginated data array.
          examples:
            - - items
        urlField:
          type: array
          items:
            type: string
          description: |-
            JSON property name(s) that must be accessed, starting from the top level of the HTTP response, to reach the
            next page’s URL.
          examples:
            - - pagingInfo
              - nextPageUrl
        maxPages:
          type: integer
          format: int32
          description: Maximum number of pages to collect. Defaults to 1000.
          examples:
            - 100
    ParameterCursorBasedPagination:
      type: object
      required:
        - type
        - itemsArrayField
        - parameterName
        - parameterField
      properties:
        type:
          type: string
          const: PARAMETER_CURSOR
        itemsArrayField:
          type: array
          items:
            type: string
          description: |-
            JSON property name(s) that must be accessed, starting from the top level of the HTTP response, to reach the
            paginated data array.
          examples:
            - - items
        parameterName:
          type: string
          description: |-
            The name of the URL query parameter to populate with the cursor value from the previous
            response.
          examples:
            - pagingCursor
        parameterField:
          type: array
          items:
            type: string
          description: |-
            JSON property name(s) that must be accessed, starting from the top level of the HTTP response, to reach the
            next page’s cursor value.
          examples:
            - - pagingInfo
              - nextPageCursor
        maxPages:
          type: integer
          format: int32
          description: Maximum number of pages to collect. Defaults to 1000.
          examples:
            - 100
    PaginationModel:
      type: object
      required:
        - type
        - itemsArrayField
      properties:
        type:
          type: string
          enum:
            - OFFSET
            - URL_CURSOR
            - PARAMETER_CURSOR
        itemsArrayField:
          type: array
          items:
            type: string
          description: |-
            JSON property name(s) that must be accessed, starting from the top level of the HTTP response, to reach the
            paginated data array.
          examples:
            - - items
        maxPages:
          type: integer
          format: int32
          description: Maximum number of pages to collect. Defaults to 1000.
          examples:
            - 100
      oneOf:
        - $ref: '#/components/schemas/OffsetBasedPagination'
        - $ref: '#/components/schemas/UrlCursorBasedPagination'
        - $ref: '#/components/schemas/ParameterCursorBasedPagination'
      discriminator:
        propertyName: type
        mapping:
          OFFSET: '#/components/schemas/OffsetBasedPagination'
          URL_CURSOR: '#/components/schemas/UrlCursorBasedPagination'
          PARAMETER_CURSOR: '#/components/schemas/ParameterCursorBasedPagination'
    HttpEndpoint:
      type: object
      required:
        - name
        - path
      properties:
        name:
          type: string
          description: |-
            A concise name for this HTTP endpoint. Used in the name of the file(s) the Collector creates to store the
            response(s) it receives. Can contain only letters, digits, underscores, hyphens, and dots.
          examples:
            - compute_managers
        path:
          type: string
          description: The URL path for this HTTP endpoint. Must start with "/". May include a query string.
          examples:
            - /api/v1/fabric/compute-managers
        paginationModel:
          $ref: '#/components/schemas/PaginationModel'
          description: |-
            Instructions for fetching this HTTP endpoint’s dataset in parts (pages) using a sequence of requests. Can
            only be used if this endpoint’s response format is JSON. Absent if this endpoint doesn’t require pagination.
          examples:
            - type: OFFSET
              itemsArrayField:
                - managers
              parameterName: page
              offsetIncrementExpression:
                operator: PLUS_ONE
    HttpEndpointProfile:
      allOf:
        - type: object
          required:
            - id
          properties:
            id:
              type: string
              description: System-assigned identifier of this endpoint profile. Always begins with "HTTP-".
              examples:
                - HTTP-4
        - $ref: '#/components/schemas/HttpEndpointProfileDef'
    Attribution:
      type: object
      properties:
        createdById:
          type: string
          description: |-
            The ID of the user who created this entity, if known. *Note*: The referenced user account might no longer
            exist since an administrator can delete accounts.
          examples:
            - '456'
        createdAt:
          type: string
          description: When this entity was created, if known.
          examples:
            - '2021-12-29T16:30:45.111Z'
        createdBy:
          type: string
          description: |-
            The username of the user who created this entity, if known. Absent if the user account has been
            deleted.
          examples:
            - me@example.com
        updatedById:
          type: string
          description: |-
            The ID of the user who most recently updated this entity, if known. *Note*: The referenced user account
            might no longer exist since an administrator can delete accounts.
          examples:
            - '789'
        updatedAt:
          type: string
          description: When this entity was most recently updated, if known.
          examples:
            - '2024-10-27T21:44:51.345Z'
        updatedBy:
          type: string
          description: |-
            The username of the user who most recently updated this entity, if known. Absent if the user account has
            been deleted.
          examples:
            - you@example.com
  securitySchemes:
    api_token:
      type: http
      scheme: basic
