{
  "openapi": "3.1.0",
  "info": {
    "title": "RefurbSitter Agent API",
    "version": "1.0.0",
    "description": "Free and Spot can read account and catalog and create checkout links through REST. Spot can manage one watch through MCP. Hunt, Fleet and Reseller can manage watches through REST and MCP and configure one webhook URL per account. REST, signup, and MCP share a per-IP rate limit. Authenticated requests also share one budget per account across REST and MCP. Request bodies are limited to 64 KiB.",
    "termsOfService": "https://refurbsitter.com/terms"
  },
  "servers": [{"url": "https://refurbsitter.com/api/agent/v1"}],
  "security": [{"agentKey": []}],
  "paths": {
    "/signup": {
      "post": {
        "operationId": "start_signup",
        "summary": "Send a one-time code to the account owner's mailbox",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {"type": "string", "format": "email"},
                  "label": {
                    "type": "string",
                    "description": "Optional label, up to 80 UTF-8 bytes after trimming."
                  }
                },
                "required": ["email"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "flow_id": {
                      "type": "string",
                      "description": "Opaque flow ID. Keep it with the signup request and submit it unchanged."
                    }
                  },
                  "required": ["flow_id"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "403": {
            "description": "Origin, channel, or checkout is forbidden",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "413": {
            "description": "Email too long or request body exceeds 64 KiB",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "415": {
            "description": "Expected application/json",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "422": {
            "description": "Invalid email",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "429": {
            "description": "Rate limited",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "503": {
            "description": "Service temporarily unavailable or Agent API disabled",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          }
        }
      }
    },
    "/signup/verify": {
      "post": {
        "operationId": "verify_signup",
        "summary": "Verify the six-digit code and issue an API key",
        "description": "The code expires after ten minutes. Each code allows up to five guesses.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "flow_id": {
                    "type": "string",
                    "description": "Opaque flow ID. Keep it with the signup request and submit it unchanged."
                  },
                  "code": {"type": "string", "pattern": "^[0-9]{6}$"}
                },
                "required": ["flow_id", "code"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IssuedKey"}}}
          },
          "400": {
            "description": "Invalid request",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "403": {
            "description": "Origin, channel, or checkout is forbidden",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "409": {
            "description": "Operation conflicts with current account state",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "413": {"$ref": "#/components/responses/BodyTooLarge"},
          "415": {
            "description": "Expected application/json",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "429": {
            "description": "Rate limited",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "503": {
            "description": "Service temporarily unavailable or Agent API disabled",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          }
        }
      }
    },
    "/account": {
      "get": {
        "operationId": "get_account",
        "summary": "Read account and plan state",
        "responses": {
          "200": {
            "description": "Success",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Account"}}}
          },
          "401": {
            "description": "Missing, invalid, or revoked key",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "429": {
            "description": "Rate limited",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "503": {
            "description": "Service temporarily unavailable or Agent API disabled",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          }
        }
      }
    },
    "/catalog": {
      "get": {
        "operationId": "list_catalog",
        "summary": "List products and watchable configurations",
        "responses": {
          "200": {
            "description": "Success",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Catalog"}}}
          },
          "401": {
            "description": "Missing, invalid, or revoked key",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "429": {
            "description": "Rate limited",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "503": {
            "description": "Service temporarily unavailable or Agent API disabled",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          }
        }
      }
    },
    "/watches": {
      "get": {
        "operationId": "list_watches",
        "summary": "List this account's restock watches",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {"watches": {"type": "array", "items": {"$ref": "#/components/schemas/Watch"}}},
                  "required": ["watches"]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or revoked key",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "402": {
            "description": "Payment required for Free accounts",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "403": {
            "description": "Hunt is the minimum plan for this REST operation",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "429": {
            "description": "Rate limited",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "503": {
            "description": "Service temporarily unavailable or Agent API disabled",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          }
        }
      },
      "post": {
        "operationId": "create_watch",
        "summary": "Create a restock watch",
        "description": "Send a config_id from the catalog and the desired channels. The API fills the family and configuration fields from the catalog.",
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WatchInput"}}}
        },
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {"watch": {"$ref": "#/components/schemas/Watch"}},
                  "required": ["watch"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {
            "description": "Missing, invalid, or revoked key",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "402": {
            "description": "Payment required for Free accounts, watch quota reached, or paid access paused",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "403": {
            "description": "Hunt is the minimum plan for this REST operation, or the channel is unavailable",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "413": {"$ref": "#/components/responses/BodyTooLarge"},
          "415": {
            "description": "Expected application/json",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "429": {
            "description": "Rate limited",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "503": {
            "description": "Service temporarily unavailable or Agent API disabled",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          }
        }
      }
    },
    "/watches/{id}": {
      "get": {
        "operationId": "get_watch",
        "summary": "Get this account's watch",
        "parameters": [{"name": "id", "in": "path", "required": true, "description": "Use the ID returned by the watch list.", "schema": {"type": ["string", "integer"]}}],
        "responses": {
          "200": {
            "description": "Watch details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {"watch": {"$ref": "#/components/schemas/Watch"}},
                  "required": ["watch"]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or revoked key",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "402": {
            "description": "Payment required for Free accounts",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "403": {
            "description": "Hunt is the minimum plan for this REST operation",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {
            "description": "watch_not_found for an invalid ID or a watch that does not exist in this account",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "429": {
            "description": "Rate limited",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "503": {
            "description": "Service temporarily unavailable or Agent API disabled",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          }
        }
      },
      "delete": {
        "operationId": "delete_watch",
        "summary": "Delete this account's watch",
        "parameters": [{"name": "id", "in": "path", "required": true, "description": "Use the ID returned by the watch list.", "schema": {"type": ["string", "integer"]}}],
        "responses": {
          "204": {"description": "Success"},
          "401": {
            "description": "Missing, invalid, or revoked key",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "402": {
            "description": "Payment required for Free accounts",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "403": {
            "description": "Hunt is the minimum plan for this REST operation",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {
            "description": "watch_not_found for an invalid ID or a watch that does not exist in this account",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "429": {
            "description": "Rate limited",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "503": {
            "description": "Service temporarily unavailable or Agent API disabled",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          }
        }
      }
    },
    "/webhook": {
      "put": {
        "operationId": "set_webhook",
        "summary": "Set or clear a webhook or rotate its signing secret",
        "description": "Available on Hunt, Fleet and Reseller. Each account can configure one webhook URL. Changing the URL rotates the signing secret and returns the new secret. Set rotate_secret to true and omit webhook_url to rotate the current secret. A watch must select the webhook channel to send alerts. Check that X-RefurbSitter-Timestamp is recent. Compare X-RefurbSitter-Signature in constant time against v1= followed by the hex HMAC-SHA256 of the timestamp, a period, and the raw body. Deduplicate verified deliveries using the id field in the signed JSON body. The X-RefurbSitter-Event-Id header is a copy.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "webhook_url": {
                    "type": ["string", "null"],
                    "format": "uri",
                    "description": "HTTPS destination. Use null to clear the destination and its secret."
                  },
                  "rotate_secret": {"type": "boolean"}
                },
                "anyOf": [
                  {"required": ["webhook_url"]},
                  {"required": ["rotate_secret"], "properties": {"rotate_secret": {"const": true}}}
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "webhook_configured": {"type": "boolean"},
                    "signing_secret": {
                      "type": "string",
                      "description": "Returned once when a secret is created or rotated. Use it as a UTF-8 string when computing the HMAC."
                    }
                  },
                  "required": ["webhook_configured"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {
            "description": "Missing, invalid, or revoked key",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "402": {
            "description": "Payment required for Free accounts",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "403": {
            "description": "Hunt is the minimum plan for this REST operation",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "409": {
            "description": "Operation conflicts with current account state",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "413": {"$ref": "#/components/responses/BodyTooLarge"},
          "415": {
            "description": "Expected application/json",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "429": {
            "description": "Rate limited",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "503": {
            "description": "Service temporarily unavailable or Agent API disabled",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          }
        }
      }
    },
    "/checkout": {
      "post": {
        "operationId": "create_checkout_link",
        "summary": "Create a Stripe Checkout link for the account owner",
        "description": "Give the returned link to the account owner to open and pay.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "plan": {
                    "type": "string",
                    "description": "The RefurbSitter plan ID to purchase or renew. Both refurb-spot-pass-19 and refurb-spot-pass-9 buy the $9 Spot Pass. Renewal IDs such as refurb-hunt-renew-49 require an eligible expired pass.",
                    "example": "refurb-spot-pass-9"
                  }
                },
                "required": ["plan"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {"url": {"type": "string", "format": "uri"}},
                  "required": ["url"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {
            "description": "Missing, invalid, or revoked key",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "403": {
            "description": "Origin, channel, or checkout is forbidden",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "409": {
            "description": "Operation conflicts with current account state",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "413": {"$ref": "#/components/responses/BodyTooLarge"},
          "415": {
            "description": "Expected application/json",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "429": {
            "description": "Rate limited",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "503": {
            "description": "Service temporarily unavailable or Agent API disabled",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "BodyTooLarge": {
        "description": "Request body exceeds 64 KiB",
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
      }
    },
    "securitySchemes": {"agentKey": {"type": "http", "scheme": "bearer", "bearerFormat": "rs_agent_…"}},
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {"code": {"type": "string"}, "message": {"type": "string"}, "pricing_url": {"type": "string", "format": "uri"}, "checkout": {"type": "string"}, "valid_plans": {"type": "array", "items": {"type": "string"}, "description": "Checkout plan IDs returned with invalid_plan. Renewal IDs require an eligible expired pass."}},
            "required": ["code", "message"]
          }
        },
        "required": ["error"]
      },
      "Account": {
        "type": "object",
        "properties": {
          "email": {"type": "string", "format": "email"},
          "plan": {"type": "string"},
          "entitlements": {"type": "array", "items": {"$ref": "#/components/schemas/Entitlement"}},
          "watch_count": {"type": "integer", "description": "Includes pickup watches that share the quota."},
          "watch_limit": {"type": "integer"},
          "allowed_channels": {
            "type": "array",
            "items": {"type": "string", "enum": ["email", "web_push", "ntfy", "webhook"]}
          },
          "alert_delay_ms": {"type": "integer"},
          "paid_access_paused": {"type": "boolean"},
          "webhook_configured": {"type": "boolean"}
        },
        "required": [
          "email",
          "plan",
          "entitlements",
          "watch_count",
          "watch_limit",
          "allowed_channels",
          "alert_delay_ms",
          "paid_access_paused",
          "webhook_configured"
        ]
      },
      "Entitlement": {
        "type": "object",
        "properties": {
          "plan": {"type": "string"},
          "mode": {"enum": ["payment", "subscription"]},
          "active": {
            "type": "boolean",
            "description": "Stored entitlement status. Use expires_at and the account plan for current access."
          },
          "paid_at": {"type": "string", "format": "date-time"},
          "expires_at": {"type": ["string", "null"], "format": "date-time"},
          "payment_failed": {"type": "boolean"}
        },
        "required": ["plan", "mode", "active", "paid_at", "expires_at", "payment_failed"]
      },
      "Catalog": {
        "type": "object",
        "properties": {
          "specific_config_enforced": {"type": "boolean"},
          "products": {"type": "array", "items": {"$ref": "#/components/schemas/Product"}}
        },
        "required": ["specific_config_enforced", "products"]
      },
      "Product": {
        "type": "object",
        "properties": {
          "family": {"type": "string"},
          "label": {"type": "string"},
          "processors": {"type": "array", "items": {"type": "object"}},
          "screenSizes": {"type": "array", "items": {"type": "integer"}},
          "configurations": {"type": "array", "items": {"$ref": "#/components/schemas/Configuration"}}
        },
        "required": ["family", "label", "processors", "configurations"]
      },
      "Configuration": {
        "type": "object",
        "properties": {
          "config_id": {"type": "string"},
          "label": {"type": "string"},
          "chip_pattern": {"type": ["string", "null"]},
          "cpu_cores_min": {"type": ["integer", "null"]},
          "gpu_cores_min": {"type": ["integer", "null"]},
          "ram": {"type": ["integer", "null"]},
          "ssd": {"type": ["integer", "null"]}
        },
        "required": ["config_id", "label", "chip_pattern", "cpu_cores_min", "gpu_cores_min", "ram", "ssd"]
      },
      "WatchInput": {
        "type": "object",
        "properties": {
          "model_family": {"type": "string", "description": "Use a product family returned by the catalog."},
          "chip_pattern": {"type": ["string", "null"]},
          "cpu_cores_min": {"type": ["integer", "null"]},
          "gpu_cores_min": {"type": ["integer", "null"]},
          "ram_gte": {
            "type": ["integer", "null"],
            "description": "RAM in GB. Set ram_gte and ram_lte to the exact configuration's ram."
          },
          "ram_lte": {"type": ["integer", "null"]},
          "ssd_gte": {
            "type": ["integer", "null"],
            "description": "Storage in GB. Use the configuration's ssd."
          },
          "config_id": {"type": ["string", "null"]},
          "screen_size": {"type": ["integer", "null"]},
          "requires_10gb_ethernet": {"type": "boolean", "description": "Mac mini only."},
          "channels": {
            "type": "array",
            "items": {"type": "string", "enum": ["email", "web_push", "ntfy", "webhook"]},
            "minItems": 1
          }
        },
        "required": ["channels"],
        "anyOf": [
          {"required": ["config_id"], "properties": {"config_id": {"type": "string", "minLength": 1}}},
          {"required": ["model_family"]}
        ],
        "description": "Use a catalog config_id to select a configuration. Non-null values for fields defined by the configuration must match it. If specific_config_enforced is true and you omit config_id for a Mac watch, send the exact catalog fields."
      },
      "Watch": {
        "type": "object",
        "properties": {
          "model_family": {"type": "string", "description": "Use a product family returned by the catalog."},
          "chip_pattern": {"type": ["string", "null"]},
          "cpu_cores_min": {"type": ["integer", "null"]},
          "gpu_cores_min": {"type": ["integer", "null"]},
          "ram_gte": {
            "type": ["integer", "null"],
            "description": "RAM in GB. Set ram_gte and ram_lte to the exact configuration's ram."
          },
          "ram_lte": {"type": ["integer", "null"]},
          "ssd_gte": {
            "type": ["integer", "null"],
            "description": "Storage in GB. Use the configuration's ssd."
          },
          "config_id": {"type": ["string", "null"]},
          "screen_size": {"type": ["integer", "null"]},
          "requires_10gb_ethernet": {"type": "boolean", "description": "Mac mini only."},
          "channels": {
            "type": "array",
            "items": {"type": "string", "enum": ["email", "web_push", "ntfy", "webhook"]},
            "minItems": 1
          },
          "id": {"type": ["string", "integer"]},
          "user_email": {"type": "string", "format": "email"},
          "active": {"type": "boolean"},
          "created_at": {"type": "string", "format": "date-time"},
          "updated_at": {"type": "string", "format": "date-time"},
          "price_max": {"type": ["integer", "null"]}
        },
        "required": [
          "model_family",
          "chip_pattern",
          "cpu_cores_min",
          "gpu_cores_min",
          "ram_gte",
          "ram_lte",
          "ssd_gte",
          "config_id",
          "screen_size",
          "requires_10gb_ethernet",
          "channels",
          "id",
          "user_email",
          "active",
          "created_at",
          "updated_at",
          "price_max"
        ]
      },
      "IssuedKey": {
        "type": "object",
        "properties": {
          "id": {"type": "string", "format": "uuid"},
          "email": {"type": "string", "format": "email"},
          "key": {"type": "string", "description": "Shown once. Store securely."},
          "key_prefix": {"type": "string"},
          "label": {"type": ["string", "null"]},
          "created_at": {"type": "string", "format": "date-time"},
          "last_used_at": {"type": ["string", "null"], "format": "date-time"},
          "revoked_at": {"type": ["string", "null"], "format": "date-time"}
        },
        "required": ["id", "email", "key", "key_prefix", "label", "created_at", "last_used_at", "revoked_at"]
      }
    }
  }
}
