Authentication
The base URL is https://refurbsitter.com/api/agent/v1. Send Authorization: Bearer YOUR_API_KEY on account, catalog, checkout, watch, and webhook requests. Send Content-Type: application/json on requests with a JSON body.
In the examples below, set REFURBSITTER_API_KEY in your shell from your secret store. Create and revoke keys or connection tokens in dashboard settings on paid plans. Free accounts can get a key through email-code signup and revoke it in settings when agent access is shown. Save a newly issued key immediately. Once you dismiss it, you can identify the key in settings by its prefix.
Download the OpenAPI specification for request and response schemas.
POST /api/agent/v1/signup
Start with the mailbox owner’s email and an optional label of up to 80 bytes after trimming. This request and the verification request work without a bearer key.
curl -sS -X POST "https://refurbsitter.com/api/agent/v1/signup" \
-H 'Content-Type: application/json' \
--data '{"email":"operator@example.com","label":"Inventory agent"}'The server returns 200 OK with a flow_id. Save the actual value and ask the mailbox owner for the six-digit code. The code expires after 10 minutes.
{
"flow_id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA_SW52ZW50b3J5IGFnZW50"
}POST /api/agent/v1/signup/verify
Replace the example flow_id and code with the values from the previous step and the email. Send the code as a string to preserve leading zeros.
curl -sS -X POST "https://refurbsitter.com/api/agent/v1/signup/verify" \
-H 'Content-Type: application/json' \
--data '{"flow_id":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA_SW52ZW50b3J5IGFnZW50","code":"012345"}'The server returns 201 Created with the key and its metadata. The response below uses synthetic values. Store the actual key securely. A successful verification consumes the code.
{
"email": "operator@example.com",
"key": "rs_agent_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"id": "44fa1fc8-76e3-4268-bfa5-991a0b660fa1",
"key_prefix": "rs_agent_AAAAAAAA",
"label": "Inventory agent",
"created_at": "2026-11-20T12:00:00.000Z",
"last_used_at": null,
"revoked_at": null
}GET /api/agent/v1/account
Returns the account email, effective plan, entitlements, watch usage and limit, allowed alert channels, alert delay in milliseconds, and whether paid access is paused or a webhook is configured. Pickup watches count toward the shared quota.
curl -sS "https://refurbsitter.com/api/agent/v1/account" \
-H "Authorization: Bearer $REFURBSITTER_API_KEY"GET /api/agent/v1/catalog
Returns specific_config_enforced and products. Each product includes its family and watchable configurations. Use a configuration’s config_id when creating a watch.
curl -sS "https://refurbsitter.com/api/agent/v1/catalog" \
-H "Authorization: Bearer $REFURBSITTER_API_KEY"GET /api/agent/v1/watches
Returns the account’s restock watches in one watches array. Use the returned id to delete a watch.
curl -sS "https://refurbsitter.com/api/agent/v1/watches" \
-H "Authorization: Bearer $REFURBSITTER_API_KEY"POST /api/agent/v1/watches
Creates a watch and returns 201 Created with a watch object. Send a catalog config_id and a nonempty channels array. RefurbSitter fills the product family, chip, core counts, RAM, and storage from the ID. Supplied values for those fields must agree with the ID.
curl -sS -X POST "https://refurbsitter.com/api/agent/v1/watches" \
-H "Authorization: Bearer $REFURBSITTER_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"config_id":"studio-m5-max-18-40@48/512","channels":["email"]}'For manual configuration, send model_family and the applicable chip_pattern, cpu_cores_min, gpu_cores_min, ram_gte, ram_lte, ssd_gte, screen_size, or requires_10gb_ethernet fields. RAM and storage are in GB. When specific_config_enforced is true, use exact catalog fields for a Mac watch without an ID. The Ethernet filter applies to Mac mini.
Choose from email, web_push, ntfy, and webhook according to allowed_channels from the account endpoint. Set up the destination before using the webhook channel.
GET /api/agent/v1/watches/{id}
Set WATCH_ID to the ID returned by the watch list. The response contains a watch object. Invalid IDs, missing watches, and watches outside the account return 404 watch_not_found.
curl -sS "https://refurbsitter.com/api/agent/v1/watches/$WATCH_ID" \
-H "Authorization: Bearer $REFURBSITTER_API_KEY"DELETE /api/agent/v1/watches/{id}
Set WATCH_ID to the ID returned by the watch list. Deleting an owned watch returns 204 No Content. Invalid IDs, missing watches, and watches outside the account return 404 watch_not_found.
curl -sS -X DELETE "https://refurbsitter.com/api/agent/v1/watches/$WATCH_ID" \
-H "Authorization: Bearer $REFURBSITTER_API_KEY"PUT /api/agent/v1/webhook
Sets the account’s public HTTPS destination and returns webhook_configured. Save the signing_secret when returned. Send {"webhook_url":null} to clear the destination or {"rotate_secret":true} to rotate the current secret.
curl -sS -X PUT "https://refurbsitter.com/api/agent/v1/webhook" \
-H "Authorization: Bearer $REFURBSITTER_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"webhook_url":"https://alerts.example.com/refurbsitter"}'See the webhook guide for the event and verification examples.
POST /api/agent/v1/checkout
Creates a Stripe Checkout link for the signed-in key’s account and returns {"url":"…"}. Give the link to the account owner to open and complete payment. Read the account again to confirm the resulting plan before using paid operations.
curl -sS -X POST "https://refurbsitter.com/api/agent/v1/checkout" \
-H "Authorization: Bearer $REFURBSITTER_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"plan":"refurb-spot-pass-9"}'| Checkout plan | Accepted plan ID |
|---|---|
| 30-Day Spot Pass | refurb-spot-pass-19 |
| 90-Day Hunt Pass | refurb-hunt-pass-69 |
| Fleet Monthly | refurb-fleet-99 |
| Fleet Annual | refurb-fleet-annual-999 |
| 30-Day Spot Pass (alias) | refurb-spot-pass-9 |
refurb-spot-pass-19 and refurb-spot-pass-9 select the same Spot Pass. For the Reseller tier, contact RefurbSitter.
Plan access
Every tier can use account, catalog, and checkout through REST and MCP. The watch columns cover listing, creating, and deleting watches. REST watch access also lets you retrieve a single watch. Webhook access covers one destination per account across both transports.
| Plan | API keys | Watch quota | MCP watches | REST watches | Webhook destinations |
|---|---|---|---|---|---|
| Free | 1 | 1 | No | No | 0 |
| Spot | 1 | 1 | Yes | No | 0 |
| Hunt | 5 | 5 | Yes | Yes | 1 |
| Fleet | 5 | 20 | Yes | Yes | 1 |
| Reseller | 10 | 75 | Yes | Yes | 1 |
The watch quota is shared with the dashboard. Free agent keys are for account and catalog reads and checkout.
Errors
Read error.code for the machine-readable reason and error.message for details.
{
"error": {
"code": "unauthorized",
"message": "A valid RefurbSitter API key is required."
}
}payment_required and plan_required include error.pricing_url and error.checkout. invalid_plan includes error.valid_plans.
| HTTP status | Codes |
|---|---|
| 400 | invalid_body, invalid_label, invalid_signup, invalid_code, invalid_watch, invalid_channel, invalid_webhook, invalid_plan |
| 401 | unauthorized |
| 402 | payment_required, watch_limit |
| 403 | forbidden, plan_required, channel_not_allowed, checkout_disabled |
| 404 | watch_not_found |
| 405 | Empty response with an Allow header |
| 408 | body_timeout |
| 409 | key_limit, webhook_not_configured, checkout_conflict |
| 413 | body_too_large or invalid_signup for an email address over 254 characters |
| 415 | unsupported_media_type |
| 422 | invalid_signup |
| 429 | rate_limited |
| 503 | agent_api_disabled, unavailable |
Other checkout failures can use checkout_failed. Use OPTIONS to inspect the Allow header. Account, catalog, and watch-list routes also support HEAD.
curl -sS -i -X OPTIONS 'https://refurbsitter.com/api/agent/v1/watches'
curl -sS -I 'https://refurbsitter.com/api/agent/v1/watches' \
-H "Authorization: Bearer $REFURBSITTER_API_KEY"Rate limits
The REST API and MCP share IP and authenticated account budgets. For 429, wait for Retry-After in seconds when it is present. If signup verification says you’ve used all guesses, request a new code.
| Scope | Limit |
|---|---|
| Agent requests per IP | 120 per minute |
| Authenticated agent requests per account | 60 per minute, shared by the account’s keys |
| Signup starts per IP | 5 per minute |
| Signup codes per email identity | 3 per hour and 10 per day |
| Signup starts across the service | 50 per UTC day by default |
| Verification attempts | 5 per flow during the code’s lifetime |
| Watch creation per account | 20 per minute |
| Agent checkout per account | 5 per hour, with a separate checkout limit of 8 per minute per IP |
Request bodies are limited to 64 KiB and must arrive within 10 seconds.