openapi: 3.1.0
info:
  title: SPX Graphics Control Data API
  description: The SPX Graphics Control REST API provides external control over the SPX-GC (SPX Graphics Controller) system for live video productions and live streams. It allows external applications and devices such as the Elgato Stream Deck to trigger graphics playback, control rundowns, manage templates, load projects, and interact with custom SPX extensions. The API runs locally at http://localhost:5656 and supports optional API key authentication via URL parameter.
  version: '1.0'
  contact:
    name: SPX Graphics Support
    url: https://spxgc.tawk.help/
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: http://localhost:5656
  description: Local SPX-GC Instance (default port)
- url: http://localhost:5000
  description: Legacy Local SPX-GC Instance
security: []
tags:
- name: Data
  description: Save and load custom JSON data
paths:
  /api/v1/saveCustomJSON:
    post:
      operationId: saveCustomJSON
      summary: Save Custom JSON
      description: Saves arbitrary JSON data to disk for persistence in app extensions. This POST handler can be used to store state that persists across SPX restarts, such as scores, counters, or configuration data.
      tags:
      - Data
      parameters:
      - $ref: '#/components/parameters/apikey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomJSONRequest'
      responses:
        '200':
          description: Custom JSON saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
  /api/v1/feedproxy:
    get:
      operationId: feedProxy
      summary: Feed Proxy
      description: A proxy endpoint that forwards HTTP requests to external URLs, supporting custom headers for authentication. Useful for working around CORS restrictions when fetching external data feeds for template population.
      tags:
      - Data
      parameters:
      - name: url
        in: query
        description: The target URL to proxy the request to
        required: true
        schema:
          type: string
          format: uri
      - $ref: '#/components/parameters/apikey'
      responses:
        '200':
          description: Proxied response from external URL
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    CustomJSONRequest:
      type: object
      description: Arbitrary JSON data payload to persist to disk
      properties:
        filename:
          type: string
          description: Name of the JSON file to save (without extension)
          example: scores
        data:
          type: object
          description: JSON data to persist
          additionalProperties: true
      required:
      - filename
      - data
    SuccessResponse:
      type: object
      description: Standard SPX API success response
      properties:
        status:
          type: string
          description: Response status
          example: ok
        message:
          type: string
          description: Human-readable status message
          example: Command executed successfully
  parameters:
    apikey:
      name: apikey
      in: query
      description: API key for authentication. Required only if the SPX configuration has an apikey value set. Leave empty if no restriction is configured.
      required: false
      schema:
        type: string
externalDocs:
  description: SPX Graphics API Documentation
  url: https://spxgc.tawk.help/article/help-api