{
  "openapi": "3.1.0",
  "info": {
    "title": "workerfuse guard API",
    "version": "1.0.0",
    "description": "A paired workerfuse guard posts each run's per-script spend estimates, pauses and alerts. The response carries the hosted limits and queued commands for that Cloudflare account. Agents that read spend or change limits should use the MCP server at https://workerfuse.com/mcp. See https://workerfuse.com/developers.",
    "contact": { "email": "support@workerfuse.com", "url": "https://workerfuse.com/contact" }
  },
  "servers": [{ "url": "https://workerfuse.com" }],
  "externalDocs": { "url": "https://workerfuse.com/developers" },
  "security": [{ "apiKey": [] }],
  "paths": {
    "/api/report": {
      "post": {
        "operationId": "postRunReport",
        "summary": "Send a guard run report and get the hosted config",
        "description": "Stores the report under the login that owns the API key. The first valid report for a Cloudflare account starts its 14-day trial. Acknowledged commands are marked done.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunReport" } } }
        },
        "responses": {
          "200": { "description": "Hosted config for the next run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardConfig" } } } },
          "400": { "description": "Invalid JSON or invalid report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Missing or unknown API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "Another managed login owns this Cloudflare account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "413": { "description": "The report is larger than 1 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": { "type": "http", "scheme": "bearer", "description": "The wf_ API key from signup. See https://workerfuse.com/auth.md." }
    },
    "schemas": {
      "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" } } },
      "Uuid": { "type": "string", "pattern": "^[a-f0-9-]{36}$" },
      "RunReport": {
        "type": "object",
        "required": ["accountId", "scripts", "pauses", "alerts"],
        "properties": {
          "accountId": { "type": "string", "pattern": "^[a-f0-9]{32}$", "description": "Cloudflare account ID, not the workerfuse login ID." },
          "guardVersion": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
          "usageError": { "type": "string", "maxLength": 16384, "description": "Set when the guard could not read usage on this run." },
          "scripts": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["scriptName", "hourlyUsd", "dailyUsd"],
              "properties": {
                "scriptName": { "type": "string", "minLength": 1, "maxLength": 16384 },
                "hourlyUsd": { "type": "number", "minimum": 0, "description": "Estimated cost in the last hour." },
                "dailyUsd": { "type": "number", "minimum": 0, "description": "Estimated cost since 00:00 UTC." }
              }
            }
          },
          "pauses": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["scriptName", "reason"],
              "properties": {
                "scriptName": { "type": "string", "minLength": 1, "maxLength": 16384 },
                "reason": { "type": "string", "minLength": 1, "maxLength": 16384 },
                "id": { "$ref": "#/components/schemas/Uuid" },
                "versionId": { "$ref": "#/components/schemas/Uuid" },
                "stubVersionId": { "$ref": "#/components/schemas/Uuid" },
                "resumable": { "type": "boolean" }
              }
            }
          },
          "alerts": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["subject", "text"],
              "properties": {
                "subject": { "type": "string", "minLength": 1, "maxLength": 16384 },
                "text": { "type": "string", "minLength": 1, "maxLength": 16384 }
              }
            }
          },
          "acknowledgedCommands": { "type": "array", "items": { "$ref": "#/components/schemas/Uuid" } },
          "resumedPauses": { "type": "array", "items": { "$ref": "#/components/schemas/Uuid" } }
        }
      },
      "GuardLimits": {
        "type": "object",
        "required": ["hourlyUsd", "dailyUsd", "storageUsd", "skip", "dryRun"],
        "properties": {
          "hourlyUsd": { "type": "number", "minimum": 0 },
          "dailyUsd": { "type": "number", "minimum": 0 },
          "storageUsd": { "type": "number", "minimum": 0 },
          "skip": { "type": "array", "items": { "type": "string" } },
          "dryRun": { "type": "boolean" },
          "d1RowsPerDay": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }
        }
      },
      "GuardConfig": {
        "type": "object",
        "required": ["plan", "limits", "commands"],
        "properties": {
          "plan": { "type": "string", "enum": ["active", "lapsed"] },
          "limits": { "oneOf": [{ "$ref": "#/components/schemas/GuardLimits" }, { "type": "null" }] },
          "commands": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "type", "scriptName"],
              "properties": {
                "id": { "$ref": "#/components/schemas/Uuid" },
                "type": { "type": "string", "enum": ["pause", "resume"] },
                "scriptName": { "type": "string" },
                "versionId": { "type": "string", "description": "Resume only: the pre-pause version." },
                "stubVersionId": { "type": "string", "description": "Resume only: the stub version." }
              }
            }
          },
          "openPauses": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "scriptName", "stubVersionId"],
              "properties": { "id": { "type": "string" }, "scriptName": { "type": "string" }, "stubVersionId": { "type": "string" } }
            }
          }
        }
      }
    }
  }
}
