openapi: 3.1.0
info:
  title: Pica8 AmpCon Network Controller API
  version: 1.12.1
  summary: JSON REST API of the customer-deployed Pica8 AmpCon network controller.
  description: 'Machine-readable transcription of the REST API that Pica8 publishes for its AmpCon Network Controller.


    PROVENANCE — read before using. Pica8 does **not** publish an OpenAPI description. This document was transcribed by API
    Evangelist, operation by operation, from Pica8''s own published API reference: the `AmpCon 1.12.0 API document 20230625.docx`
    attachment on the public AmpCon documentation wiki page listed in `externalDocs` (page 753668, space `ampcon`, AmpCon
    version 1.12.1, update time 2023/06/25). Every path, method, header, request field, example value and error message below
    is copied from that document. Nothing has been invented, extrapolated or inferred: where the source document is incomplete
    or self-inconsistent that is recorded in `x-documentation-gaps` and in the affected operation''s description rather than
    being filled in. This is a derived artifact, not a first-party Pica8 contract.


    DEPLOYMENT — AmpCon is customer-installed software. There is no Pica8-hosted API endpoint; the server variable in `servers[]`
    is the operator''s own AmpCon appliance address, exactly as the source document writes it (`https://<ampcon-server-ip>/`).


    AUTHENTICATION — `POST /token` exchanges AmpCon web login credentials for a JWT, which is then sent as `Authorization:
    Bearer <token>`. Only `superadmin` users may mint a token or call the API.


    ERROR SIGNALLING — AmpCon reports outcome in the response BODY, in a `status` or `status_code` field (200 / 400 / 500),
    together with a human-readable `msg`, `message` or `info` string. The document does not guarantee that the HTTP status
    line mirrors the body, so clients must read the body.'
  contact:
    name: Pica8 Support
    url: https://www.pica8.com/support/
  x-provenance:
    method: derived
    derived-by: API Evangelist enrichment pipeline
    derived-on: '2026-08-26'
    derived-from: 'https://pica8-fs.atlassian.net/wiki/spaces/ampcon/pages/753668/AmpCon+API+document (attachment: AmpCon
      1.12.0 API document 20230625.docx, AmpCon version 1.12.1, update time 2023/06/25)'
    first-party: false
    verbatim: false
    note: Transcribed from the provider's published prose/Word API reference. Not published by Pica8 as OpenAPI.
  x-documentation-gaps:
  - operation: Upgrade switch (section 4.11)
    gap: The URL in the published document is truncated to `https://<ampcon-server-ip>/api/` and the HTTP method field is
      blank. Content-Type is multipart/form-data and the input is `[sn, files]`. The path was NOT guessed and the operation
      is therefore absent from paths[].
  - operation: Group schedule upgrade (section 4.18)
    gap: The URL in the published document is truncated to `https://<ampcon-server-ip>/api/`. Method POST, Content-Type multipart/form-data,
      input `[name, start_date, end_date, files]`. Path not guessed; operation absent from paths[].
  - operation: Run playbook (section 6.4)
    gap: The URL in the published document is truncated to `https://<ampcon-server-ip>/api/`. Method POST, Content-Type application/json,
      input includes playbook_name, playbook_dir, switches[], switch_checkall, group_list[], vars and a scheduled object with
      type DIRECT|ONCE|SCHEDULED. Path not guessed; operation absent from paths[].
  - operation: Get configuration file by name (section 3.4.2)
    gap: The published document gives the same URL (`/api/config_files`) for both the list and the filter-by-name variant,
      with no name parameter. Only the list form is described here.
  - operation: Delete group (section 4.17)
    gap: The published document assigns `POST /api/switch/groups/update` to BOTH group update and group delete. Modelled as
      a single overloaded operation.
  - operation: Update AmpCon login user (section 5.3)
    gap: The published document records the method as GET while also specifying a JSON request body. Transcribed as documented.
externalDocs:
  description: Pica8 AmpCon API document (source of this transcription)
  url: https://pica8-fs.atlassian.net/wiki/spaces/ampcon/pages/753668/AmpCon+API+document
servers:
- url: https://{ampcon-server-ip}
  description: Customer-deployed AmpCon Network Controller. Written `https://<ampcon-server-ip>/` in the source document.
  variables:
    ampcon-server-ip:
      default: ampcon.example.internal
      description: Address of the operator's own AmpCon server.
security:
- bearerAuth: []
tags:
- name: Token
  description: JWT token minting.
- name: Template
  description: Jinja2 configuration templates and their declared variables.
- name: Configuration
  description: Global and per-switch (site) configuration generation and comparison.
- name: Backup
  description: Configuration backup snapshots and rollback.
- name: ConfigurationFile
  description: Configuration files used by the configuration-push function.
- name: Switch
  description: 'Switch inventory and lifecycle: stage, import, DECOM, RMA, logs.'
- name: Group
  description: Switch groups and their permitted action sets.
- name: License
  description: Per-switch and per-group license audit and license application.
- name: Settings
  description: Controller system settings, switch model catalog and user administration.
- name: Playbook
  description: Ansible playbook management.
- name: Job
  description: Ansible playbook execution jobs.
paths:
  /token:
    post:
      operationId: createToken
      summary: Mint a JWT bearer token
      description: 'Exchanges AmpCon web login credentials for a JWT bearer token. Only `superadmin` level users are permitted
        to mint a token and call the API; any other user is refused. The returned token key is sent on every subsequent request
        as `Authorization: Bearer <token>`. An expired or invalid token yields the message `Invalid Token`.'
      tags:
      - Token
      responses:
        '200':
          description: The generated token key.
          content:
            text/plain:
              schema:
                type: string
        '401':
          description: Login credential invalid or the user lacks superadmin permission.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: Username or Password is incorrect
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                password:
                  type: string
              required:
              - username
              - password
            example:
              username: <ampcon-web-login-username>
              password: <ampcon-web-login-password>
      security: []
  /api/templates:
    get:
      operationId: getTemplates
      summary: Get templates list
      description: Returns every configuration template on the AmpCon server, including its Jinja2 body, declared parameters,
        target platform and tag.
      tags:
      - Template
      responses:
        '200':
          description: Template list.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    description:
                      type: string
                    content:
                      type: string
                    j2_template:
                      type: string
                    tag:
                      type: string
                    params:
                      type: string
                    platform:
                      type: string
  /api/templates/{template_name}:
    get:
      operationId: getTemplateByName
      summary: Get template information by name
      description: Returns a single configuration template filtered by name.
      tags:
      - Template
      responses:
        '200':
          description: Template.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    description:
                      type: string
                    content:
                      type: string
                    j2_template:
                      type: string
                    tag:
                      type: string
                    params:
                      type: string
                    platform:
                      type: string
      parameters:
      - name: template_name
        in: path
        required: true
        schema:
          type: string
        description: Template name.
  /api/templates/add:
    post:
      operationId: addTemplate
      summary: Add new template
      description: Creates a new configuration template. Fails when the hardware model named in `platform` has not been configured
        on the controller, or when a template of the same name already exists.
      tags:
      - Template
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: success
                status_code: 200
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: Template <name> exists
                status_code: 500
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                platform:
                  type: string
                content:
                  type: string
                description:
                  type: string
                action:
                  type: string
                  enum:
                  - Config
                  - Delete
              required:
              - name
              - platform
              - content
            example:
              name: <template-name>
              platform: <platform-name>
              content: <jinja2-template-string>
              description: <template-desc>
              action: Config
  /api/templates/update:
    post:
      operationId: updateTemplate
      summary: Update template
      description: 'Updates an existing template. `type` selects what is being replaced: `template_var` rewrites the variable
        definitions (default, type, description, param_check), `j2_template` rewrites the Jinja2 body.'
      tags:
      - Template
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: success
                status_code: 200
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: template_name <name> does not exist
                status_code: 500
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                file_name:
                  type: string
                content: {}
                type:
                  type: string
                  enum:
                  - template_var
                  - j2_template
              required:
              - file_name
              - content
              - type
            example:
              file_name: <template-name>
              content: <jinja2-template-string>
              type: j2_template
  /api/templates/delete:
    post:
      operationId: deleteTemplate
      summary: Delete template
      description: Deletes an existing template by name.
      tags:
      - Template
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: success
                status_code: 200
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: template_name <name> does not exist
                status_code: 500
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
              required:
              - name
            example:
              name: <template-name>
  /api/templates/template_verify:
    post:
      operationId: verifyGeneratedConfiguration
      summary: Compare generated configuration with running or backup configuration
      description: Renders the configuration that the named global template and site templates would generate for a switch
        and diffs it against `running-config` or a backup snapshot.
      tags:
      - Configuration
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                switch:
                  type: string
                global_template:
                  type: string
                site_template:
                  type: array
                  items:
                    type: string
                compare_config:
                  type: string
              required:
              - switch
            example:
              switch: <switch-sn>
              global_template: <global-config-name>
              site_template:
              - <site-template-name-1>
              - <site-template-name-2>
              compare_config: running-config
  /api/global_config:
    get:
      operationId: getGlobalConfigs
      summary: Get global configurations list
      description: Returns every global configuration held by AmpCon, with its raw PICOS configuration body, target switch
        model and default flag.
      tags:
      - Configuration
      responses:
        '200':
          description: Global configuration list.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    config:
                      type: string
                    system_model:
                      type: string
                    type:
                      type: string
                    parent_id:
                      type: string
                    default:
                      type: boolean
  /api/global_config/{global_config_name}:
    get:
      operationId: getGlobalConfigByName
      summary: Get global configuration by name
      description: Returns a single global configuration filtered by name.
      tags:
      - Configuration
      responses:
        '200':
          description: Global configuration.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    config:
                      type: string
                    system_model:
                      type: string
                    type:
                      type: string
                    parent_id:
                      type: string
                    default:
                      type: boolean
      parameters:
      - name: global_config_name
        in: path
        required: true
        schema:
          type: string
        description: Global configuration name.
  /api/global_config/add:
    post:
      operationId: addGlobalConfig
      summary: Add new global configuration
      description: Creates a global configuration for a configured switch model.
      tags:
      - Configuration
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: success
                status_code: 200
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: ERROR:[Create failed, the config already exist!]
                status_code: 500
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                config:
                  type: string
                model_name:
                  type: string
              required:
              - name
              - config
              - model_name
            example:
              name: <Global-config-name>
              config: <Global-config-content>
              model_name: <Global-config-model-name>
  /api/global_config/update:
    post:
      operationId: updateGlobalConfig
      summary: Update global configuration
      description: Replaces the body of an existing global configuration.
      tags:
      - Configuration
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: success
                status_code: 200
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: ERROR:[ Action failed, the config does not exist!]
                status_code: 500
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                config:
                  type: string
                model_name:
                  type: string
              required:
              - name
              - config
              - model_name
            example:
              name: <Global-config-name>
              config: <Global-config-content>
              model_name: <Global-config-model-name>
  /api/global_config/delete:
    post:
      operationId: deleteGlobalConfig
      summary: Delete global configuration
      description: Deletes a global configuration. Refused while the configuration is still in use for a deployment.
      tags:
      - Configuration
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: success
                status_code: 200
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: ERROR:[config is in use!]
                status_code: 500
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
              required:
              - name
            example:
              name: <Global-config-name>
  /api/switch_config:
    get:
      operationId: getSwitchConfigs
      summary: Get switch (site) configuration list
      description: Returns every per-switch (site) configuration generated on AmpCon.
      tags:
      - Configuration
      responses:
        '200':
          description: Site configuration list.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    config:
                      type: string
                    system_model:
                      type: string
                    type:
                      type: string
                    parent_id:
                      type: string
                    default:
                      type: boolean
  /api/switch_config/{switch_config_name}:
    get:
      operationId: getSwitchConfigByName
      summary: Get switch (site) configuration by name
      description: Returns a single per-switch (site) configuration filtered by name.
      tags:
      - Configuration
      responses:
        '200':
          description: Site configuration.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    config:
                      type: string
                    system_model:
                      type: string
                    type:
                      type: string
                    parent_id:
                      type: string
                    default:
                      type: boolean
      parameters:
      - name: switch_config_name
        in: path
        required: true
        schema:
          type: string
        description: Site configuration name.
  /api/switch_config/add:
    post:
      operationId: generateSwitchConfig
      summary: Generate new switch (site) configuration
      description: Generates the deployment configuration for one switch from a global configuration plus one or more templates.
        Once generated, AmpCon uses it to deploy the switch when it registers. `no_generate_template_name` accepts multiple
        templates.
      tags:
      - Configuration
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: success
                status_code: 200
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: ERROR:[Switch <switch_sn> already exist]
                status_code: 500
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                template_info:
                  type: object
                agent_info:
                  type: object
                param:
                  type: object
              required:
              - template_info
            example:
              template_info:
                no_generate_name: test13_site_config
                no_generate_template_name:
                - test
                no_generate_global_config: 2022-2-14-glob-as5812_54x-test1
                no_generate_description: site_config
                no_generate_switch_sn: SNXXXXX
                no_generate_platform: as5812_54x
                no_generate_location: test
              param:
                scheduler_profile: ''
                alias: '123'
              agent_info:
                no_vpn_config: Persistent VPN
                no_retrieve_config: 'True'
                no_hostname_prefix: server
                no_server_domain: pica8.com
                no_uplink_ports: qe-1/1/49,qe-1/1/50,qe-1/1/51,qe-1/1/52
                no_speed: '40000'
                no_vpn_host: 10.1.0.16
                no_vlan: '4094'
                no_native_vlan: '4094'
                no_vpn_enable: 'True'
                no_enable: 'True'
                no_lacp: 'False'
  /api/switch_config/update:
    post:
      operationId: updateSwitchConfig
      summary: Update switch (site) configuration
      description: Updates an existing per-switch (site) configuration on AmpCon.
      tags:
      - Configuration
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
  /api/backup_config/{switch_sn}:
    get:
      operationId: getBackupConfigsBySn
      summary: Get all backup configuration snapshots by serial number
      description: Lists every backup configuration snapshot AmpCon holds for one switch serial number, including snapshot
        tags.
      tags:
      - Backup
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
      parameters:
      - name: switch_sn
        in: path
        required: true
        schema:
          type: string
        description: Switch serial number.
    post:
      operationId: backupSwitchConfiguration
      summary: Back up a switch configuration
      description: Takes a fresh configuration backup snapshot of the named switch.
      tags:
      - Backup
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
      parameters:
      - name: switch_sn
        in: path
        required: true
        schema:
          type: string
        description: Switch serial number.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
  /api/backup_config/{switch_sn}/{backup_date}:
    get:
      operationId: getBackupConfigByDate
      summary: Get a switch backup configuration by serial number and date
      description: Returns one specific backup configuration snapshot for a switch, selected by snapshot date.
      tags:
      - Backup
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
      parameters:
      - name: switch_sn
        in: path
        required: true
        schema:
          type: string
        description: Switch serial number.
      - name: backup_date
        in: path
        required: true
        schema:
          type: string
        description: Backup snapshot date.
  /api/backup_config/rollback:
    post:
      operationId: rollbackBackupConfiguration
      summary: Roll back to a backup configuration
      description: REVERSAL OPERATION. Restores a switch to a previously captured backup configuration snapshot. The published
        document does not state a retention window for snapshots, so the window inside which a rollback remains possible is
        undocumented.
      tags:
      - Backup
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
  /api/compare_config:
    post:
      operationId: compareBackupWithRunningConfig
      summary: Compare a backup configuration with the running configuration
      description: Diffs a stored backup configuration snapshot against the configuration currently running on the switch.
      tags:
      - Configuration
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
  /api/config_files:
    get:
      operationId: getConfigFiles
      summary: Get configuration file list
      description: Returns the configuration files available for the configuration-push function. The published document uses
        this same URL for the filter-by-name variant.
      tags:
      - ConfigurationFile
      responses:
        '200':
          description: Configuration file list.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    content:
                      type: string
                    description:
                      type: string
                    platform:
                      type: string
                    level:
                      type: integer
                    pid:
                      type: integer
  /api/config_files/update:
    post:
      operationId: updateConfigFile
      summary: Update configuration file
      description: Updates the body of a configuration file used for configuration push.
      tags:
      - ConfigurationFile
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
  /api/config_files/delete:
    post:
      operationId: deleteConfigFile
      summary: Delete configuration file
      description: Deletes a configuration file used for configuration push.
      tags:
      - ConfigurationFile
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
  /api/config_files/push:
    post:
      operationId: pushConfigFileToSwitch
      summary: Push configuration file to switch
      description: Pushes a stored configuration file onto one or more switches. The input parameters for this call were corrected
        in the 2022-10-27 revision of the API document.
      tags:
      - ConfigurationFile
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
  /api/switch/all_switch_list:
    get:
      operationId: getAllSwitches
      summary: Get all switch list
      description: Returns every switch known to the AmpCon server with its serial number, hardware id, management and temporary
        IPs, provisioning status, step and PICOS version.
      tags:
      - Switch
      responses:
        '200':
          description: Switch list.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    sn:
                      type: string
                    host_name:
                      type: string
                    hwid:
                      type: string
                    mgt_ip:
                      type: string
                    tmp_ip:
                      type: string
                    link_ip_addr:
                      type: string
                    address:
                      type: string
                    domain:
                      type: string
                    current_user:
                      type: string
                    current_password:
                      type: string
                    remark:
                      type: string
                    status:
                      type: string
                    topology:
                      type: string
                    version:
                      type: string
                    step:
                      type: integer
              example:
              - sn: EC1815000436
                host_name: '1234'
                hwid: BD46-BDF7-DF7B-7435
                mgt_ip: 10.8.0.6
                tmp_ip: 10.8.0.6
                status: Provisioning Success
                step: 6
                topology: '1'
                version: 3.8.0.1
  /api/switch/deployed_switch_list:
    get:
      operationId: getDeployedSwitches
      summary: Get deployed switch list
      description: Returns only the switches that have completed deployment.
      tags:
      - Switch
      responses:
        '200':
          description: Deployed switch list.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    sn:
                      type: string
                    host_name:
                      type: string
                    hwid:
                      type: string
                    mgt_ip:
                      type: string
                    tmp_ip:
                      type: string
                    link_ip_addr:
                      type: string
                    address:
                      type: string
                    domain:
                      type: string
                    current_user:
                      type: string
                    current_password:
                      type: string
                    remark:
                      type: string
                    status:
                      type: string
                    topology:
                      type: string
                    version:
                      type: string
                    step:
                      type: integer
  /api/switch/parkinglot:
    get:
      operationId: getParkingLotSwitches
      summary: Get switches in the parking lot
      description: Returns switches that have powered up and registered with AmpCon but for which no generated configuration
        could be found, with registration counts and history.
      tags:
      - Switch
      responses:
        '200':
          description: Parking-lot switch list.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    sn:
                      type: string
                    ip:
                      type: string
                    model:
                      type: string
                    address:
                      type: string
                    remark:
                      type: string
                    history_time:
                      type: string
                    last_register:
                      type: string
                    register_count:
                      type: integer
                    investigate:
                      type: boolean
  /api/switch/switch_list/{switch_sn}:
    get:
      operationId: getSwitchBySn
      summary: Get switch information by serial number
      description: Returns one switch record filtered by serial number.
      tags:
      - Switch
      responses:
        '200':
          description: Switch.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    sn:
                      type: string
                    host_name:
                      type: string
                    hwid:
                      type: string
                    mgt_ip:
                      type: string
                    tmp_ip:
                      type: string
                    link_ip_addr:
                      type: string
                    address:
                      type: string
                    domain:
                      type: string
                    current_user:
                      type: string
                    current_password:
                      type: string
                    remark:
                      type: string
                    status:
                      type: string
                    topology:
                      type: string
                    version:
                      type: string
                    step:
                      type: integer
      parameters:
      - name: switch_sn
        in: path
        required: true
        schema:
          type: string
        description: Switch serial number.
  /api/switch/stage:
    post:
      operationId: stageSwitch
      summary: Stage a switch
      description: Stages a switch so that AmpCon starts the deployment process the next time that switch registers with the
        server.
      tags:
      - Switch
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: The EC1815000436 staged
                status: 200
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: The EC18150004361 switch does not exist
                status: 500
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sn:
                  type: string
              required:
              - sn
            example:
              sn: EC1815000436
  /api/switch/decom:
    post:
      operationId: decommissionSwitch
      summary: Decommission (DECOM) a switch
      description: REVERSAL OPERATION. Removes the switch from AmpCon management and restores its default settings — the documented
        way to undo a deployment. No time window is stated.
      tags:
      - Switch
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: DECOM success
                status: 200
        '400':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: 'The sn:EC18150004361 switch decom failed, error: cannot find switch EC18150004361'
                status: 400
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                info: cannot connect to switch, please check
                status: '500'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sn:
                  type: string
              required:
              - sn
            example:
              sn: EC1815000436
  /api/switch/rma:
    post:
      operationId: rmaSwitch
      summary: RMA a switch
      description: Transfers a broken switch's saved deployment configuration onto a replacement unit. `staged` controls whether
        the new serial number is staged immediately.
      tags:
      - Switch
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                status: '200'
                msg: RMA Success
        '400':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: new sn number is same as original
                status: 400
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                old_sn:
                  type: string
                new_sn:
                  type: string
                staged:
                  type: string
              required:
              - old_sn
              - new_sn
            example:
              old_sn: EC1703000856
              new_sn: EC1750001004
              staged: 'true'
  /api/switch/log:
    get:
      operationId: getSwitchLogs
      summary: Get AmpCon switch logs
      description: Returns the AmpCon operation log, one entry per event with serial number, timestamp, message, severity
        type and read status.
      tags:
      - Switch
      responses:
        '200':
          description: Operation log.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    sn:
                      type: string
                    msg:
                      type: string
                    history_time:
                      type: string
                    status:
                      type: string
                    type:
                      type: string
                    count:
                      type: integer
  /api/switch/import:
    get:
      operationId: getImportedSwitches
      summary: Get import switch list
      description: Returns the switches that were imported into AmpCon rather than provisioned by zero-touch provisioning.
      tags:
      - Switch
      responses:
        '200':
          description: Imported switch list.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    sn:
                      type: string
                    host_name:
                      type: string
                    hwid:
                      type: string
                    mgt_ip:
                      type: string
                    tmp_ip:
                      type: string
                    link_ip_addr:
                      type: string
                    address:
                      type: string
                    domain:
                      type: string
                    current_user:
                      type: string
                    current_password:
                      type: string
                    remark:
                      type: string
                    status:
                      type: string
                    topology:
                      type: string
                    version:
                      type: string
                    step:
                      type: integer
    post:
      operationId: importSwitch
      summary: Import an already-configured switch
      description: Brings an existing, already-configured switch under AmpCon management by IP address.
      tags:
      - Switch
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: Import success!
                status: 200
        '400':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: sn EC1815000436 already exists in AmpCon
                status: 400
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ip:
                  type: string
              required:
              - ip
            example:
              ip: 10.1.0.22
  /api/switch/license_audit:
    post:
      operationId: auditSwitchLicense
      summary: Audit a switch license
      description: Audits one switch's license status to check whether the license has expired or will expire within 30 days.
      tags:
      - License
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                message: license audit success
                status: 200
        '400':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                message: cannot find switch EC18150010436
                status: 400
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sn:
                  type: string
              required:
              - sn
            example:
              sn: EC1815000436
  /api/switch/license_action:
    post:
      operationId: applySwitchLicense
      summary: Apply the latest license to a switch
      description: Audits the switch license and pushes the latest license from the Pica8 license portal onto the switch.
      tags:
      - License
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                message: license action success
                status: 200
        '400':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                message: cannot find switch EC18150010436
                status: 400
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sn:
                  type: string
              required:
              - sn
            example:
              sn: EC1815000436
  /api/switch/groups:
    get:
      operationId: getSwitchGroups
      summary: Get group information list
      description: Returns every switch group with its permitted action array and member serial numbers.
      tags:
      - Group
      responses:
        '200':
          description: Group list.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    sn:
                      type: array
                      items:
                        type: string
                    action_array:
                      type: array
                      items:
                        type: string
                        enum:
                        - audit
                        - action
                        - upgrading
                        - retrieve_config
              example:
              - name: group_test_1
                action_array:
                - audit
                - action
                - upgrading
                - retrieve_config
                sn:
                - EC1750001004
                - EC1741001625
  /api/switch/groups/add:
    post:
      operationId: addSwitchGroup
      summary: Add group
      description: Creates a switch group. `action_array` restricts which group-scoped operations are permitted; valid values
        are `audit`, `action`, `upgrading` and `retrieve_config`.
      tags:
      - Group
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: group add success
                status: 200
        '400':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: <group-name> group already exist
                status: 400
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                group_name:
                  type: string
                description:
                  type: string
                switches:
                  type: array
                  items:
                    type: string
                action_array:
                  type: array
                  items:
                    type: string
                    enum:
                    - audit
                    - action
                    - upgrading
                    - retrieve_config
              required:
              - group_name
            example:
              action_array:
              - audit
              - action
              group_name: test_group
              description: test
              switches:
              - SNXXXXXX
  /api/switch/groups/update:
    post:
      operationId: updateSwitchGroup
      summary: Update or delete a group
      description: 'Updates an existing switch group. The published document uses this same path and method for group DELETION:
        posting only `{"group_name": "..."}` deletes the group, while posting the full body updates it. That overload is a
        property of the published contract, not of this transcription.'
      tags:
      - Group
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: group update success
                status: 200
        '400':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: <group-name> group does not exist
                status: 400
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                group_name:
                  type: string
                description:
                  type: string
                switches:
                  type: array
                  items:
                    type: string
                action_array:
                  type: array
                  items:
                    type: string
                    enum:
                    - audit
                    - action
                    - upgrading
                    - retrieve_config
              required:
              - group_name
            example:
              action_array:
              - audit
              - action
              - upgrading
              group_name: test_group
              description: test
              switches:
              - SNXXXXXX
  /api/switch/groups/license_audit:
    post:
      operationId: auditGroupLicenses
      summary: Group switch license audit
      description: Runs a license audit across every switch in a group. The audit runs in the background.
      tags:
      - License
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                status: 200
                msg: license audit successful in the background
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: The group not exist
                status: 500
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                group:
                  type: string
              required:
              - group
            example:
              group: test_group
  /api/switch/groups/license_action:
    post:
      operationId: applyGroupLicenses
      summary: Group switch license action
      description: Applies the latest licenses across every switch in a group. The action runs in the background.
      tags:
      - License
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                status: 200
                msg: license action successful in the background
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: The group does not exist
                status: 500
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                group:
                  type: string
              required:
              - group
            example:
              group: test_group
  /api/settings/system_config:
    get:
      operationId: getSystemConfig
      summary: Get system configuration information
      description: 'Returns the AmpCon system configuration: license portal URL and credentials, switch SSH operation credentials,
        security config path and the retrieve-config retention count.'
      tags:
      - Settings
      responses:
        '200':
          description: System configuration.
          content:
            application/json:
              schema:
                type: object
                properties:
                  license_portal_url:
                    type: string
                  license_portal_user:
                    type: string
                  license_portal_password:
                    type: string
                  switch_op_user:
                    type: string
                  switch_op_password:
                    type: string
                  security_config:
                    type: string
                  retrieve_config_num:
                    type: integer
  /api/settings/switch_model:
    get:
      operationId: getSwitchModels
      summary: Get switch model configuration information
      description: Returns every configured switch model with its up-to-date image path and MD5, ONIE installer path, licence
        speed class, feature tier and upgrade scripts.
      tags:
      - Settings
      responses:
        '200':
          description: Switch model configuration list.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    model:
                      type: string
                    feature:
                      type: string
                    speed_for_license:
                      type: string
                    up_to_date_version:
                      type: string
                    up_to_date_image_path:
                      type: string
                    up_to_date_image_md5_path:
                      type: string
                    up_to_date_onie_path:
                      type: string
                    manual_upgrade_scripts:
                      type: string
                    patched_install_script:
                      type: string
                    patched_tar_file:
                      type: string
                    script_file_path:
                      type: string
  /api/settings/update_user:
    get:
      operationId: updateAmpConUser
      summary: Update AmpCon login user
      description: 'Updates an AmpCon user: password, role (`readonly`, `operator`, `admin`, `superadmin`), email and scope.
        `user_type` selects a `group`- or `global`-scoped user; `group_name` is required when `user_type` is `group`. Support
        for specifying the user type was added in the 2023-06-25 revision. NOTE: the published document records the method
        for this call as GET while also specifying a JSON request body — that inconsistency is in Pica8''s document and has
        not been altered here.'
      tags:
      - Settings
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                info: update user success
                status: '200'
        '400':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                msg: <ERROR msg from backend>
                status: '400'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                password:
                  type: string
                user_type:
                  type: string
                  enum:
                  - group
                  - global
                group_name:
                  type: string
                type:
                  type: string
                  enum:
                  - readonly
                  - operator
                  - admin
                  - superadmin
                email:
                  type: string
              required:
              - username
            example:
              username: <ampcon-login-user>
              password: <password>
              user_type: group
              group_name: group1,group2,group3
              type: operator
              email: <email-string>
  /api/ansible/playbooks:
    get:
      operationId: getPlaybooks
      summary: Get playbook information list
      description: Returns every Ansible playbook registered on AmpCon with its name, description, tag and creating user.
      tags:
      - Playbook
      responses:
        '200':
          description: Playbook list.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    description:
                      type: string
                    tag:
                      type: string
                    create_user:
                      type: string
  /api/ansible/playbooks/update:
    post:
      operationId: upsertPlaybook
      summary: Create or update a playbook
      description: Uploads a playbook ZIP archive. If the playbook name does not exist it is created; if it exists its content
        is overwritten.
      tags:
      - Playbook
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                info: Success to update playbook "test"
                status: '200'
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                info: cannot unzip the upload playbook zip file.
                status: '500'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                import_playbook_file:
                  type: string
                  format: binary
                playbook_name:
                  type: string
                playbook_description:
                  type: string
              required:
              - playbook_name
  /api/ansible/playbooks/delete:
    post:
      operationId: deletePlaybook
      summary: Delete a playbook
      description: Deletes the named playbook and its folder.
      tags:
      - Playbook
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                info: Success to delete playbook.
                status: '200'
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
              example:
                info: name XXX does not exist in database.
                status: '500'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                playbook_name:
                  type: string
              required:
              - playbook_name
            example:
              playbook_name: <playbook-name>
  /api/ansible/jobs:
    get:
      operationId: getJobs
      summary: Get job information list
      description: Returns the list of playbook execution jobs on AmpCon.
      tags:
      - Job
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
  /api/ansible/jobs/delete:
    post:
      operationId: removeJob
      summary: Remove a job
      description: Removes a playbook execution job.
      tags:
      - Job
      responses:
        '200':
          description: Success. AmpCon returns a message plus a status/status_code field in the body; the HTTP status line
            is not the primary error signal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
        '500':
          description: Documented error response. AmpCon reports the failure in the body (`status` / `status_code` of 400
            or 500) alongside a human-readable message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  status_code:
                    type: integer
                  status:
                    type: integer
                  info:
                    type: string
                  message:
                    type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT minted by POST /token from AmpCon web login credentials. Only `superadmin` level users may mint a
        token. Sent as `Authorization: Bearer <token>`. An expired or invalid token returns the message `Invalid Token`.'