openapi: 3.1.0
info:
  title: SPX Graphics Control Data Extensions 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: Extensions
  description: Invoke functions in custom SPX extensions
paths:
  /api/v1/invokeExtensionFunction:
    post:
      operationId: invokeExtensionFunction
      summary: Invoke Extension Function
      description: Invokes an exposed function in a custom-built SPX extension. This allows external devices such as Stream Deck buttons to drive custom extension logic, enabling advanced applications like sports scoring and live timing. Introduced in v1.3.
      tags:
      - Extensions
      parameters:
      - $ref: '#/components/parameters/apikey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtensionFunctionRequest'
      responses:
        '200':
          description: Extension function invoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
components:
  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
  schemas:
    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
    ExtensionFunctionRequest:
      type: object
      description: Request to invoke a function defined in an SPX extension
      properties:
        extension:
          type: string
          description: Name of the SPX extension
          example: SportsScoring
        function:
          type: string
          description: Name of the function to invoke within the extension
          example: incrementScore
        params:
          type: object
          description: Optional parameters to pass to the function
          additionalProperties: true
      required:
      - extension
      - function
externalDocs:
  description: SPX Graphics API Documentation
  url: https://spxgc.tawk.help/article/help-api