Stay Portland Developer Documentation

Quickstart

Stay Portland’s public API helps you find Portland vacation rentals, check exact prices, and hand a traveler a checkout link. Requests and responses use JSON. Use the canonical www host directly to avoid a redirect on POST requests.

Start with an undated search. Copy a returned slug into the quote request’s listing field. Search prices are accommodation-only; priced availability and quotes include cleaning and taxes. Quotes do not reserve a home or complete a booking.

curl 'https://www.stayportland.com/api/site-tools/search' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data '{"guests":2,"limit":2}'

Authentication and API keys

The documented public search, priced-availability, quote, and MCP endpoints require no API key, account, or Authorization header. Key issuance and authenticated partner integrations are not offered by this API.

Guest accounts, reservations, payment details, and private stay/access information are outside this public contract. Give the traveler the returned checkout URL; payment happens on Stay Portland. Never ask for card details in an agent or CLI.

Endpoints and schemas

POST /api/site-tools/search — optional dates, guest capacity, bedrooms, bathrooms, beds, pets, neighborhood, title query, maxNightly, sort, offset, and limit. Returns public listing cards and pagination. Dated totals cover accommodation only.

POST /api/site-tools/priced-availability — required checkin and checkout; optional capacity and property filters. Returns up to six exact all-in quotes per page and checkout links. This creates temporary quotes, never reservations or payments.

POST /api/site-tools/quote — listing (ID or slug), checkin, checkout, and guests. Returns a temporary all-in USD quote with its expiry and checkout URL.

Dates use YYYY-MM-DD in Portland time. Check-in must be today or later, and stays can be no longer than 30 nights. The OpenAPI specification is the complete reference for required fields, defaults, bounds, response types, and operation IDs. Unknown fields are rejected.

curl 'https://www.stayportland.com/openapi.json' -H 'Accept: application/json'

Errors and rate limits

Errors include error (the existing compatibility message), code, message, hint, and documentation. Validation errors also identify fields in issues. Use HTTP status and code for control flow, and the hint to recover.

Each request body is limited to 16 KiB. Per IP per 10 minutes: search 6 requests, priced availability 3, quote 12. Shared deployment budgets are 120, 20, and 120 respectively. A 429 includes Retry-After in seconds. Wait for that interval; do not immediately retry. A 429 can also mean the rate-limit service is unavailable.

Fix invalid input before retrying 400 responses. On 409, choose different dates or search again. On 502, retry later with backoff. Unknown API paths return 404 JSON with documentation links. Unsupported endpoint methods return 405 with an Allow header.

{
  "error": "invalid search parameters",
  "code": "INVALID_PARAMETERS",
  "message": "invalid search parameters",
  "hint": "Check the request fields against the OpenAPI schema.",
  "documentation": "https://www.stayportland.com/developers"
}

Stay Portland MCP server

Connect a Streamable HTTP client to https://www.stayportland.com/mcp. This public stateless server supports discovery, comparisons, reviews, policies, shortlists, and quotes. Its server card is at /.well-known/mcp.json. No authentication is required.

POST requests must accept both application/json and text/event-stream. Initialize first, send notifications/initialized, then discover tools with tools/list. Use the negotiated MCP-Protocol-Version on subsequent requests. The server does not issue session IDs; GET and DELETE return 405 because a persistent stream/session is not offered.

A successful initialization may be returned as SSE. Notifications receive 202 with no body. The API’s booking boundary also applies to MCP: hand off checkout to the traveler. Server-side connectors omit Origin; browser requests must use an allowed origin.

curl 'https://www.stayportland.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"quickstart","version":"1.0.0"}}}'

Markdown and discovery

Request the homepage, About, developer documentation, AI connection page, property profiles, or policy pages with Accept: text/markdown. Use text/html for the browser representation. These negotiated responses vary on Accept and Accept-Encoding. RSC navigation keeps the framework’s own representation.

Start at /llms.txt for agent resources, /sitemap.xml for public pages, and /ai-sitemap.xml for property markdown. Missing URLs return a real 404 and recovery links. The canonical brand and domain are Stay Portland and https://www.stayportland.com.

curl 'https://www.stayportland.com/' -H 'Accept: text/markdown'

Stay Portland CLI

The official CLI package is maintained as @stayportland/cli in this project’s packages/cli directory. Registry publication is pending; there is no npm installation command until the package is published. Node.js 22 or newer is required.

Contributors with repository access can use the source commands below; the private repository is not a public CLI download. Commands output JSON for piping, accept --base-url for an authorized development environment, and report failures to stderr with a nonzero exit code. Run npm --prefix packages/cli test for the local fixture-server sandbox.

node packages/cli/bin/stayportland.mjs openapi
node packages/cli/bin/stayportland.mjs search --json '{"guests":2,"limit":2}'