{
 "openapi": "3.1.0",
 "info": {
  "title": "Sandbox Timer",
  "version": "1.0.0",
  "description": "Idle-sandbox guard for AI agents. Your agent sends its running E2B, Vercel Sandbox, Daytona or Modal sessions; Sandbox Timer flags the idle ones, shows what idle time cost at the hourly rates you give it, and with Pro at $9 a month returns the ready-to-run kill call for each. A guard on top of your sandboxes, not a sandbox. It never holds your provider keys. Free 500/day; Pro $9/month: https://pay.instaloops.com/b/3cI3cv55uffh0ez4Kr83C3C"
 },
 "servers": [
  {
   "url": "https://timer.cloudforbots.com"
  }
 ],
 "components": {
  "securitySchemes": {
   "bearer": {
    "type": "http",
    "scheme": "bearer"
   }
  }
 },
 "paths": {
  "/api/run/track_sessions": {
   "post": {
    "operationId": "track_sessions",
    "summary": "Send your agent's running sandbox sessions (up to 200; call it on a heartbeat, e.g",
    "description": "Send your agent's running sandbox sessions (up to 200; call it on a heartbeat, e.g. every 5 minutes) and get back which are idle past your threshold or over their max lifetime, the dollars idle time has cost at the hourly rates you pass, and what to do. Pro acts: returns a ready-to-run kill call per idle sandbox for its provider (E2B kill, Vercel Sandbox stop, Daytona stop, Modal terminate) and POSTs one alert per sandbox to your webhook. Free watch-only returns would_kill and sends nothing. We never hold provider keys and never kill anything ourselves: your agent runs the call with its own key.",
    "security": [
     {},
     {
      "bearer": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "fleet": {
          "type": "string",
          "description": "A stable name for this group of sandboxes, e.g. \"my-agent\". State and rules are kept per fleet."
         },
         "sessions": {
          "type": "array",
          "items": {
           "type": "object",
           "properties": {
            "id": {
             "type": "string",
             "description": "Sandbox id as your provider returns it (E2B sandboxId, Vercel sandbox name, Daytona id or name, Modal object_id)."
            },
            "provider": {
             "type": "string",
             "description": "e2b, vercel, daytona, modal, or any other name."
            },
            "idle_minutes": {
             "type": "number",
             "description": "Minutes since the sandbox last did work (a command, a request). Or pass last_activity_at."
            },
            "last_activity_at": {
             "type": "string",
             "description": "ISO time of the last work in the sandbox (instead of idle_minutes)."
            },
            "age_minutes": {
             "type": "number",
             "description": "Minutes since it started (or pass started_at). Used for max lifetime."
            },
            "started_at": {
             "type": "string",
             "description": "ISO start time (instead of age_minutes)."
            },
            "rate_per_hour": {
             "type": "number",
             "description": "What this sandbox costs you per hour in USD, from your provider's price page or bill. Optional; without it we count minutes, not dollars."
            },
            "status": {
             "type": "string",
             "description": "running (default), paused or stopped. Paused and stopped sessions are skipped."
            },
            "label": {
             "type": "string",
             "description": "Optional human name, e.g. \"repo-tests\"."
            },
            "session_id": {
             "type": "string",
             "description": "Vercel only: the current session id, used in the REST stop call."
            }
           },
           "required": [
            "id"
           ]
          }
         },
         "idle_minutes": {
          "type": "integer",
          "description": "Idle minutes before a sandbox counts as idle. Default 15 (or your saved Pro rule)."
         },
         "max_lifetime_minutes": {
          "type": "integer",
          "description": "Optional: flag sandboxes running longer than this, idle or not."
         },
         "rates_per_hour": {
          "type": "object",
          "description": "Optional default USD per hour by provider, e.g. {\"e2b\": 0.17}. Your own numbers; per-session rate_per_hour wins."
         },
         "alert_webhook": {
          "type": "string",
          "description": "https URL Pro posts the idle alert (with the kill call) to."
         }
        },
        "required": [
         "sessions"
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Result with job, understood, outcome, usage",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "bad_agent_key"
     },
     "429": {
      "description": "free_limit_reached (includes upgrade link)"
     }
    }
   }
  },
  "/api/run/idle_report": {
   "post": {
    "operationId": "idle_report",
    "summary": "Which sandboxes were flagged idle and what idle time cost, per provider, from what track_sessions has seen",
    "description": "Which sandboxes were flagged idle and what idle time cost, per provider, from what track_sessions has seen. Without an API key pass fleet. With a key: every fleet on it. Free shows 7 days, Pro 30.",
    "security": [
     {},
     {
      "bearer": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "fleet": {
          "type": "string",
          "description": "A stable name for this group of sandboxes, e.g. \"my-agent\". State and rules are kept per fleet."
         },
         "days": {
          "type": "integer",
          "description": "1-30 (free max 7)."
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Result with job, understood, outcome, usage",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "bad_agent_key"
     },
     "429": {
      "description": "free_limit_reached (includes upgrade link)"
     }
    }
   }
  },
  "/api/run/set_idle_rules": {
   "post": {
    "operationId": "set_idle_rules",
    "summary": "Pro: save the rules track_sessions applies to a fleet: idle_minutes threshold, max_lifetime_minutes, default rates_per_hour by provider, and alert_webhook",
    "description": "Pro: save the rules track_sessions applies to a fleet: idle_minutes threshold, max_lifetime_minutes, default rates_per_hour by provider, and alert_webhook. Free returns a preview of the rules and saves nothing (pass the same values on each track_sessions call instead).",
    "security": [
     {},
     {
      "bearer": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "fleet": {
          "type": "string",
          "description": "A stable name for this group of sandboxes, e.g. \"my-agent\". State and rules are kept per fleet."
         },
         "idle_minutes": {
          "type": "integer"
         },
         "max_lifetime_minutes": {
          "type": "integer"
         },
         "rates_per_hour": {
          "type": "object"
         },
         "alert_webhook": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Result with job, understood, outcome, usage",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "bad_agent_key"
     },
     "429": {
      "description": "free_limit_reached (includes upgrade link)"
     }
    }
   }
  },
  "/api/run/weekly_report": {
   "post": {
    "operationId": "weekly_report",
    "summary": "Plain-English summary of the last 7 days: sandboxes watched, how many sat idle, dollars idle time cost at your rates, kill calls returned (Pro) or that would have been (free)",
    "description": "Plain-English summary of the last 7 days: sandboxes watched, how many sat idle, dollars idle time cost at your rates, kill calls returned (Pro) or that would have been (free). Read-only; sends nothing. Needs a free API key.",
    "security": [
     {},
     {
      "bearer": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {}
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Result with job, understood, outcome, usage",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "bad_agent_key"
     },
     "429": {
      "description": "free_limit_reached (includes upgrade link)"
     }
    }
   }
  },
  "/api/key": {
   "post": {
    "operationId": "get_free_key",
    "summary": "Get a free API key",
    "responses": {
     "200": {
      "description": "api_key"
     }
    }
   }
  }
 }
}