{
  "openapi": "3.1.0",
  "info": {
    "title": "PressureDesk Agent API",
    "version": "0.1.0",
    "summary": "Read-only pressure-scored market intelligence for AI agents.",
    "description": "PressureDesk exposes fresh previews, paid snapshots, dossiers, freshness states, aggregate source health, and receipts for public market-pressure signals. Live wallet actions, token launches, trades, and external API mutations are outside the current boundary."
  },
  "servers": [
    {
      "url": "/",
      "description": "Current host"
    }
  ],
  "paths": {
    "/v1/agent-home": {
      "get": {
        "operationId": "getAutonomyForgeAgentHome",
        "summary": "Get the one-call agent storefront for AutonomyForge products.",
        "description": "Returns outcome-only product proof, product endpoints, pricing links, trust health, examples, and suggested next actions for buyer evaluation.",
        "responses": {
          "200": {
            "description": "Public-safe agent home packet."
          }
        }
      }
    },
    "/v1/meta": {
      "get": {
        "operationId": "getPressureDeskMeta",
        "summary": "Get product metadata and latest snapshot id.",
        "responses": {
          "200": {
            "description": "Product metadata."
          }
        }
      }
    },
    "/v1/founding-access": {
      "get": {
        "operationId": "getPressureDeskFoundingAccess",
        "summary": "Get the manual founding-access request packet.",
        "description": "Returns required request fields, disallowed secret fields, buyer proof links, and read-only safety boundaries. This route does not collect payment or accept submitted data.",
        "responses": {
          "200": {
            "description": "Founding-access request packet."
          }
        }
      }
    },
    "/v1/tools/evaluate": {
      "get": {
        "operationId": "evaluateAgentToolPurchase",
        "summary": "Evaluate whether an agent should call or pay a target tool before spending.",
        "description": "Returns a public-safe buy, wait, try-free, or avoid dossier with bounded maxSpendUsd, safety boundaries, machine-readable fit, receipt expectation, and next action.",
        "parameters": [
          {
            "name": "target",
            "in": "query",
            "required": true,
            "description": "Target HTTP URL for the API, MCP endpoint, or paid tool.",
            "schema": {
              "type": "string",
              "format": "uri"
            }
          },
          {
            "name": "task",
            "in": "query",
            "required": false,
            "description": "Short agent task the target would be used for.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "priceUsd",
            "in": "query",
            "required": false,
            "description": "Known or advertised per-call price in USD.",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Agent Tool Buyer Dossier."
          },
          "400": {
            "description": "Missing target query parameter."
          }
        }
      }
    },
    "/v1/tools/evaluate/paid": {
      "get": {
        "operationId": "getPaidAgentToolBuyerDossier",
        "summary": "Get the paid Agent Tool Buyer Dossier after x402 settlement or premium entitlement.",
        "description": "Without payment this returns a 402 x402 payment-required packet. With a valid payment signature or premium entitlement it returns the paid dossier, paidDepth delivery proof, operator notes, and persisted delivery receipt.",
        "parameters": [
          {
            "name": "target",
            "in": "query",
            "required": true,
            "description": "Target HTTP URL for the API, MCP endpoint, or paid tool.",
            "schema": {
              "type": "string",
              "format": "uri"
            }
          },
          {
            "name": "task",
            "in": "query",
            "required": false,
            "description": "Short agent task the target would be used for.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "priceUsd",
            "in": "query",
            "required": false,
            "description": "Known or advertised target per-call price in USD.",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paid Agent Tool Buyer Dossier with paidDepth and receipt."
          },
          "400": {
            "description": "Missing target or unsafe payment metadata."
          },
          "402": {
            "description": "x402 payment is required."
          },
          "409": {
            "description": "Duplicate payment or resource mismatch."
          },
          "503": {
            "description": "Payment verifier is not configured."
          }
        }
      }
    },
    "/v1/payments/live-status": {
      "get": {
        "operationId": "getPressureDeskLivePaymentStatus",
        "summary": "Read x402 and premium-entitlement readiness status.",
        "description": "Returns payment route, price, rail readiness, and hard-block reasons without exposing secrets or entitlement tokens.",
        "responses": {
          "200": {
            "description": "Live payment status."
          }
        }
      }
    },
    "/v1/snapshots/latest/preview": {
      "get": {
        "operationId": "previewLatestPressureSnapshot",
        "summary": "Get a redacted free preview of the latest pressure snapshot.",
        "responses": {
          "200": {
            "description": "Redacted snapshot preview."
          },
          "404": {
            "description": "No snapshot exists."
          },
          "409": {
            "description": "Latest snapshot is stale."
          }
        }
      }
    },
    "/v1/snapshots/latest": {
      "get": {
        "operationId": "getLatestPressureSnapshot",
        "summary": "Get the full latest pressure snapshot or a payment-required response.",
        "responses": {
          "200": {
            "description": "Full delivered snapshot and receipt."
          },
          "402": {
            "description": "Modeled payment is required before full delivery."
          },
          "404": {
            "description": "No snapshot exists."
          },
          "409": {
            "description": "Latest snapshot is stale."
          }
        }
      }
    },
    "/v1/entities/{entityId}/dossier": {
      "get": {
        "operationId": "getPressureDossier",
        "summary": "Get a full evidence-backed pressure dossier by public preview id.",
        "description": "Returns payment-required metadata without entitlement, or customer-only dossier depth plus an agentCommerceDossier buyer packet after modeled payment.",
        "parameters": [
          {
            "name": "entityId",
            "in": "path",
            "required": true,
            "description": "Public preview id from the latest snapshot preview.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Entity dossier."
          },
          "402": {
            "description": "Modeled payment is required before dossier delivery."
          },
          "404": {
            "description": "Dossier not found."
          }
        }
      }
    },
    "/v1/freshness": {
      "get": {
        "operationId": "getPressureDeskFreshness",
        "summary": "Check whether the latest snapshot is fresh, stale, or missing.",
        "responses": {
          "200": {
            "description": "Freshness state."
          },
          "404": {
            "description": "No snapshot exists."
          }
        }
      }
    },
    "/v1/source-health": {
      "get": {
        "operationId": "getPressureDeskSourceHealth",
        "summary": "Read aggregate source health, source mode, freshness, trust reasons, and safe error codes.",
        "responses": {
          "200": {
            "description": "Source health reports."
          }
        }
      }
    },
    "/v1/receipts/{paymentIdentifier}": {
      "get": {
        "operationId": "getPressureDeskReceipt",
        "summary": "Verify a local modeled delivery receipt.",
        "parameters": [
          {
            "name": "paymentIdentifier",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Receipt found."
          },
          "404": {
            "description": "Receipt not found."
          }
        }
      }
    },
    "/v1/feedback/schema": {
      "get": {
        "operationId": "getPressureDeskFeedbackSchema",
        "summary": "Get the private feedback request schema.",
        "description": "Returns the JSON shape agents can use to submit private buyer feedback after preview or paid delivery.",
        "responses": {
          "200": {
            "description": "Feedback request schema."
          }
        }
      }
    },
    "/v1/feedback": {
      "post": {
        "operationId": "submitPressureDeskFeedback",
        "summary": "Submit private buyer feedback.",
        "description": "Accepts private feedback about buyer need, usefulness, missing value, and willingness-to-pay. Rejects secret-bearing content.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "need"
                ],
                "properties": {
                  "buyerKind": {
                    "type": "string",
                    "enum": [
                      "agent",
                      "human-owner",
                      "builder",
                      "operator",
                      "other"
                    ]
                  },
                  "route": {
                    "type": "string"
                  },
                  "need": {
                    "type": "string",
                    "maxLength": 1200
                  },
                  "useful": {
                    "type": "boolean"
                  },
                  "missingValue": {
                    "type": "string",
                    "maxLength": 1200
                  },
                  "willingnessToPayUsd": {
                    "type": "number",
                    "minimum": 0
                  },
                  "contact": {
                    "type": "string",
                    "maxLength": 220
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Feedback accepted as private demand signal."
          },
          "400": {
            "description": "Missing need or secret-bearing feedback."
          },
          "413": {
            "description": "Request too large."
          },
          "415": {
            "description": "JSON content type required."
          }
        }
      }
    }
  }
}