Pica8 Configuration API

openapi: 3.2.0
info:
  title: Pica8 AmpCon Network Controller Configuration 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.
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: Configuration
  description: Global and per-switch (site) configuration generation and comparison.
paths:
  /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/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
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`.'
externalDocs:
  description: Pica8 AmpCon API document (source of this transcription)
  url: https://pica8-fs.atlassian.net/wiki/spaces/ampcon/pages/753668/AmpCon+API+document