openapi: 3.1.0
info:
  title: nOps Essentials Scheduler API
  description: The nOps public API provides programmatic access to cloud cost and usage insights, MAP migration project management, and essentials scheduler operations. It enables teams to monitor and analyze AWS environments, automate cost optimization tasks, and integrate nOps data into existing analytics tools and monitoring systems outside of the nOps dashboard.
  version: 1.0.0
  contact:
    name: nOps Support
    url: https://help.nops.io/docs/support/open-support-case
  termsOfService: https://www.nops.io/terms-of-service/
servers:
- url: https://app.nops.io
  description: nOps Production API
security:
- ApiKeyAuth: []
tags:
- name: Essentials Scheduler
  description: Endpoints for managing the nOps Essentials scheduler, which automates resource management tasks like starting and stopping non-production workloads to reduce costs.
paths:
  /svc/k8s_cost/recommendations/essentials/scheduler/workload/:
    get:
      operationId: getSchedulerWorkloadRecommendations
      summary: Nops Get Scheduler Workload Recommendations
      description: Retrieves workload recommendations for the Essentials scheduler, including suggestions for scheduling non-production workloads to reduce costs.
      tags:
      - Essentials Scheduler
      parameters:
      - name: sort_type
        in: query
        required: false
        description: Sort order for results (asc or desc).
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: project_id
        in: query
        required: false
        description: Comma-separated list of nOps AWS Project IDs to filter by.
        schema:
          type: string
      - name: environment
        in: query
        required: false
        description: Comma-separated list of environments to filter by.
        schema:
          type: string
      responses:
        '200':
          description: Successful response with workload recommendations.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized. Invalid or missing API key.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /svc/k8s_cost/recommendations/essentials/scheduler/workload/summary/:
    get:
      operationId: getSchedulerWorkloadSummary
      summary: Nops Get Scheduler Workload Summary
      description: Retrieves a summary of workload recommendations for the Essentials scheduler.
      tags:
      - Essentials Scheduler
      parameters:
      - name: project_id
        in: query
        required: false
        description: Comma-separated list of nOps AWS Project IDs to filter by.
        schema:
          type: string
      - name: environment
        in: query
        required: false
        description: Comma-separated list of environments to filter by.
        schema:
          type: string
      responses:
        '200':
          description: Successful response with workload summary.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized. Invalid or missing API key.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /svc/k8s_cost/recommendations/essentials/scheduler/utilization/:
    get:
      operationId: getSchedulerUtilizationRecommendations
      summary: Nops Get Scheduler Utilization Recommendations
      description: Retrieves utilization-based recommendations for the Essentials scheduler, identifying idle or underutilized resources.
      tags:
      - Essentials Scheduler
      parameters:
      - name: sort_type
        in: query
        required: false
        description: Sort order for results (asc or desc).
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: project_id
        in: query
        required: false
        description: Comma-separated list of nOps AWS Project IDs to filter by.
        schema:
          type: string
      - name: environment
        in: query
        required: false
        description: Comma-separated list of environments to filter by.
        schema:
          type: string
      responses:
        '200':
          description: Successful response with utilization recommendations.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized. Invalid or missing API key.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /svc/k8s_cost/recommendations/essentials/scheduler/utilization/summary/:
    get:
      operationId: getSchedulerUtilizationSummary
      summary: Nops Get Scheduler Utilization Summary
      description: Retrieves a summary of utilization recommendations for the Essentials scheduler.
      tags:
      - Essentials Scheduler
      parameters:
      - name: project_id
        in: query
        required: false
        description: Comma-separated list of nOps AWS Project IDs to filter by.
        schema:
          type: string
      - name: environment
        in: query
        required: false
        description: Comma-separated list of environments to filter by.
        schema:
          type: string
      responses:
        '200':
          description: Successful response with utilization summary.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized. Invalid or missing API key.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /svc/notifications/scheduler/nops_scheduler:
    post:
      operationId: createScheduler
      summary: Nops Create a Scheduler
      description: Creates a new scheduler for automating resource management tasks such as starting and stopping non-production workloads on a schedule to reduce costs.
      tags:
      - Essentials Scheduler
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SchedulerCreateRequest'
      responses:
        '201':
          description: Scheduler created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scheduler'
        '400':
          description: Bad request. Invalid scheduler configuration.
        '401':
          description: Unauthorized. Invalid or missing API key.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /svc/notifications/scheduler/{id}/trigger:
    post:
      operationId: triggerScheduler
      summary: Nops Manually Trigger a Scheduler
      description: Manually triggers a specific scheduler to run its configured actions immediately.
      tags:
      - Essentials Scheduler
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the scheduler to trigger.
        schema:
          type: integer
      responses:
        '200':
          description: Scheduler triggered successfully.
        '401':
          description: Unauthorized. Invalid or missing API key.
        '404':
          description: Scheduler not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /svc/notifications/scheduler/{id}/enable:
    post:
      operationId: enableScheduler
      summary: Nops Enable a Scheduler
      description: Enables a previously disabled scheduler so it resumes running on its configured schedule.
      tags:
      - Essentials Scheduler
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the scheduler to enable.
        schema:
          type: integer
      responses:
        '200':
          description: Scheduler enabled successfully.
        '401':
          description: Unauthorized. Invalid or missing API key.
        '404':
          description: Scheduler not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /svc/notifications/scheduler/{id}/disable:
    post:
      operationId: disableScheduler
      summary: Nops Disable a Scheduler
      description: Disables a scheduler so it stops running on its configured schedule.
      tags:
      - Essentials Scheduler
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the scheduler to disable.
        schema:
          type: integer
      responses:
        '200':
          description: Scheduler disabled successfully.
        '401':
          description: Unauthorized. Invalid or missing API key.
        '404':
          description: Scheduler not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    SchedulerCreateRequest:
      type: object
      properties:
        name:
          type: string
          description: Name of the scheduler.
          example: Example Title
        project_id:
          type: integer
          description: The nOps AWS Project ID to associate with.
          example: '500123'
        schedule:
          type: object
          description: Schedule configuration for the scheduler.
          example: example_value
        resources:
          type: array
          description: List of resources to manage with this scheduler.
          items:
            type: object
          example: []
    Scheduler:
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier of the scheduler.
          example: abc123
        name:
          type: string
          description: Name of the scheduler.
          example: Example Title
        enabled:
          type: boolean
          description: Whether the scheduler is currently enabled.
          example: true
        project_id:
          type: integer
          description: The associated nOps AWS Project ID.
          example: '500123'
        created_at:
          type: string
          format: date-time
          description: Timestamp when the scheduler was created.
          example: '2026-01-15T10:30:00Z'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Nops-Api-Key
      description: API key generated from the nOps console under Organization Settings. Include this key in the X-Nops-Api-Key header for all requests.
    SignatureAuth:
      type: apiKey
      in: header
      name: x-nops-signature
      description: Encoded signature for enhanced security. Created using a public/private key pair configured in the nOps console.