# Popular Demand > Developer docs for buyers' agents: the Popular Demand MCP server, REST API and agent rules. - [Introduction](https://docs.populardemand.market/introduction.md): What Popular Demand is, and where the purchase happens. - [Quickstart](https://docs.populardemand.market/quickstart.md): Connect the MCP server, save a first Request and read Offers. - [Requests](https://docs.populardemand.market/concepts/requests.md): A free, private, non-binding record of something a buyer would buy later. - [Items and options](https://docs.populardemand.market/concepts/items-and-options.md): What the buyer needs, and the models they would accept. - [Price limits](https://docs.populardemand.market/concepts/price-limits.md): Recorded only when the buyer volunteers one. - [Offers](https://docs.populardemand.market/concepts/offers.md): A seller's group price, bought at the seller's own checkout. - [Questions](https://docs.populardemand.market/concepts/questions.md): still_want checks and seller questions. - [Notifications](https://docs.populardemand.market/concepts/notifications.md): How the buyer hears about Offers and checks. - [Closing](https://docs.populardemand.market/concepts/closing.md): close_request closes a Request. The buyer can reopen it for 7 days. - [Agent rules](https://docs.populardemand.market/agent-rules.md): What the buyer MCP server tells every agent, quoted from the source. - [Authentication](https://docs.populardemand.market/authentication.md): OAuth, and the permissions the buyer grants. - [CLI](https://docs.populardemand.market/cli.md): A command-line client for agents with their own computer. - [Email agents](https://docs.populardemand.market/email-agents.md): A fallback for agents that only have a mailbox. - [Changelog](https://docs.populardemand.market/changelog.md): Changes to the buyer contract. - [MCP server](https://docs.populardemand.market/mcp/overview.md): The buyer MCP server and its 9 tools. - [list_requests](https://docs.populardemand.market/mcp/tools/list_requests.md): List Requests - [get_request](https://docs.populardemand.market/mcp/tools/get_request.md): Get a Request - [get_offers](https://docs.populardemand.market/mcp/tools/get_offers.md): Get Offers - [save_request](https://docs.populardemand.market/mcp/tools/save_request.md): Save a Request - [update_request](https://docs.populardemand.market/mcp/tools/update_request.md): Change a Request - [close_request](https://docs.populardemand.market/mcp/tools/close_request.md): Close a Request - [answer_question](https://docs.populardemand.market/mcp/tools/answer_question.md): Answer a question - [respond_to_offer](https://docs.populardemand.market/mcp/tools/respond_to_offer.md): Respond to an Offer - [set_notifications](https://docs.populardemand.market/mcp/tools/set_notifications.md): Set notifications - [REST API](https://docs.populardemand.market/api-reference/introduction.md) - [Errors](https://docs.populardemand.market/api-reference/errors.md): Refusal codes, what each means and what your agent does next. - [Limits](https://docs.populardemand.market/api-reference/limits.md): The hourly quotas your agent’s calls count against. - [List Requests](https://docs.populardemand.market/api-reference/requests/list-requests.md): List owned Request summaries within the approved agent scope. Includes actual blockers and useful next actions. Fetch detail_url for evidence diagnostics and history. Reading does not reaffirm interest. Without paging parameters the response is up to 100 summaries of open Requests under the intents… - [Save a Request](https://docs.populardemand.market/api-reference/requests/save-a-request.md): Create active soft demand after verified ownership and explicit user authorization. No existing market or variant is required. Without currency, the Request uses its country’s currency (US/USD, IL/ILS). The response has save_confirmation: relay it as it is. - [Get a Request](https://docs.populardemand.market/api-reference/requests/get-a-request.md): Private status, conditions, evidence diagnostics, effective pricing, reachability and history. A read-only capability grants access to one purchase; cannot write. Reading records polling activity separately from freshness. The owner’s read also has needs_attention, open_questions and notifications,… - [Change a Request](https://docs.populardemand.market/api-reference/requests/change-a-request.md): Versioned owner edit. In changes, a field you leave out stays as it is and null clears it. Listing an item’s options replaces that item’s options. Preserve original ID/source. Changes invalidate context-dependent evidence and cluster membership conservatively. - [Close or ask to close a Request](https://docs.populardemand.market/api-reference/requests/close-or-ask-to-close-a-request.md): Close a Request. From the person’s own session it closes at once, revoking polling access and subscriptions and cancelling pending messages. With an agent token it never closes an open Request: it pauses it and emails the person a link to close it, keep it paused or resume it. The response’s message… - [Confirm the buyer still wants a Request](https://docs.populardemand.market/api-reference/requests/confirm-the-buyer-still-wants-a-request.md): Only after fresh user confirmation. Polling must never invoke this automatically. OAuth grants require the separately selected reaffirm permission. - [Propose an exact product](https://docs.populardemand.market/api-reference/requests/propose-an-exact-product.md): Propose an exact product interpretation with evidence and rationale. Does not approve substitution, create catalog/market data, or change canonical user conditions. Operator review required. - [Get Offers](https://docs.populardemand.market/api-reference/offers/get-offers.md): Read owned candidate Offers, original term snapshots and current evaluation. Requires owner read permission. The default lists five recent Offers; optional limit is 1–20, with a truncation flag, next_cursor and fresh read time. Continue with paired before_created_at/before_id; each page is an indepe… - [Record whether an Offer fits](https://docs.populardemand.market/api-reference/offers/record-whether-an-offer-fits.md): Record a confirmed pre-check of one exact owned Offer and Request version: fits, needs_user or does_not_fit. Requires a stable Idempotency-Key and, for OAuth agents, offer_fit permission and this Request in scope. A conflict requires a fresh read and user reconciliation. This records intent only; it… - [Get questions](https://docs.populardemand.market/api-reference/questions/get-questions.md): Read up to 10 recent targeted questions for an owned Request from the last 30 days, newest first, with allowed typed answers, deadline, status and latest typed answer. Requires verified ownership; OAuth agents also need read permission and this Request in scope. Private capabilities are not accepted… - [Answer a question](https://docs.populardemand.market/api-reference/questions/answer-a-question.md): Answer one question from open_questions, as answer_question does over MCP. Needs an agent access token and a stable Idempotency-Key. still_want takes yes or pause and needs the reaffirm permission; answer it only with the person’s answer. A seller question needs the reachability permission; answer o… - [Get notification settings](https://docs.populardemand.market/api-reference/notifications/get-notification-settings.md): Read the account-wide check frequency and channels. Reading changes nothing. - [Change notification settings](https://docs.populardemand.market/api-reference/notifications/change-notification-settings.md): Change the account-wide check frequency or channels, as set_notifications does without request_id. Change only what the person confirmed. An agent needs the reachability permission and access to all of the person’s Requests. Deal alerts belong to one Request: use /api/purchases/{id}/demand-checks. - [Get demand-check settings](https://docs.populardemand.market/api-reference/notifications/get-demand-check-settings.md): Read the account-wide check frequency and channels, plus deal alerts for this owned Request. OAuth agents need read permission, the purchases:read scope and this Request in scope. Private capabilities are refused. Reading never confirms interest or sends a message. Writing account-wide settings need… - [Change demand-check settings](https://docs.populardemand.market/api-reference/notifications/change-demand-check-settings.md): Change only settings the user confirmed, with a stable Idempotency-Key. Include at least one of check_frequency, check_channels or deal_alerts. check_frequency and check_channels apply to the whole account; deal_alerts applies only to this open Request. OAuth agents need reachability permission; acc… - [Set agent reachability](https://docs.populardemand.market/api-reference/notifications/set-agent-reachability.md): Identity and reachability are distinct. Choose verified-account email or polling cadence; enabled=false cancels that channel only. Owners may send mcp_webhook with enabled=false to stop all Request webhook subscriptions; creation uses authenticated MCP events/subscribe only. Local email goes to Mail… ## OpenAPI Specs - [notifications](/api-reference/openapi/notifications.json) - [offers](/api-reference/openapi/offers.json) - [questions](/api-reference/openapi/questions.json) - [requests](/api-reference/openapi/requests.json) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.