openapi: 3.0.3
info:
  title: Cridora Public API
  version: "1.0"
  description: >
    Read-only, unauthenticated endpoints for live Cridora gold/silver rates
    and a UAE market rate comparison. All other Cridora APIs require an
    authenticated human session and are out of scope for agents — see
    https://cridora.com/llms.txt for what not to attempt.
  contact:
    email: support@cridora.com
servers:
  - url: https://cridora.com/api
paths:
  /pricing/public/:
    get:
      operationId: getPublicPricingBoard
      summary: Live Cridora buy/sellback rates for gold and silver
      description: >
        Cridora's own live rate (AED per gram), not a generic spot price.
        Cached briefly server-side; poll no more than once every few
        seconds.
      responses:
        "200":
          description: Current rate board
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicPricingBoard"
  /pricing/competitors/:
    get:
      operationId: getCompetitorMatrix
      summary: Indicative UAE market rate comparison matrix
      description: >
        Indicative third-party UAE retail/market rates gathered for
        comparison. May return a 503 with an empty row set if upstream
        sources are temporarily unavailable.
      parameters:
        - name: refresh
          in: query
          required: false
          schema:
            type: string
            enum: ["1"]
          description: Pass refresh=1 to force a fresh fetch instead of the cached matrix.
      responses:
        "200":
          description: Comparison matrix
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "503":
          description: Upstream comparison sources temporarily unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  rows:
                    type: array
                    items: {}
components:
  schemas:
    PublicPricingBoard:
      type: object
      properties:
        currency:
          type: string
          example: AED
        unit:
          type: string
          example: per_gram
        updated_at:
          type: string
          format: date-time
        live:
          type: boolean
          description: Whether both upstream international and retail feeds are currently healthy.
        gold:
          $ref: "#/components/schemas/MetalRate"
        silver:
          $ref: "#/components/schemas/MetalRate"
    MetalRate:
      type: object
      properties:
        purity:
          type: string
          example: "24K"
        sell:
          type: number
          nullable: true
          description: Cridora's live buy price, AED per gram.
        sellback:
          type: number
          nullable: true
          description: Cridora's live sellback price, AED per gram.
        updated_at:
          type: string
          format: date-time
