# Agent REST API

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

## 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](/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](/openapi.json) 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.

```bash
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.

```json
{
  "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.

```bash
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.

```json
{
  "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.

```bash
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.

```bash
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.

```bash
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.

```bash
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`.

```bash
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`.

```bash
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.

```bash
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](/docs/webhooks) 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.

```bash
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](/contact).

## 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.

```json
{
  "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`.

```bash
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.
