> ## 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.

# Propose an exact product

> 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.



## OpenAPI

````yaml /api-reference/openapi/requests.json post /api/purchases/{id}/resolution
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/{id}/resolution:
    post:
      tags:
        - Requests
      summary: Propose an exact product
      description: >-
        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.
      operationId: proposeProductResolution
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Shared19'
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            Stable key for one logical write. 8–64 characters. Reusing it with
            different input returns 409.
          schema:
            type: string
            minLength: 8
            maxLength: 64
        - 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'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolutionProposal'
      responses:
        '201':
          description: >-
            Private result; no-store/noindex. No payment or executable order is
            implied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProposalReceipt'
          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:
    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)$
    ResolutionProposal:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        expected_version:
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
        description:
          type: string
          minLength: 3
          maxLength: 500
        product_id:
          $ref: '#/components/schemas/Shared19'
        variant_id:
          $ref: '#/components/schemas/Shared19'
        evidence_url:
          type: string
          maxLength: 2000
          format: uri
        rationale:
          type: string
          minLength: 10
          maxLength: 2000
      required:
        - expected_version
        - description
        - rationale
      additionalProperties: false
    ProposalReceipt:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        proposal_id:
          $ref: '#/components/schemas/Shared19'
        status:
          type: string
          const: proposed
        operator_review_required:
          type: boolean
          const: true
      required:
        - proposal_id
        - status
        - operator_review_required
      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
  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.