{
  "openrpc": "1.2.6",
  "info": {
    "title": "Circle WebSocket Server API",
    "version": "0.2.0",
    "description": "API for interacting with a Circle's WebSocket server, supporting script execution and comprehensive job management."
  },
  "methods": [
    {
      "name": "fetch_nonce",
      "summary": "Fetches a nonce for authentication purposes.",
      "params": [
        {
          "name": "pubkey",
          "description": "The public key to fetch a nonce for.",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "result": {
        "name": "nonceResult",
        "description": "The nonce string for authentication.",
        "schema": {
          "type": "string"
        }
      }
    },
    {
      "name": "authenticate",
      "summary": "Authenticates a user with public key and signature.",
      "params": [
        {
          "name": "pubkey",
          "description": "The public key of the user.",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "signature",
          "description": "The signature for authentication.",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "result": {
        "name": "authResult",
        "description": "Authentication result.",
        "schema": {
          "type": "boolean"
        }
      }
    },
    {
      "name": "whoami",
      "summary": "Gets authentication status and user information.",
      "params": [],
      "result": {
        "name": "whoamiResult",
        "description": "User authentication information.",
        "schema": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    {
      "name": "play",
      "summary": "Executes a Rhai script on the server and returns the result immediately.",
      "params": [
        {
          "name": "script",
          "description": "The Rhai script to execute.",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "result": {
        "name": "playResult",
        "description": "The output from the executed Rhai script.",
        "schema": {
          "$ref": "#/components/schemas/PlayResult"
        }
      },
      "examples": [
        {
          "name": "Simple Script Execution",
          "params": [
            {
              "name": "script",
              "value": "let x = 10; x * 2"
            }
          ],
          "result": {
            "name": "playResult",
            "value": {
              "output": "20"
            }
          }
        }
      ]
    },
    {
      "name": "create_job",
      "summary": "Creates a new job without starting it.",
      "params": [
        {
          "name": "job",
          "description": "The job to create.",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/Job"
          }
        }
      ],
      "result": {
        "name": "createJobResult",
        "description": "The ID of the created job.",
        "schema": {
          "type": "string"
        }
      }
    },
    {
      "name": "start_job",
      "summary": "Starts a previously created job.",
      "params": [
        {
          "name": "job_id",
          "description": "The ID of the job to start.",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "result": {
        "name": "startJobResult",
        "description": "Confirmation that the job was started.",
        "schema": {
          "type": "object",
          "properties": {
            "success": {
              "type": "boolean",
              "description": "Whether the job was successfully started."
            }
          },
          "required": ["success"]
        }
      }
    },
    {
      "name": "run_job",
      "summary": "Creates and runs a job, returning the result when complete.",
      "params": [
        {
          "name": "script",
          "description": "The script content to execute.",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "script_type",
          "description": "The type of script (HeroScript, RhaiSAL, or RhaiDSL).",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/ScriptType"
          }
        },
        {
          "name": "prerequisites",
          "description": "List of job IDs that must complete before this job can run.",
          "required": false,
          "schema": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      ],
      "result": {
        "name": "runJobResult",
        "description": "The job execution result.",
        "schema": {
          "type": "string"
        }
      }
    },
    {
      "name": "get_job_status",
      "summary": "Gets the current status of a job.",
      "params": [
        {
          "name": "job_id",
          "description": "The ID of the job to check.",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "result": {
        "name": "jobStatus",
        "description": "The current job status.",
        "schema": {
          "$ref": "#/components/schemas/JobStatus"
        }
      }
    },
    {
      "name": "get_job_output",
      "summary": "Gets the output of a completed job.",
      "params": [
        {
          "name": "job_id",
          "description": "The ID of the job to get output for.",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "result": {
        "name": "jobOutput",
        "description": "The job output, if available.",
        "schema": {
          "type": "string"
        }
      }
    },
    {
      "name": "get_job_logs",
      "summary": "Gets the logs of a job.",
      "params": [
        {
          "name": "job_id",
          "description": "The ID of the job to get logs for.",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "result": {
        "name": "jobLogs",
        "description": "The job logs, if available.",
        "schema": {
          "$ref": "#/components/schemas/JobLogsResult"
        }
      }
    },
    {
      "name": "list_jobs",
      "summary": "Lists all job IDs in the system.",
      "params": [],
      "result": {
        "name": "jobList",
        "description": "List of all jobs.",
        "schema": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/Job"
          }
        }
      }
    },
    {
      "name": "stop_job",
      "summary": "Stops a running job.",
      "params": [
        {
          "name": "job_id",
          "description": "The ID of the job to stop.",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "result": {
        "name": "stopJobResult",
        "description": "Confirmation that the stop request was sent.",
        "schema": {
          "type": "null"
        }
      }
    },
    {
      "name": "delete_job",
      "summary": "Deletes a job from the system.",
      "params": [
        {
          "name": "job_id",
          "description": "The ID of the job to delete.",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "result": {
        "name": "deleteJobResult",
        "description": "Confirmation that the job was deleted.",
        "schema": {
          "type": "null"
        }
      }
    },
    {
      "name": "clear_all_jobs",
      "summary": "Clears all jobs from the system.",
      "params": [],
      "result": {
        "name": "clearJobsResult",
        "description": "Information about the cleared jobs.",
        "schema": {
          "type": "null"
        }
      }
    }
  ],
  "components": {
    "schemas": {
      "PlayResult": {
        "type": "object",
        "properties": {
          "output": {
            "type": "string",
            "description": "The string representation of the Rhai script's evaluation result."
          }
        },
        "required": ["output"]
      },
      "ScriptType": {
        "type": "string",
        "enum": ["HeroScript", "RhaiSAL", "RhaiDSL"],
        "description": "The type of script to execute."
      },
      "JobStatus": {
        "type": "string",
        "enum": ["Dispatched", "WaitingForPrerequisites", "Started", "Error", "Finished"],
        "description": "The current status of a job."
      },
      "Job": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the job."
          },
          "caller_id": {
            "type": "string",
            "description": "ID of the caller who created this job."
          },
          "context_id": {
            "type": "string",
            "description": "Context ID for the job execution."
          },
          "script": {
            "type": "string",
            "description": "The script content to execute."
          },
          "script_type": {
            "$ref": "#/components/schemas/ScriptType"
          },
          "timeout": {
            "type": "integer",
            "description": "Timeout in seconds for script execution."
          },
          "retries": {
            "type": "integer",
            "description": "Number of retries on script execution failure."
          },
          "concurrent": {
            "type": "boolean",
            "description": "Whether to execute script in separate thread."
          },
          "log_path": {
            "type": "string",
            "description": "Path to write logs of script execution to."
          },
          "env_vars": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Environment variables for script execution."
          },
          "prerequisites": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Job IDs that must complete before this job can run."
          },
          "dependents": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Job IDs that depend on this job completing."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp when the job was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp when the job was last updated."
          }
        },
        "required": ["id", "caller_id", "context_id", "script", "script_type", "timeout", "retries", "concurrent", "env_vars", "prerequisites", "dependents", "created_at", "updated_at"]
      },
      "JobLogsResult": {
        "type": "object",
        "properties": {
          "logs": {
            "type": ["string", "null"],
            "description": "The job logs, null if not available."
          }
        },
        "required": ["logs"]
      }
    }
  }
}