For developers

Connect your assistant to Scout

Scout watches Resy for a table that matches a request and either alerts the user or, with their explicit approval, books it. Any assistant that can make HTTP calls can find restaurants, create a request, hand the user an approval link, and check the outcome later. This page is written to be read by an agent as well as by a person.

Scout origin: https://dinewithscout.com
REST base: https://dinewithscout.com/api/v1
MCP endpoint: https://dinewithscout.com/mcp
Contract: /api/v1/openapi.json. Skill file: /developers/skill.md.

Get a token

Personal access token. A signed-in user opens Assistants, finds "Personal access tokens", picks the scopes, and creates one. The token starts with spt_, is shown once, is valid for 90 days, and can be revoked on the same page. It works on every /api/v1/* route and on /mcp. Send it as Authorization: Bearer spt_.... Store it in the assistant's secure vault or environment, not in a conversation.

OAuth 2.1. For MCP hosts with native OAuth support. Authorization code with PKCE S256, dynamic client registration at POST /oauth/register, resource https://dinewithscout.com/mcp. Discovery: authorization server and MCP resource. Grants last 30 days. Access tokens last 15 minutes and come with refresh tokens.

Quick start

Set SCOUT_TOKEN to a personal access token, then:

# 1. Confirm the token works; executor.ready says whether Resy is connected, executor.execution is "cloud" by default
curl -H "Authorization: Bearer $SCOUT_TOKEN" https://dinewithscout.com/api/v1/capabilities

# 2. Look up venue IDs (Scout's catalog, then Resy; no live availability)
curl -H "Authorization: Bearer $SCOUT_TOKEN" "https://dinewithscout.com/api/v1/restaurants?q=carbone"

# 3. Validate a spec without creating anything
curl -X POST -H "Authorization: Bearer $SCOUT_TOKEN" -H "Content-Type: application/json" \
  -d @spec.json https://dinewithscout.com/api/v1/requests/preview

# 4. Create the request (Idempotency-Key is required; reuse it on retries)
curl -X POST -H "Authorization: Bearer $SCOUT_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" -d @spec.json https://dinewithscout.com/api/v1/requests

# 5. Poll for status
curl -H "Authorization: Bearer $SCOUT_TOKEN" https://dinewithscout.com/api/v1/requests/sr_...

A minimal spec.json:

{
  "title": "Anniversary dinner",
  "venue_ids": [4123],
  "dates": ["2026-10-02", "2026-10-03"],
  "party_size": 2,
  "earliest_time": "19:00",
  "latest_time": "21:00",
  "timezone": "America/New_York",
  "seating": "any",
  "mode": "alert_only",
  "max_cancellation_fee_per_person": 0,
  "fee_review_hours": 3,
  "expires_at": "2026-10-03T23:59:00-04:00",
  "max_bookings": 1
}

Field rules: venue_ids 1 to 8 positive integers; dates 1 to 42 explicit ISO dates; party_size 1 to 20; times in 24 hour HH:MM with latest_time not before earliest_time; timezone an IANA name (use the venue's); seating any, indoor or outdoor; mode alert_only or auto_book; max_cancellation_fee_per_person 0 to 1000 USD; fee_review_hours 0 to 168 (Scout only auto-books when the free cancellation deadline is at least this far away); expires_at an ISO datetime with offset, before the token expires; max_bookings must be 1; title optional. Unknown fields are rejected. Other routes: GET /requests, PUT /requests/{id} with Idempotency-Key and body {"revision", "spec"}, POST /requests/{id}/stop, GET /reservations/{id}.

How requests work

Alert-only requests start monitoring at once and the response has status: active.

Auto-book requests are created as drafts with status: needs_approval. The response's action_url is the approval link. The user must open it in Scout and approve the exact dates, times, party and fee limits. The agent must give the user that link and must not say anything is booked or being watched until the status changes. Nobody can approve on the user's behalf.

Statuses returned by GET /requests/{id}: needs_approval (waiting for the user), active (monitoring), awaiting_verification (a booking may have been submitted and Scout is confirming it; do not claim success or failure yet), confirmed (a verified reservation exists), expired, stopped, revoked.

A reservation is only real when an entry in reservations[] has verified: true. Until then, say that Scout is watching or verifying, never that a table is booked. Reservation details need the reservations:read scope.

Stopping a request with POST /requests/{id}/stop ends monitoring. It never cancels a reservation that already exists. Reservations are managed at resy.com/account/reservations. There are no webhooks; poll for status.

Tools and scopes

Over MCP the same operations appear as tools: scout_find_restaurants, scout_preview_request, scout_create_request, scout_update_request, scout_get_request, scout_list_requests, scout_stop_request, and scout_get_reservation. Create and update take spec plus an idempotency_key.

Scopes: restaurants:read (catalog search), requests:read (capabilities, preview, list and read requests; required for any MCP connection), requests:write (create, update, stop), reservations:read (reservation details). A token sees only the requests and reservations created through that token or connection. Manage tokens and connected assistants at Assistants.

Limits and honesty notes

Resy only. Up to 20 open requests per user, 8 restaurants and 42 explicit dates per request, one booking per request. Scout's service charge is $0; restaurant cancellation or no-show fees are separate and bounded by the approved fee policy. No deposits or prepaid meals, no cancellation tool, no webhooks.

Resy's terms prohibit automated access and Resy may deactivate accounts that use tools like Scout. Users accept that risk when they connect Resy, and agents should make sure they know it.

Scout makes no claim of better capture rates or privileged inventory access. Restaurant search covers Scout's catalog and Resy's venue search, not live availability. The service is stateless between calls and only the listed request operations are available.