Docs
RestoSignals API reference
One REST API (plus a hosted MCP server) for restaurants, bars and cafés about to open, scored by opening_score. Base URL https://api.restosignals.com. Try every endpoint live in the interactive Swagger UI.
Authentication
Every call takes an API key (prefix pk_). Create one free (100 lead credits, no card) at /signup, or mint a smaller 15-credit trial key programmatically:
curl -s -X POST https://api.restosignals.com/v1/register
# -> { "api_key": "pk_...", "credits": 15 } Send the key on every request in a header — never in the query string (it would leak into logs and proxies). Both of these work:
-H "X-API-Key: pk_YOUR_KEY"
-H "Authorization: Bearer pk_YOUR_KEY" OAuth 2.1 for MCP clients. The MCP server is also its own OAuth 2.1 provider (PKCE + dynamic client registration), so Claude, ChatGPT connectors, Cursor and other MCP clients can connect with just the server URL and a one-time sign-in. Discovery starts at /.well-known/oauth-protected-resource; the full agent auth guide is auth.md.
Metering & credits
- 1 credit = 1 returned lead. You are charged per row actually returned, after the query runs — never per request.
- Empty results are free. A filter that matches nothing costs 0 credits.
- Balance-capped. If your balance is smaller than limit, the page is truncated to what you can pay for and truncated_by_balance: true is set.
- Out of credits → the request is rejected with 402 before any query runs.
Every metered JSON response echoes credits_used and credits_remaining.
Errors
Errors return a JSON body { "detail": "…" } with a standard HTTP status:
GET /v1/openings
The core call — fused, deduped venues ranked by opening_score DESC, then recency.
curl -s "https://api.restosignals.com/v1/openings?state=NY&min_opening_score=40&limit=25" \
-H "X-API-Key: pk_YOUR_KEY" Query parameters
Response
{
"count": 2,
"credits_used": 2,
"credits_remaining": 48,
"truncated_by_balance": false,
"contacts_included": true, // true on a paid plan; false on the free tier
"openings": [
{ "id": 4412, "business_name": "DINER 24 BROADWAY NYC LLC.", "dba": null,
"address": "1674 Broadway", "city": "New York", "state": "NY", "county": null,
"lat": null, "lng": null, "opening_score": 100, "status": "opening",
"signal_types": ["business", "food_permit", "liquor"],
"earliest_signal_date": "2026-06-02", "latest_signal_date": "2026-08-30",
"contact": { // subscriber: revealed. free tier: {locked, available, unlock}
"owner_name": "Diner 24 Broadway LLC", "phone": "9175781633",
"email": null, "website": null,
"owner_address": "1674 Broadway, New York NY 10019" } },
{ "id": 4390, "business_name": "MEDUSA ART STUDIOS & EVENTS", "city": "Astoria",
"state": "NY", "opening_score": 90, "status": "opening",
"signal_types": ["food_permit", "liquor"], "…": "…" }
]
} Venue fields
GET /v1/openings/latest
Same response shape, filtered to venues whose latest signal landed in the last 7 days, sorted newest first. Params: state, limit, offset.
The opening_score model
0–100. We take the strongest evidence within each distinct signal type, then add a fusion bonus that grows with the number of independent types — so a multi-signal venue always outranks a single-signal one. That fusion is the product a raw feed can't reproduce.
- liquor — a pending application (strongest pre-open) or a recently issued license.
- food_permit — a new food / health permit for the premises.
- business — a new LLC / corp filing that matches the venue by name (same-state, unique, multi-token guards prevent false merges).
- fusion bonus — each additional independent signal type adds real weight; a 3-signal venue scores near 100.
- recency decay — evidence older than ~180 days is progressively discounted.
GET /v1/signals
The un-fused view — raw signal rows, for transparency and power users. Filters: source, signal_type, state, city, change_type, status, since, limit, offset. Each row includes source, signal_type, business_name, dba, address_raw, license_number, license_type, status, change_type, filing_date, issue_date, expiration_date, first_seen_date, source_url. 1 credit per returned row.
GET /v1/export
Bulk CSV of fused venues with the same filters as /v1/openings (plus limit up to 10,000). Columns: id, business_name, dba, address_norm, city, state, county, lat, lng, opening_score, status, signal_types (pipe-joined), earliest_signal_date, latest_signal_date. 1 credit per row.
curl -s "https://api.restosignals.com/v1/export?state=NY&min_opening_score=60" \
-H "X-API-Key: pk_YOUR_KEY" Returns a JSON body with a time-limited download_url (and expires_in seconds); the CSV also carries X-Credits-Used, X-Credits-Remaining and X-Row-Count headers.
Webhooks
Register a URL to be POSTed new matching venues as they surface — free. The daily worker dispatches matches.
# create
curl -s -X POST https://api.restosignals.com/v1/webhooks \
-H "X-API-Key: pk_YOUR_KEY" -H "content-type: application/json" \
-d '{"url":"https://you.example.com/hook",
"criteria":{"state":"NY","city":"Brooklyn","signal_type":"liquor","min_opening_score":60}}'
# -> { "id": 7, "url": "…", "criteria": {…}, "active": true } GET /v1/webhooks lists yours; DELETE /v1/webhooks/{id} removes one. Criteria keys: state, city, signal_type, min_opening_score (all optional).
Account & config
- POST /v1/register → {api_key, credits}. Free trial key.
- GET /v1/account → balance, plan and your active keys.
- GET /v1/usage → calls and credits by endpoint.
- POST /v1/keys / POST /v1/keys/revoke → manage keys (session or key auth).
- GET /v1/config → public pricing: plans, packs, free-trial credits, billing status.
Coverage
Live states today: NY, TX, IL, OR, CO, WA, CA. NY, TX, IL and CA carry fused, multi-signal leads (the high scores); OR, CO and WA are liquor-only and thin today, with no hot leads yet. A state with no data returns an empty list — never a fabricated row. In MCP, call coverage for the current list and per-state counts.
MCP server (for AI agents)
The same data and wallet over the Model Context Protocol at https://api.restosignals.com/mcp. With OAuth, the URL is all a client needs:
{ "mcpServers": { "restosignals": { "url": "https://api.restosignals.com/mcp" } } } Or pass an API key:
{
"mcpServers": {
"restosignals": {
"url": "https://api.restosignals.com/mcp",
"headers": { "Authorization": "Bearer pk_YOUR_KEY" }
}
}
} Tools: coverage (free, no key — call first), new_openings, venue_signals, watch_area (paid accounts). Machine-readable: the server card and llms.txt. Full setup, per-tool schemas and an installable skill are on the agents page →