{
 "openapi": "3.1.0",
 "info": {
  "title": "Run Memory",
  "version": "1.0.0",
  "description": "Checkpoint and resume for AI agent runs. Save state after each step; when a run crashes, resume hands back the last step, state and finished items so it picks up where it left off instead of starting over. Free watch-only mode shows exactly what would be saved; Pro (All Access, $49 a month) saves and resumes. Free 500/day; Pro via All Access $49/month: https://cloudforbots.com/offer"
 },
 "servers": [
  {
   "url": "https://memory.cloudforbots.com"
  }
 ],
 "components": {
  "securitySchemes": {
   "bearer": {
    "type": "http",
    "scheme": "bearer"
   }
  }
 },
 "paths": {
  "/api/run/save_checkpoint": {
   "post": {
    "operationId": "save_checkpoint",
    "summary": "Call after each completed step with the state you would need to continue (cursor, ids done, partial results; up to 256 KB JSON)",
    "description": "Call after each completed step with the state you would need to continue (cursor, ids done, partial results; up to 256 KB JSON). Pro saves it (last 20 per run, kept 30 days). Free watch-only saves nothing and returns would_save: exactly what would have been stored. Never put passwords or API keys in state.",
    "security": [
     {},
     {
      "bearer": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "run_id": {
          "type": "string",
          "description": "A stable id for this job that survives a crash, e.g. \"invoice-import-oct\". Use the same id when you restart."
         },
         "step": {
          "type": "string",
          "description": "The step you just finished, e.g. \"imported page 3 of 10\"."
         },
         "state": {
          "type": "object",
          "description": "JSON state needed to resume."
         },
         "done": {
          "type": "array",
          "items": {
           "type": "string"
          },
          "description": "Optional list of completed item ids, so a resume skips them."
         }
        },
        "required": [
         "run_id",
         "step",
         "state"
        ]
       }
      }
     }
    },
    "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/resume": {
   "post": {
    "operationId": "resume",
    "summary": "Call FIRST when a run starts",
    "description": "Call FIRST when a run starts. If a checkpoint exists for run_id (Pro), returns the last step, state and done list: continue from there and skip finished work. If none, start fresh.",
    "security": [
     {},
     {
      "bearer": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "run_id": {
          "type": "string",
          "description": "A stable id for this job that survives a crash, e.g. \"invoice-import-oct\". Use the same id when you restart."
         }
        },
        "required": [
         "run_id"
        ]
       }
      }
     }
    },
    "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/list_checkpoints": {
   "post": {
    "operationId": "list_checkpoints",
    "summary": "List recent checkpoints (step, size, time) for one run or all runs on your key.",
    "description": "List recent checkpoints (step, size, time) for one run or all runs on your key.",
    "security": [
     {},
     {
      "bearer": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "run_id": {
          "type": "string",
          "description": "A stable id for this job that survives a crash, e.g. \"invoice-import-oct\". Use the same id when you restart."
         }
        }
       }
      }
     }
    },
    "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": "Draft a plain-English report of the last 7 days: runs, checkpoints saved (Pro) or that would have been saved (free)",
    "description": "Draft a plain-English report of the last 7 days: runs, checkpoints saved (Pro) or that would have been saved (free). Read-only; sends nothing.",
    "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"
     }
    }
   }
  }
 }
}