Cast AI Node Overlays API

openapi: 3.2.0
info:
  title: Kent Node Overlays API
  version: 0.0.1
  description: Provides an API to read Karpenter NodeOverlays reported by the cluster.
servers:
- url: https://api.cast.ai/
  description: US endpoint
- url: https://api.eu.cast.ai/
  description: EU endpoint
security:
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: NodeOverlaysAPI
  description: Provides an API to read Karpenter NodeOverlays reported by the cluster.
paths:
  /kent/v1alpha/organizations/{organizationId}/clusters/{clusterId}/node-overlays:
    get:
      tags:
      - NodeOverlaysAPI
      summary: Lists NodeOverlays
      description: Lists NodeOverlays for a cluster as observed in the latest snapshot.
      operationId: NodeOverlaysAPI_ListNodeOverlays
      parameters:
      - name: organizationId
        in: path
        description: The ID of the Organization.
        required: true
        schema:
          type: string
      - name: clusterId
        in: path
        description: The ID of the cluster.
        required: true
        schema:
          type: string
      - name: page.limit
        in: query
        description: Defines the number of items that should be returned
        schema:
          type: string
      - name: page.cursor
        in: query
        description: "Cursor that defines token indicating where to start the next page.\n Empty value indicates to start from beginning of the dataset."
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListNodeOverlaysResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /kent/v1alpha/organizations/{organizationId}/clusters/{clusterId}/node-overlays/{id}:
    get:
      tags:
      - NodeOverlaysAPI
      summary: Gets a NodeOverlay by name
      description: Returns a single NodeOverlay by name from the latest snapshot.
      operationId: NodeOverlaysAPI_GetNodeOverlay
      parameters:
      - name: organizationId
        in: path
        description: The ID of the Organization.
        required: true
        schema:
          type: string
      - name: clusterId
        in: path
        description: The ID of the cluster.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: The name of the NodeOverlay.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeOverlay'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
components:
  schemas:
    NodeOverlay:
      type: object
      properties:
        apiVersion:
          type: string
          description: APIVersion defines the versioned schema of this representation of an object.
        kind:
          type: string
          description: Kind is a string value representing the REST resource this object represents.
        metadata:
          allOf:
          - $ref: '#/components/schemas/Metadata'
          description: Metadata contains the standard object metadata.
        spec:
          allOf:
          - $ref: '#/components/schemas/NodeOverlaySpec'
          description: Spec is the specification of the desired behavior of the NodeOverlay.
        status:
          allOf:
          - $ref: '#/components/schemas/NodeOverlayStatus'
          description: Status represents information about the status of a NodeOverlay.
        source:
          enum:
          - NODE_OVERLAY_SOURCE_UNSPECIFIED
          - NODE_OVERLAY_SOURCE_CAST_AI
          - NODE_OVERLAY_SOURCE_CUSTOMER
          type: string
          description: Source indicates whether this NodeOverlay was created by CAST AI or by the customer.
          format: enum
        nodeCount:
          allOf:
          - $ref: '#/components/schemas/NodeOverlayNodeCount'
          description: NodeCount is the count of nodes in the cluster that match this overlay's requirements.
      description: Karpenter NodeOverlay definition.
    NodeSelectorRequirement:
      type: object
      properties:
        key:
          type: string
          description: Key is the label key the selector applies to.
        operator:
          type: string
          description: Operator relates the key to values (In, NotIn, Exists, DoesNotExist, Gt, Lt, Gte, Lte).
        values:
          type: array
          items:
            type: string
          description: Values are the values compared against the key.
      description: A node selector requirement applied during scheduling.
    NodeOverlayStatus:
      type: object
      properties:
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/Condition'
          description: Conditions contains signals for health and readiness.
      description: NodeOverlayStatus defines the observed state of a NodeOverlay.
    Status:
      type: object
      properties:
        code:
          type: integer
          description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
          format: int32
        message:
          type: string
          description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
        details:
          type: array
          items:
            $ref: '#/components/schemas/GoogleProtobufAny'
          description: A list of messages that carry the error details.  There is a common set of message types for APIs to use.
      description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).'
    ListNodeOverlaysResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/NodeOverlay'
          description: The list of NodeOverlays observed in the latest snapshot.
      description: Response message for listing NodeOverlays.
    NodeOverlayNodeCount:
      type: object
      properties:
        total:
          type: integer
          description: Total number of matching nodes.
          format: int32
        byInstanceType:
          type: object
          additionalProperties:
            type: integer
            format: int32
          description: 'Breakdown by instance type (e.g. "m5.large": 3, "m5.xlarge": 2).'
      description: NodeOverlayNodeCount holds node counts for nodes matching a NodeOverlay's requirements.
    Condition:
      type: object
      properties:
        lastTransitionTime:
          type: string
          description: 'last_transition_time: The last time the condition transitioned from one status to another (RFC3339 format).'
          format: date-time
        status:
          type: string
          description: 'status: The status of the condition ("True", "False", or "Unknown").'
        type:
          type: string
          description: 'type: The type of condition (e.g., "Ready", "SubnetsReady", "SecurityGroupsReady", "AMIsReady").'
        message:
          type: string
          description: 'message: A human-readable message indicating details about the transition.'
        reason:
          type: string
          description: 'reason: A programmatic identifier indicating the reason for the condition''s last transition.'
      description: 'Condition: Represents the state of a particular aspect of the EC2NodeClass resource.'
    Metadata:
      type: object
      properties:
        name:
          type: string
          description: Name must be unique within a namespace. NodeOverlays are cluster-scoped.
        labels:
          type: object
          additionalProperties:
            type: string
          description: Labels are key/value pairs that can be used to organize and categorize objects.
        annotations:
          type: object
          additionalProperties:
            type: string
          description: Annotations are unstructured key/value pairs that can be used by external tooling.
        createTime:
          type: string
          description: CreationTimestamp is when this NodeOverlay was created.
          format: date-time
      description: Standard object metadata.
    NodeOverlaySpec:
      type: object
      properties:
        requirements:
          type: array
          items:
            $ref: '#/components/schemas/NodeSelectorRequirement'
          description: Requirements constrain when this NodeOverlay is applied during scheduling simulations.
        priceAdjustment:
          type: string
          description: "PriceAdjustment specifies the price change for matching instance types.\n Accepts a fixed modifier (e.g. \"-0.5\", \"1.2\") or a percentage modifier (e.g. \"+10%\", \"-15%\")."
        price:
          type: string
          description: Price specifies an absolute price override for an instance type matching the requirements.
        capacity:
          type: object
          additionalProperties:
            type: string
          description: "Capacity adds extended resources (e.g. nvidia.com/gpu) to nodes that match the requirements.\n Keys follow the Kubernetes resource name format; values are Kubernetes quantities."
        weight:
          type: integer
          description: Weight defines the priority of this NodeOverlay. Higher weight takes precedence.
          format: int32
      description: NodeOverlaySpec is the top-level NodeOverlay specification.
    GoogleProtobufAny:
      type: object
      properties:
        '@type':
          type: string
          description: The type of the serialized message.
      additionalProperties: true
      description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
x-provenance:
  method: searched
  source: https://docs.cast.ai/reference
  harvested: '2026-10-20'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.cast.ai/reference/awsdataproxyapi_getdata.md
  - https://docs.cast.ai/reference/azuredataproxyapi_getdata.md
  - https://docs.cast.ai/reference/clustersapi_onboardclusterscript-1.md
  - https://docs.cast.ai/reference/featuresapi_configurefeature.md
  - https://docs.cast.ai/reference/featuresapi_getclusterfeatureinstallscript.md
  - https://docs.cast.ai/reference/featuresapi_getclusterinstallscript.md
  - https://docs.cast.ai/reference/featuresapi_getfeature.md
  - https://docs.cast.ai/reference/featuresapi_getinstallscript.md
  - https://docs.cast.ai/reference/featuresapi_getorganizationfeatureinstallscript.md
  - https://docs.cast.ai/reference/featuresapi_getorganizationinstallscript.md
  - https://docs.cast.ai/reference/featuresapi_getoverview.md
  - https://docs.cast.ai/reference/featuresapi_getsummary.md
  - https://docs.cast.ai/reference/featuresapi_listfeaturecompatibilities.md
  - https://docs.cast.ai/reference/featuresapi_listfeatureconfigs.md
  - https://docs.cast.ai/reference/featuresapi_listfeatures.md
  - https://docs.cast.ai/reference/kentrollerapi_creatediagnosticreport.md
  - https://docs.cast.ai/reference/kentrollerapi_getdiagnosticreport.md
  - https://docs.cast.ai/reference/kentrollerapi_listdiagnosticreports.md
  - https://docs.cast.ai/reference/machinelearningapi_predictspotinterruption.md
  - https://docs.cast.ai/reference/nodeclassesapi_listaksnodeclasses.md
  - https://docs.cast.ai/reference/nodeclassesapi_listec2nodeclasses.md
  - https://docs.cast.ai/reference/nodeclassesapi_listnodeclasses.md
  - https://docs.cast.ai/reference/nodeclassesapi_updateaksnodeclass.md
  - https://docs.cast.ai/reference/nodeclassesapi_updateec2nodeclass.md
  - https://docs.cast.ai/reference/nodeclassesapi_updatenodeclass.md
  - https://docs.cast.ai/reference/nodeoverlaysapi_getnodeoverlay.md
  - https://docs.cast.ai/reference/nodeoverlaysapi_listnodeoverlays.md
  - https://docs.cast.ai/reference/nodepoolsapi_listnodepools.md
  - https://docs.cast.ai/reference/nodepoolsapi_updatenodepool.md
  - https://docs.cast.ai/reference/nodesapi_deletenode.md
  - https://docs.cast.ai/reference/nodesapi_drainnode.md
  - https://docs.cast.ai/reference/nodesapi_interruptnode.md
  - https://docs.cast.ai/reference/operationsapi_getoperation-3.md
  - https://docs.cast.ai/reference/opspilotreadapi_getresource.md
  - https://docs.cast.ai/reference/opspilotreadapi_listresources.md
  - https://docs.cast.ai/reference/rebalancingapi_cancelrebalancingplan.md
  - https://docs.cast.ai/reference/rebalancingapi_createrebalancingplan.md
  - https://docs.cast.ai/reference/rebalancingapi_executerebalancingplan.md
  - https://docs.cast.ai/reference/rebalancingapi_getrebalancingconstraints.md
  - https://docs.cast.ai/reference/rebalancingapi_getrebalancingplan.md
  - https://docs.cast.ai/reference/rebalancingapi_listrebalancingplans.md
  - https://docs.cast.ai/reference/rebalancingapi_listworkloads.md
  - https://docs.cast.ai/reference/scheduledrebalancingapi_createrebalancingschedule-1.md
  - https://docs.cast.ai/reference/scheduledrebalancingapi_deleterebalancingschedule-1.md
  - https://docs.cast.ai/reference/scheduledrebalancingapi_getrebalancingschedule-1.md
  - https://docs.cast.ai/reference/scheduledrebalancingapi_listrebalancingschedules-1.md
  - https://docs.cast.ai/reference/scheduledrebalancingapi_togglerebalancingschedule.md
  - https://docs.cast.ai/reference/scheduledrebalancingapi_updaterebalancingschedule-1.md
  - https://docs.cast.ai/reference/statusapi_getkentstatus.md
  merge:
    pages: 49
    deduped: 542
    conflicts_kept_first: 0