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

# Save a Request

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



## OpenAPI

````yaml /api-reference/openapi/requests.json post /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:
    post:
      tags:
        - Requests
      summary: Save a Request
      description: >-
        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.
      operationId: saveFuturePurchase
      parameters:
        - 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:
              $schema: https://json-schema.org/draft/2020-12/schema
              type: object
              properties:
                request:
                  type: object
                  properties:
                    words:
                      type: string
                      minLength: 5
                      maxLength: 4000
                      description: >-
                        What the person asked for, in their own words and
                        language.
                    country:
                      default: US
                      type: string
                      pattern: ^[A-Z]{2}$
                      enum:
                        - US
                        - IL
                    currency:
                      type: string
                      pattern: ^[A-Z]{3}$
                      enum:
                        - USD
                        - ILS
                    destination:
                      default: {}
                      type: object
                      properties:
                        postal_code:
                          description: >-
                            A US ZIP (12345 or 12345-6789) or a 7-digit Israeli
                            postal code. Optional when saving; required before
                            an Offer can be prepared.
                          type: string
                          maxLength: 32
                        city:
                          type: string
                          minLength: 1
                          maxLength: 100
                        region:
                          description: >-
                            State or region; derived from postal_code when one
                            is given.
                          type: string
                          minLength: 1
                          maxLength: 100
                        scope:
                          type: string
                          enum:
                            - national_parcel
                            - regional
                            - unknown
                      additionalProperties: false
                    need_by:
                      $ref: '#/components/schemas/Shared15'
                    time_horizon:
                      type: string
                      minLength: 1
                      maxLength: 200
                    delivery:
                      maxItems: 2
                      type: array
                      items:
                        type: string
                        enum:
                          - shipping
                          - pickup
                    all_items_required:
                      type: boolean
                    items:
                      default: []
                      maxItems: 20
                      type: array
                      items:
                        type: object
                        properties:
                          item_id:
                            description: Optional stable id; one is assigned when left out.
                            type: string
                            pattern: ^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,79}$
                          description:
                            type: string
                            minLength: 3
                            maxLength: 1000
                          quantity:
                            anyOf:
                              - type: integer
                                minimum: 1
                                maximum: 10000
                              - type: 'null'
                            description: How many; null when the person hasn’t said.
                          required:
                            description: >-
                              Leave out unless the person says this item is
                              optional. Optional items don’t count in the pool
                              counts people see.
                            type: boolean
                          options:
                            maxItems: 20
                            type: array
                            items:
                              $ref: '#/components/schemas/Shared2'
                            description: >-
                              The models the person would accept: several
                              options mean any one of them, not several
                              purchases.
                          terms:
                            $ref: '#/components/schemas/Shared13'
                          price_limit:
                            $ref: '#/components/schemas/Shared7'
                        required:
                          - description
                        additionalProperties: false
                        description: >-
                          One item the person needs, with how many if known. Its
                          options are the models they would accept: several
                          options mean any one of them, not several purchases.
                    price_limit:
                      $ref: '#/components/schemas/Shared6'
                    source:
                      type: string
                      pattern: ^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,99}$
                    expires_at:
                      $ref: '#/components/schemas/Shared11'
                  required:
                    - words
                  additionalProperties: false
              required:
                - request
              additionalProperties: false
            examples:
              illustrative:
                summary: >-
                  Illustrative input: replace request, source, IDs and versions;
                  never submit as real demand.
                value:
                  request:
                    words: >-
                      I might buy a Hobie Outback later. Find a meaningfully
                      better deal.
                    country: US
                    currency: USD
                    destination:
                      city: San Francisco
                      scope: regional
                    time_horizon: Before May; ask me which year
                    source: community:example-club
      responses:
        '201':
          description: >-
            Private result; no-store/noindex. No payment or executable order is
            implied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseView'
          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:
    Shared15:
      anyOf:
        - $ref: '#/components/schemas/Shared17'
        - type: 'null'
    Shared2:
      type: object
      properties:
        option_id:
          description: Keep an existing option’s id; leave out for a new one.
          type: string
          pattern: ^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,79}$
        description:
          type: string
          minLength: 3
          maxLength: 500
        product:
          $ref: '#/components/schemas/Shared5'
      required:
        - description
      additionalProperties: false
    Shared13:
      type: object
      properties:
        warranty_months_min:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 120
            - type: 'null'
        returns_days_min:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 365
            - type: 'null'
        authorized_seller_required:
          type:
            - boolean
            - 'null'
      additionalProperties: false
    Shared7:
      type: object
      properties:
        amount_minor:
          type: integer
          exclusiveMinimum: 0
          maximum: 100000000
        includes_delivery_and_tax:
          type: boolean
      required:
        - amount_minor
        - includes_delivery_and_tax
      additionalProperties: false
      description: >-
        The most the person will pay for one unit of this item, in the
        currency’s smallest unit. Record it only when the person volunteers it.
        For a limit on the whole order, use the Request’s price_limit.
    Shared6:
      type: object
      properties:
        amount_minor:
          type: integer
          exclusiveMinimum: 0
          maximum: 100000000
        includes_delivery_and_tax:
          type: boolean
      required:
        - amount_minor
        - includes_delivery_and_tax
      additionalProperties: false
      description: >-
        The most the person will pay for the whole order, in the currency’s
        smallest unit (cents for USD). Record it only when the person volunteers
        it; never ask for one. It marks Offers above it and is not permission to
        spend.
    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)))$
    PurchaseView:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        blockers:
          type: array
          items:
            type: string
        next_actions:
          $ref: '#/components/schemas/Shared21'
        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'
            matching_confirmation_counts:
              anyOf:
                - type: object
                  properties:
                    person:
                      type: integer
                      minimum: 0
                      maximum: 9007199254740991
                    agent:
                      type: integer
                      minimum: 0
                      maximum: 9007199254740991
                    unknown:
                      type: integer
                      minimum: 0
                      maximum: 9007199254740991
                  required:
                    - person
                    - agent
                    - unknown
                  additionalProperties: false
                - type: 'null'
            message:
              description: >-
                The line the person sees under the status, or null. It can have
                several lines (one per saved item, then a sentence), separated
                by newlines. Show it as given.
              type:
                - string
                - 'null'
            matching_people:
              anyOf:
                - type: integer
                  minimum: 0
                  maximum: 9007199254740991
                - type: 'null'
              description: >-
                With gathering_interest only: the largest of
                item_counts[].people (null when none is a number). Counts only,
                never who; no threshold is published. Null in other states.
            item_counts:
              description: >-
                With gathering_interest only: for each saved item, the people
                (this person included) for whom one seller could make a single
                offer of that exact product: it is among every counted person's
                accepted options, with the same market and a delivery one seller
                can serve. The largest such group per item; groups tied for
                largest each get an entry, except groups of the same people,
                which share one entry listing each product (any of them could be
                offered). Groups are never added together. people is null when
                the only group is people nearby for pickup and fewer than 5
                others are nearby, none included (message then says so; exact
                small local counts are not shown, and an empty area reads like a
                sparse one). Counts only, never who. Null in other states.
              anyOf:
                - type: array
                  items:
                    type: object
                    properties:
                      need_id:
                        type: string
                      label:
                        type: string
                      products:
                        type: array
                        items:
                          type: object
                          properties:
                            namespace:
                              type: string
                            item_id:
                              type: string
                          required:
                            - namespace
                            - item_id
                          additionalProperties: false
                      people:
                        anyOf:
                          - type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                          - type: 'null'
                    required:
                      - need_id
                      - label
                      - products
                      - people
                    additionalProperties: false
                - type: 'null'
          required:
            - state
            - label
            - message
            - matching_people
          additionalProperties: false
        exact_item_confirmation:
          $ref: '#/components/schemas/Shared3'
        id:
          $ref: '#/components/schemas/Shared19'
        status:
          type: string
          enum:
            - draft
            - active
            - closed
        version:
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
        original_raw_request:
          type: string
        raw_request:
          type: string
        country:
          type: string
          pattern: ^[A-Z]{2}$
          enum:
            - US
            - IL
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          enum:
            - USD
            - ILS
        destination:
          type: object
          properties:
            city:
              type: string
              minLength: 1
              maxLength: 100
            region:
              type: string
              minLength: 1
              maxLength: 100
            zip:
              type: string
              pattern: ^[a-zA-Z0-9 -]{3,12}$
            scope:
              default: unknown
              type: string
              enum:
                - national_parcel
                - regional
                - unknown
            postal_code:
              type: string
              maxLength: 32
          required:
            - scope
          additionalProperties: false
        time_horizon:
          type:
            - string
            - 'null'
        need_by:
          $ref: '#/components/schemas/Shared9'
        items:
          type: array
          items:
            type: object
            properties:
              item_id:
                type: string
              description:
                type: string
              quantity:
                anyOf:
                  - type: integer
                    exclusiveMinimum: 0
                    maximum: 9007199254740991
                  - type: 'null'
              required:
                type: boolean
              confirmed:
                type: boolean
              options:
                type: array
                items:
                  type: object
                  properties:
                    option_id:
                      type: string
                    description:
                      type: string
                    product:
                      anyOf:
                        - type: object
                          properties:
                            namespace:
                              type: string
                              minLength: 1
                              maxLength: 200
                            item_id:
                              type: string
                              minLength: 1
                              maxLength: 200
                          required:
                            - namespace
                            - item_id
                          additionalProperties: false
                        - type: 'null'
                    attributes:
                      $ref: '#/components/schemas/Shared18'
                    url:
                      type: string
                      format: uri
                  required:
                    - option_id
                    - description
                    - product
                  additionalProperties: false
              terms:
                type: object
                properties:
                  warranty_months_min:
                    anyOf:
                      - type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      - type: 'null'
                  returns_days_min:
                    anyOf:
                      - type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      - type: 'null'
                  authorized_seller_required:
                    type:
                      - boolean
                      - 'null'
                required:
                  - warranty_months_min
                  - returns_days_min
                  - authorized_seller_required
                additionalProperties: false
            required:
              - item_id
              - description
              - quantity
              - required
              - confirmed
              - options
              - terms
            additionalProperties: false
        price_limits:
          type: array
          items:
            type: object
            properties:
              limit_id:
                type: string
              item_id:
                type:
                  - string
                  - 'null'
              includes_delivery_and_tax:
                type: boolean
              amount_minor:
                type: integer
                exclusiveMinimum: 0
                maximum: 9007199254740991
              currency:
                type: string
                pattern: ^[A-Z]{3}$
                enum:
                  - USD
                  - ILS
              set_at:
                $ref: '#/components/schemas/Shared11'
            required:
              - limit_id
              - item_id
              - includes_delivery_and_tax
              - amount_minor
              - currency
              - set_at
            additionalProperties: false
        delivery:
          type: array
          items:
            type: string
            enum:
              - shipping
              - pickup
        all_items_required:
          type:
            - boolean
            - 'null'
        resolution_status:
          type: string
          enum:
            - unresolved
            - proposed
            - resolved
        research_status:
          type: string
          enum:
            - needs_research
            - provisional
            - reviewed
        source:
          type: string
        created_via:
          type: string
          enum:
            - web
            - api
            - agent
            - email
        draft_agent:
          description: >-
            While this is a draft an email agent sent: that agent's mailbox,
            which activation can make a delegate for this Request. Null
            otherwise.
          type:
            - string
            - 'null'
        origin_client_id:
          anyOf:
            - type: string
              maxLength: 2048
            - type: 'null'
        created_at:
          $ref: '#/components/schemas/Shared11'
        updated_at:
          $ref: '#/components/schemas/Shared11'
        expires_at:
          $ref: '#/components/schemas/Shared11'
        activated_at:
          $ref: '#/components/schemas/Shared9'
        last_reaffirmed_at:
          $ref: '#/components/schemas/Shared9'
        closed_at:
          $ref: '#/components/schemas/Shared9'
        closed_reason:
          type:
            - string
            - 'null'
        observations:
          type: array
          items:
            $ref: '#/components/schemas/Shared1'
        baseline:
          anyOf:
            - $ref: '#/components/schemas/Shared1'
            - type: 'null'
        pricing:
          $ref: '#/components/schemas/Shared14'
        baseline_diagnostics:
          type: object
          properties:
            status:
              type: string
              enum:
                - usable
                - missing
                - blocked
            checked_at:
              $ref: '#/components/schemas/Shared11'
            baseline_id:
              anyOf:
                - $ref: '#/components/schemas/Shared19'
                - type: 'null'
            reason_codes:
              $ref: '#/components/schemas/Shared20'
            observations:
              type: array
              items:
                type: object
                properties:
                  observation_id:
                    $ref: '#/components/schemas/Shared19'
                  eligible:
                    type: boolean
                  reasons:
                    $ref: '#/components/schemas/Shared20'
                required:
                  - observation_id
                  - eligible
                  - reasons
                additionalProperties: false
            history_limit_reached:
              type: boolean
          required:
            - status
            - checked_at
            - baseline_id
            - reason_codes
            - observations
            - history_limit_reached
          additionalProperties: false
        execution_available:
          type: boolean
          const: false
        execution_note:
          type: string
        offer_email:
          type: object
          properties:
            request_enabled:
              type: boolean
            permitted:
              type: boolean
            questions_emailed:
              type: boolean
              description: >-
                Whether questions about this Request are emailed to the user.
                False while email updates for it are off: tell the user they
                could miss an offer, and answer questions you receive.
            consent_url:
              description: Owner-only URL.
              type:
                - string
                - 'null'
          required:
            - request_enabled
            - permitted
            - questions_emailed
            - consent_url
          additionalProperties: false
        reachability:
          type: array
          items:
            type: object
            properties:
              channel:
                type: string
                enum:
                  - email
                  - poll
              status:
                type: string
                enum:
                  - active
                  - revoked
              verified_at:
                $ref: '#/components/schemas/Shared9'
              expected_check_hours:
                anyOf:
                  - type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  - type: 'null'
              last_polled_at:
                $ref: '#/components/schemas/Shared9'
              last_delivered_at:
                $ref: '#/components/schemas/Shared9'
            required:
              - channel
              - status
              - verified_at
              - expected_check_hours
              - last_polled_at
              - last_delivered_at
            additionalProperties: false
        agent_events:
          type: array
          items:
            type: object
            properties:
              id:
                $ref: '#/components/schemas/Shared19'
              event_name:
                type: string
                enum:
                  - request.research_updated
                  - request.plan_prepared
                  - request.plan_context_changed
                  - request.question_asked
                  - request.payment_updated
              status:
                type: string
                enum:
                  - active
                  - revoked
              expires_at:
                $ref: '#/components/schemas/Shared11'
              last_delivered_at:
                $ref: '#/components/schemas/Shared9'
            required:
              - id
              - event_name
              - status
              - expires_at
              - last_delivered_at
            additionalProperties: false
        polling_access:
          type: array
          items:
            type: object
            properties:
              id:
                $ref: '#/components/schemas/Shared19'
              expires_at:
                $ref: '#/components/schemas/Shared11'
              last_polled_at:
                $ref: '#/components/schemas/Shared9'
            required:
              - id
              - expires_at
              - last_polled_at
            additionalProperties: false
        email_delivery:
          type: string
          enum:
            - local_inbox
            - configured
            - unconfigured
        history:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              occurred_at:
                $ref: '#/components/schemas/Shared11'
              payload:
                type: object
                propertyNames:
                  type: string
                additionalProperties: {}
            required:
              - type
              - occurred_at
              - payload
            additionalProperties: false
        compatible_demand:
          type: array
          items:
            type: object
            properties:
              id:
                $ref: '#/components/schemas/Shared19'
              title:
                type: string
              compatibility_rule:
                type: string
              geography_scope:
                type: string
              active_intents:
                type: string
              count_kind:
                type: string
                const: active_requests
              executable_units:
                type: number
                const: 0
              observed_at:
                $ref: '#/components/schemas/Shared11'
            required:
              - id
              - title
              - compatibility_rule
              - geography_scope
              - active_intents
              - count_kind
              - executable_units
              - observed_at
            additionalProperties: false
        possible_duplicate_of:
          description: >-
            Open Requests of the same owner that closely match this new one: the
            same exact product references, the same top Need option set or the
            same words, with an overlapping destination. The new Request was
            saved anyway. If one is for the same thing, ask the person which to
            keep, then update or close the other so they are counted once.
          maxItems: 5
          type: array
          items:
            type: object
            properties:
              id:
                $ref: '#/components/schemas/Shared19'
              match:
                type: string
                enum:
                  - same_products
                  - same_options
                  - same_text
            required:
              - id
              - match
            additionalProperties: false
        duplicate_hint:
          type:
            - string
            - 'null'
        save_confirmation:
          type: object
          properties:
            saved:
              type: boolean
              const: true
            status:
              type: string
              enum:
                - draft
                - active
                - closed
            counts_as:
              type: string
              enum:
                - interest_with_price_limit
                - interest_only
            message:
              type: string
            order_created:
              type: boolean
              const: false
            payment_taken:
              type: boolean
              const: false
            deal_promised:
              type: boolean
              const: false
          required:
            - saved
            - status
            - counts_as
            - message
            - order_created
            - payment_taken
            - deal_promised
          additionalProperties: false
        needs_attention:
          type: array
          items:
            type: string
            enum:
              - new_offer
              - open_question
              - details_needed
              - still_want
              - offer_ending
        attention:
          $ref: '#/components/schemas/Shared10'
        next_step:
          description: The one next step, or null.
          type:
            - string
            - 'null'
        message:
          description: What to tell the person.
          type: string
        agent_line:
          description: What the agent does next.
          type: string
        open_questions:
          description: >-
            Questions to answer with POST /api/purchases/{id}/answers before
            their deadline.
          type: array
          items:
            type: object
            propertyNames:
              type: string
            additionalProperties: {}
        notifications:
          type: object
          properties:
            request_id:
              type:
                - string
                - 'null'
            offer_alerts:
              type:
                - boolean
                - 'null'
            check_frequency:
              type: string
            check_channels:
              type: string
            agent_reachability:
              type: array
              items:
                type: object
                properties:
                  channel:
                    type: string
                  enabled:
                    type: boolean
                  expected_check_hours:
                    type:
                      - number
                      - 'null'
                required:
                  - channel
                  - enabled
                  - expected_check_hours
                additionalProperties: false
          required:
            - request_id
            - offer_alerts
            - check_frequency
            - check_channels
            - agent_reachability
          additionalProperties: false
        supplier_text_is_untrusted:
          type: boolean
          const: true
        untrusted_text_fields:
          maxItems: 20
          type: array
          items:
            type: string
      required:
        - blockers
        - next_actions
        - as_of
        - id
        - status
        - version
        - original_raw_request
        - raw_request
        - country
        - currency
        - destination
        - time_horizon
        - need_by
        - items
        - price_limits
        - delivery
        - all_items_required
        - resolution_status
        - research_status
        - source
        - created_via
        - origin_client_id
        - created_at
        - updated_at
        - expires_at
        - activated_at
        - last_reaffirmed_at
        - closed_at
        - closed_reason
        - observations
        - baseline
        - pricing
        - baseline_diagnostics
        - execution_available
        - execution_note
        - reachability
        - agent_events
        - polling_access
        - email_delivery
        - history
        - compatible_demand
      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
    Shared17:
      type: string
      format: date
      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])))$
    Shared5:
      type: object
      properties:
        brand:
          type: string
          minLength: 1
          maxLength: 200
        model:
          type: string
          minLength: 1
          maxLength: 200
        url:
          type: string
          maxLength: 2000
          format: uri
        attributes:
          $ref: '#/components/schemas/Shared18'
      additionalProperties: false
    Shared21:
      type: array
      items:
        type: object
        properties:
          code:
            type: string
          actor:
            type: string
          message:
            type: string
        required:
          - code
          - actor
          - message
        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'
    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)$
    Shared9:
      anyOf:
        - $ref: '#/components/schemas/Shared11'
        - type: 'null'
    Shared18:
      maxItems: 20
      type: array
      items:
        $ref: '#/components/schemas/Shared22'
    Shared1:
      type: object
      properties:
        outcome_description:
          type: string
          minLength: 3
          maxLength: 500
        item_minor:
          default: null
          anyOf:
            - type: integer
              exclusiveMinimum: 0
              maximum: 100000000
            - type: 'null'
        shipping_minor:
          default: null
          anyOf:
            - type: integer
              minimum: 0
              maximum: 100000000
            - type: 'null'
        tax_minor:
          default: null
          anyOf:
            - type: integer
              minimum: 0
              maximum: 100000000
            - type: 'null'
        duties_minor:
          default: null
          anyOf:
            - type: integer
              minimum: 0
              maximum: 100000000
            - type: 'null'
        total_minor:
          default: null
          anyOf:
            - type: integer
              exclusiveMinimum: 0
              maximum: 100000000
            - type: 'null'
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          enum:
            - USD
            - ILS
        source_url:
          type: string
          maxLength: 2000
          format: uri
        seller_name:
          type: string
          minLength: 1
          maxLength: 200
        observed_at:
          $ref: '#/components/schemas/Shared11'
        valid_until:
          $ref: '#/components/schemas/Shared11'
        availability:
          type: string
          enum:
            - available
            - unavailable
            - unknown
        terms:
          $ref: '#/components/schemas/Shared8'
        confidence_note:
          type: string
          minLength: 10
          maxLength: 2000
        id:
          $ref: '#/components/schemas/Shared19'
        review_status:
          type: string
          enum:
            - provisional
            - verified
            - rejected
      required:
        - outcome_description
        - item_minor
        - shipping_minor
        - tax_minor
        - duties_minor
        - total_minor
        - currency
        - source_url
        - seller_name
        - observed_at
        - valid_until
        - availability
        - terms
        - confidence_note
        - id
        - review_status
      additionalProperties: {}
    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
    Shared20:
      type: array
      items:
        type: string
        enum:
          - context_changed
          - future_observation
          - superseded
          - needs_review
          - rejected
          - not_comparable
          - incomplete_total
          - unavailable
          - availability_unknown
          - expired
    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
    Shared22:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        value:
          type: string
          minLength: 1
          maxLength: 100
      required:
        - name
        - value
      additionalProperties: false
    Shared8:
      type: object
      properties:
        warranty:
          type: string
          maxLength: 2000
        returns:
          type: string
          maxLength: 2000
        delivery:
          type: string
          maxLength: 2000
        legitimacy:
          type: string
          maxLength: 2000
        comparable:
          default: false
          type: boolean
        all_in_confirmed:
          default: false
          type: boolean
      required:
        - warranty
        - returns
        - delivery
        - legitimacy
        - comparable
        - all_in_confirmed
      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.