Skip to main content

Agent REST API

Get an API key by email and use the v1 endpoints for account, catalog, watches, webhooks, and checkout.

View Markdown

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 planAccepted plan ID
30-Day Spot Passrefurb-spot-pass-19
90-Day Hunt Passrefurb-hunt-pass-69
Fleet Monthlyrefurb-fleet-99
Fleet Annualrefurb-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.

PlanAPI keysWatch quotaMCP watchesREST watchesWebhook destinations
Free11NoNo0
Spot11YesNo0
Hunt55YesYes1
Fleet520YesYes1
Reseller1075YesYes1

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 statusCodes
400invalid_body, invalid_label, invalid_signup, invalid_code, invalid_watch, invalid_channel, invalid_webhook, invalid_plan
401unauthorized
402payment_required, watch_limit
403forbidden, plan_required, channel_not_allowed, checkout_disabled
404watch_not_found
405Empty response with an Allow header
408body_timeout
409key_limit, webhook_not_configured, checkout_conflict
413body_too_large or invalid_signup for an email address over 254 characters
415unsupported_media_type
422invalid_signup
429rate_limited
503agent_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.

ScopeLimit
Agent requests per IP120 per minute
Authenticated agent requests per account60 per minute, shared by the account’s keys
Signup starts per IP5 per minute
Signup codes per email identity3 per hour and 10 per day
Signup starts across the service50 per UTC day by default
Verification attempts5 per flow during the code’s lifetime
Watch creation per account20 per minute
Agent checkout per account5 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.