> ## Documentation Index
> Fetch the complete documentation index at: https://docs.populardemand.market/llms.txt
> Use this file to discover all available pages before exploring further.

# List Requests

> 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 key. With limit, status, before_created_at or before_id the response is one PurchaseListPage of at most 20, newest first: pass next_cursor back as before_created_at and before_id until it is null, to read every Request. Each summary has needs_attention, as list_requests does.



## OpenAPI

````yaml /api-reference/openapi/requests.json get /api/purchases
openapi: 3.1.0
info:
  title: 'Popular Demand Requests: Requests'
  version: 0.4.0
  x-api-version: '2026-11-20'
  description: >-
    List, save, read, change and close Requests, confirm the buyer still wants
    one, and propose an exact product. Index of all areas:
    https://populardemand.market/api/openapi. Versioning policy: [API
    versioning](https://docs.populardemand.market/api-reference/introduction).
    Every /api and MCP response carries an API-Version header (2026-11-20).
    API-Version identifies the contract served by this deployment; it is not
    version negotiation. The current version is 2026-11-20. Sending an
    API-Version request header does not select an older contract. We choose a
    new YYYY-MM-DD date for a breaking change. Adding optional fields, endpoints
    or tools is additive when existing valid requests and documented meanings
    stay unchanged; clients should tolerate unknown response fields. Removing or
    renaming fields, making optional input required, or changing existing field
    types, meanings or authorization requirements is breaking. During early
    access, breaking changes may ship without notice; each one is listed with
    its date in the version changes. Hourly quotas are per UTC hour; a refused
    request answers 429 with Retry-After, RateLimit and RateLimit-Policy headers
    (IETF draft-ietf-httpapi-ratelimit-headers-11, work in progress:
    https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers-11)
    and error.retry_after_seconds; a successful REST request that counted
    against a per-caller quota carries RateLimit and RateLimit-Policy with the
    allowance left. Errors may carry error.hint, the next step to take. Popular
    Demand Request API. Lists contain Request summaries; individual detail reads
    retain evidence diagnostics and history; recorded observations are
    operator-only. Purchase conditions first. Confirmed explicit all-in ceilings
    and exploration require no individual-option upload. Agent research may
    remain private. Buyer agents compare market prices themselves. Product
    resolution may follow capture. US/USD and IL/ILS only. Integer minor units;
    one canonical intent is not a guaranteed buyer. Every new intent has
    execution_available=false. baseline_diagnostics explains read-time evidence
    eligibility. Mutation retries may return historical cached results; read the
    root again when current evidence/version matters. Verified same-origin
    browser sessions are also accepted on owner REST endpoints; cookie writes
    require Origin. OAuth client tokens require the exact MCP audience and an
    approved Popular Demand grant.
servers:
  - url: https://populardemand.market
security: []
tags:
  - name: Requests
    description: >-
      List, save, read, change and close Requests, confirm the buyer still wants
      one, and propose an exact product.
paths:
  /api/purchases:
    get:
      tags:
        - Requests
      summary: List Requests
      description: >-
        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 key. With limit, status, before_created_at or
        before_id the response is one PurchaseListPage of at most 20, newest
        first: pass next_cursor back as before_created_at and before_id until it
        is null, to read every Request. Each summary has needs_attention, as
        list_requests does.
      operationId: listFuturePurchases
      parameters:
        - name: limit
          in: query
          description: >-
            Page size, 1 to 20 (default 5). Any paging parameter selects the
            paged response.
          schema:
            default: 5
            type: integer
            minimum: 1
            maximum: 20
        - name: before_created_at
          in: query
          description: next_cursor.before_created_at from the previous page.
          schema:
            $ref: '#/components/schemas/Shared11'
        - name: before_id
          in: query
          description: >-
            next_cursor.before_id from the previous page; send both cursor
            fields.
          schema:
            $ref: '#/components/schemas/Shared19'
        - name: status
          in: query
          description: open (the default), closed or all. Selects the paged response.
          schema:
            default: open
            type: string
            enum:
              - open
              - closed
              - all
        - name: API-Version
          in: header
          required: false
          description: >-
            Current contract only; no version negotiation. See
            https://docs.populardemand.market/api-reference/introduction.
          schema:
            type: string
            default: '2026-11-20'
      responses:
        '200':
          description: >-
            Private result; no-store/noindex. No payment or executable order is
            implied.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PurchaseList'
                  - $ref: '#/components/schemas/PurchaseListPage'
          headers:
            RateLimit:
              description: >-
                Present when this REST request counted against a per-caller
                hourly quota: the allowance left after it and seconds until the
                window resets, e.g. "write";r=19;t=1200. One list member per
                quota counted.
              schema:
                type: string
            RateLimit-Policy:
              description: >-
                Present with RateLimit: the quota counted, e.g.
                "write";q=20;w=3600. Quotas shared beyond the caller (every
                caller, one network or one OAuth client) are reported only when
                they refuse.
              schema:
                type: string
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
        '400':
          description: Invalid input / confirmation needed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseError'
          headers:
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
        '401':
          description: Verified identity or approved OAuth grant required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseError'
          headers:
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
        '403':
          description: >-
            forbidden: missing permission; origin_not_allowed: foreign browser
            origin at MCP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseError'
          headers:
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
        '404':
          description: Not accessible to this identity / capability
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseError'
          headers:
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
        '409':
          description: Version, lifecycle or idempotency conflict; read current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseError'
          headers:
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
        '413':
          description: Request body exceeds 32 KB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseError'
          headers:
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
        '429':
          description: >-
            A rate or resource cap was reached. Timed quotas carry Retry-After,
            RateLimit and RateLimit-Policy; untimed resource caps carry no reset
            headers.
          headers:
            Retry-After:
              description: >-
                Present only for a timed quota refusal: seconds until the next
                attempt. Untimed resource caps do not carry this header.
              schema:
                type: integer
            RateLimit:
              description: >-
                Present only when an actual limiter reports a timed quota
                refusal. Remaining quota and reset, e.g. "write";r=0;t=1200.
              schema:
                type: string
            RateLimit-Policy:
              description: >-
                Present only for an actual timed quota. The quota refused, e.g.
                "write";q=20;w=3600.
              schema:
                type: string
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseError'
        '500':
          description: Safe internal error; retry the same logical request key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseError'
          headers:
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
        '503':
          description: >-
            Required configuration unavailable, bounded transient database
            failure or a payment provider that did not execute the request. A
            transient response has explicit retry advice (retryable,
            retry_after_seconds) and a matching Retry-After header. Reuse the
            identical logical command and key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseError'
          headers:
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
      security:
        - OwnerBearer: []
components:
  schemas:
    Shared11:
      type: string
      format: date-time
      pattern: >-
        ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
    Shared19:
      type: string
      format: uuid
      pattern: >-
        ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
    PurchaseList:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        intents:
          maxItems: 100
          type: array
          items:
            $ref: '#/components/schemas/RequestSummary'
        can:
          type: array
          items:
            type: string
          description: >-
            The tools this connection may call, by MCP tool name.
            answer_question:still_want is its own entry.
      required:
        - intents
      additionalProperties: false
    PurchaseListPage:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/RequestSummary'
        has_more:
          type: boolean
        next_cursor:
          anyOf:
            - type: object
              properties:
                before_created_at:
                  $ref: '#/components/schemas/Shared11'
                before_id:
                  $ref: '#/components/schemas/Shared19'
              required:
                - before_created_at
                - before_id
              additionalProperties: false
            - type: 'null'
        ordering:
          type: string
          const: created_at_desc_id_desc
        as_of:
          $ref: '#/components/schemas/Shared11'
        can:
          type: array
          items:
            type: string
          description: >-
            The tools this connection may call, by MCP tool name.
            answer_question:still_want is its own entry.
      required:
        - items
        - has_more
        - next_cursor
        - ordering
        - as_of
      additionalProperties: false
    PurchaseError:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details: {}
            retryable:
              type: boolean
              const: true
            retry_after_seconds:
              type: integer
              exclusiveMinimum: 0
              maximum: 9007199254740991
            hint:
              type: string
            errors:
              maxItems: 20
              type: array
              items:
                type: object
                properties:
                  path:
                    type: string
                  message:
                    type: string
                required:
                  - path
                  - message
                additionalProperties: false
          required:
            - code
            - message
          additionalProperties: false
      required:
        - error
      additionalProperties: false
    RequestSummary:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Shared19'
        status:
          type: string
          enum:
            - draft
            - active
            - closed
        version:
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
        raw_request:
          type: string
        country:
          type: string
          pattern: ^[A-Z]{2}$
          enum:
            - US
            - IL
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          enum:
            - USD
            - ILS
        price_limit:
          anyOf:
            - type: object
              properties:
                amount_minor:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                currency:
                  type: string
                  pattern: ^[A-Z]{3}$
                  enum:
                    - USD
                    - ILS
              required:
                - amount_minor
                - currency
              additionalProperties: false
            - type: 'null'
        items_summary:
          anyOf:
            - type: object
              properties:
                items_count:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                known_units:
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                unknown_quantity_items:
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                basket_acceptance:
                  type: string
                  enum:
                    - all_required
                    - partial_allowed
                    - unknown
              required:
                - items_count
                - known_units
                - unknown_quantity_items
                - basket_acceptance
              additionalProperties: false
            - type: 'null'
        resolution_status:
          type: string
        research_status:
          type: string
        updated_at:
          $ref: '#/components/schemas/Shared11'
        expires_at:
          $ref: '#/components/schemas/Shared11'
        as_of:
          $ref: '#/components/schemas/Shared11'
        buyer_status:
          type: object
          properties:
            state:
              type: string
              enum:
                - closed
                - ended
                - not_confirmed
                - paused
                - bought
                - offer_ready
                - details_needed
                - confirm_needed
                - asking_sellers
                - no_offer
                - offer_ended
                - gathering_interest
            label:
              type: string
            details:
              $ref: '#/components/schemas/Shared16'
          required:
            - state
            - label
          additionalProperties: false
          description: >-
            The one status the person sees, decided at as_of; the first that
            applies wins: closed, ended (past expires_at, or past its need_by
            date unless bought or an Offer is current), not_confirmed (a draft),
            paused (paused by the person; confirming it again counts it), bought
            (we saw a paid, uncancelled store order for this Request that wasn't
            fully refunded), offer_ready (a current Offer exists),
            details_needed (no confirmed exact item or delivery method, or only
            pickup while pickup is not arranged), confirm_needed (sellers no
            longer count it: unconfirmed for over 30 days; reaffirming with the
            user's say-so counts it again), asking_sellers (an RFQ counting this
            Request is open to sellers), no_offer (that RFQ ended and no Offer
            was made; it stays until sellers are asked again), offer_ended (an
            Offer was made and is no longer current, with no known purchase),
            gathering_interest. label is the words the person sees; show it as
            given.
        exact_item_confirmation:
          $ref: '#/components/schemas/Shared3'
        pricing:
          $ref: '#/components/schemas/Shared14'
        baseline_summary:
          anyOf:
            - type: object
              properties:
                amount_minor:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                observed_at:
                  $ref: '#/components/schemas/Shared11'
                valid_until:
                  $ref: '#/components/schemas/Shared11'
              required:
                - amount_minor
                - observed_at
                - valid_until
              additionalProperties: false
            - type: 'null'
        blockers:
          type: array
          items:
            type: string
        next_actions:
          $ref: '#/components/schemas/Shared21'
        execution_available:
          type: boolean
          const: false
        detail_url:
          type: string
        needs_attention:
          type: array
          items:
            type: string
            enum:
              - new_offer
              - open_question
              - details_needed
              - still_want
              - offer_ending
        attention:
          $ref: '#/components/schemas/Shared10'
      required:
        - id
        - status
        - version
        - raw_request
        - country
        - currency
        - price_limit
        - items_summary
        - resolution_status
        - research_status
        - updated_at
        - expires_at
        - as_of
        - pricing
        - baseline_summary
        - blockers
        - next_actions
        - execution_available
        - detail_url
      additionalProperties: false
    Shared16:
      description: >-
        With details_needed only: item (the exact item, quantity or delivery
        method is missing) or pickup_only (it accepts only pickup, which is not
        arranged for now; add delivery, with the user’s say-so, to have it
        counted).
      type: string
      enum:
        - item
        - pickup_only
    Shared3:
      anyOf:
        - $ref: '#/components/schemas/Shared4'
        - type: 'null'
    Shared14:
      type: object
      properties:
        status:
          type: string
          enum:
            - exploratory
            - price_specified
        amount_minor:
          anyOf:
            - type: integer
              exclusiveMinimum: 0
              maximum: 9007199254740991
            - type: 'null'
        label:
          type: string
      required:
        - status
        - amount_minor
      additionalProperties: false
    Shared21:
      type: array
      items:
        type: object
        properties:
          code:
            type: string
          actor:
            type: string
          message:
            type: string
        required:
          - code
          - actor
          - message
        additionalProperties: false
    Shared10:
      description: Each needs_attention flag in words.
      type: array
      items:
        $ref: '#/components/schemas/Shared12'
    Shared4:
      type: object
      properties:
        confirmed_by:
          type: string
          enum:
            - person
            - agent
        confirmed_at:
          $ref: '#/components/schemas/Shared11'
        request_version:
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
      required:
        - confirmed_by
        - confirmed_at
        - request_version
      additionalProperties: false
    Shared12:
      type: object
      properties:
        flag:
          type: string
          enum:
            - new_offer
            - open_question
            - details_needed
            - still_want
            - offer_ending
            - request_ending
        message:
          type:
            - string
            - 'null'
        agent_line:
          type:
            - string
            - 'null'
      required:
        - flag
        - message
        - agent_line
      additionalProperties: false
  securitySchemes:
    OwnerBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        An OAuth access token for the buyer resource (audience, issuer and
        signature checked). Its scopes and the active grant the person approved
        are both enforced.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.