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

# Get questions

> Read up to 10 recent targeted questions for an owned Request from the last 30 days, newest first, with allowed typed answers, deadline, status and latest typed answer. Requires verified ownership; OAuth agents also need read permission and this Request in scope. Private capabilities are not accepted. Free-text replies and operator identity are never returned. Reading neither answers a question nor reaffirms interest. Answer with POST /api/purchases/{id}/answers.



## OpenAPI

````yaml /api-reference/openapi/questions.json get /api/purchases/{id}/questions
openapi: 3.1.0
info:
  title: 'Popular Demand Requests: Questions'
  version: 0.4.0
  x-api-version: '2026-11-20'
  description: >-
    Read a Request's questions and answer them. 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: Questions
    description: Read a Request's questions and answer them.
paths:
  /api/purchases/{id}/questions:
    get:
      tags:
        - Questions
      summary: Get questions
      description: >-
        Read up to 10 recent targeted questions for an owned Request from the
        last 30 days, newest first, with allowed typed answers, deadline, status
        and latest typed answer. Requires verified ownership; OAuth agents also
        need read permission and this Request in scope. Private capabilities are
        not accepted. Free-text replies and operator identity are never
        returned. Reading neither answers a question nor reaffirms interest.
        Answer with POST /api/purchases/{id}/answers.
      operationId: getRequestQuestions
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Shared3'
        - 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:
                $ref: '#/components/schemas/RequestQuestions'
          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:
    Shared3:
      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)$
    RequestQuestions:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        request_id:
          $ref: '#/components/schemas/Shared3'
        as_of:
          $ref: '#/components/schemas/Shared1'
        questions:
          maxItems: 10
          type: array
          items:
            type: object
            properties:
              question_id:
                $ref: '#/components/schemas/Shared3'
              batch_id:
                $ref: '#/components/schemas/Shared3'
              request_id:
                $ref: '#/components/schemas/Shared3'
              request_version:
                type: integer
                exclusiveMinimum: 0
                maximum: 9007199254740991
              context:
                type: object
                properties:
                  opportunity_id:
                    $ref: '#/components/schemas/Shared2'
                  rfq_id:
                    $ref: '#/components/schemas/Shared2'
                  offer_id:
                    $ref: '#/components/schemas/Shared2'
                  offer_version:
                    anyOf:
                      - type: integer
                        exclusiveMinimum: 0
                        maximum: 9007199254740991
                      - type: 'null'
                required:
                  - opportunity_id
                  - rfq_id
                  - offer_id
                  - offer_version
                additionalProperties: false
              questions:
                minItems: 1
                maxItems: 5
                type: array
                items:
                  oneOf:
                    - type: object
                      properties:
                        key:
                          type: string
                          pattern: ^[a-z][a-z0-9_]{0,39}$
                        kind:
                          type: string
                          const: yes_no
                        prompt:
                          type: string
                          minLength: 1
                          maxLength: 300
                      required:
                        - key
                        - kind
                        - prompt
                      additionalProperties: false
                    - type: object
                      properties:
                        key:
                          type: string
                          pattern: ^[a-z][a-z0-9_]{0,39}$
                        kind:
                          type: string
                          const: choice
                        prompt:
                          type: string
                          minLength: 1
                          maxLength: 300
                        choices:
                          minItems: 2
                          maxItems: 10
                          type: array
                          items:
                            type: string
                            minLength: 1
                            maxLength: 80
                      required:
                        - key
                        - kind
                        - prompt
                        - choices
                      additionalProperties: false
                    - type: object
                      properties:
                        key:
                          type: string
                          pattern: ^[a-z][a-z0-9_]{0,39}$
                        kind:
                          type: string
                          const: value
                        prompt:
                          type: string
                          minLength: 1
                          maxLength: 300
                        value_type:
                          type: string
                          enum:
                            - integer
                            - number
                            - money_minor
                        unit:
                          type: string
                          minLength: 1
                          maxLength: 20
                        min:
                          type: number
                        max:
                          type: number
                      required:
                        - key
                        - kind
                        - prompt
                        - value_type
                      additionalProperties: false
              reason:
                type: string
              status:
                type: string
                enum:
                  - open
                  - answered
                  - needs_interpretation
                  - expired
                  - cancelled
                  - superseded
              counted:
                type: boolean
              deadline:
                $ref: '#/components/schemas/Shared1'
              asked_at:
                $ref: '#/components/schemas/Shared1'
              latest_answer:
                anyOf:
                  - type: object
                    properties:
                      status:
                        type: string
                        enum:
                          - accepted
                          - needs_interpretation
                      answered_by:
                        type: string
                        enum:
                          - agent_connection
                          - email_grant
                          - owner
                      answers:
                        anyOf:
                          - minItems: 1
                            maxItems: 5
                            type: array
                            items:
                              type: object
                              properties:
                                key:
                                  type: string
                                  pattern: ^[a-z][a-z0-9_]{0,39}$
                                value:
                                  anyOf:
                                    - type: boolean
                                    - type: number
                                    - type: string
                                      maxLength: 80
                                    - type: 'null'
                              required:
                                - key
                                - value
                              additionalProperties: false
                          - type: 'null'
                      counted:
                        type: boolean
                      recorded_at:
                        $ref: '#/components/schemas/Shared1'
                    required:
                      - status
                      - answered_by
                      - answers
                      - counted
                      - recorded_at
                    additionalProperties: false
                  - type: 'null'
            required:
              - question_id
              - batch_id
              - request_id
              - request_version
              - context
              - questions
              - reason
              - status
              - counted
              - deadline
              - asked_at
              - latest_answer
            additionalProperties: false
        execution_available:
          type: boolean
          const: false
      required:
        - request_id
        - as_of
        - questions
        - execution_available
      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
    Shared1:
      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)))$
    Shared2:
      anyOf:
        - $ref: '#/components/schemas/Shared3'
        - type: 'null'
  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.