Dataset contract

What an agent needs before asking a dataset, from one free GET request: price, network, request and response formats, monthly offer.

Each published dataset describes itself at its own address. A GET is free and needs no account:

curl https://quarry.market/{username}/{slug}

Example

A dataset that sells single questions and a monthly subscription:

{
  "name": "Market outlook",
  "description": "Quarterly research on customer growth and self-serve adoption.",
  "payment": {
    "protocol": "x402",
    "price_usdc": 0.01,
    "network": "base",
    "caip2": "eip155:8453"
  },
  "request": {
    "method": "POST",
    "url": "https://quarry.market/alice/market-outlook",
    "content_type": "application/json",
    "body": {
      "query": "string, required, max 2000 chars",
      "top_k": "integer, optional, 1-20, default 5"
    }
  },
  "response": {
    "dataset": { "slug": "string", "name": "string" },
    "query": "string",
    "results": "array of { chunk_id, content, score, vector_score, text_score, … }"
  },
  "error_response": {
    "error": {
      "code": "string stable error code",
      "message": "string human-readable message",
      "details": "optional structured details"
    }
  },
  "listing": "https://quarry.market/explore/alice/market-outlook",
  "terms": "https://quarry.market/terms",
  "mcp": {
    "endpoint": "https://quarry.market/api/mcp",
    "transport": "streamable-http",
    "tools": ["search", "get_dataset", "ask", "quote_access", "get_my_access", "request_subscription", "x402_payment_guide"]
  },
  "subscription_offer": {
    "id": "f4b3a1a3-6eb9-42f2-8138-331f8c1eb0f6",
    "price_cents": 2900,
    "currency": "usd",
    "interval": "month",
    "quota": 3000,
    "license": "Use excerpts in internal analysis. Do not redistribute the source files."
  },
  "agent_mcp": "https://quarry.market/api/agent/mcp"
}

Fields

Field	Meaning
`name`, `description`	The dataset's name and description (`description` can be `null`)
`payment`	Paying per question with x402, or `null` when the dataset only sells subscriptions
`payment.price_usdc`	Price of one question in USDC, as a number. `0` means the dataset is free
`payment.network`, `payment.caip2`	The network to pay on: `base` / `eip155:8453`, or `base-sepolia` / `eip155:84532`
`request`	How to ask over HTTP: see Ask over HTTP
`response`, `error_response`	The answer and error formats. `results` names every field (shortened above): see Ask over HTTP and Error codes
`listing`	The dataset's public page
`terms`	The terms you accept by asking the dataset, with the rules on using passages
`mcp`	quarry's MCP server and its tools
`subscription_offer`	The monthly offer, when there is one: price in US cents, `quota` (questions a month), and the seller's usage terms
`agent_mcp`	The sign-in address, given with a monthly offer

Free and subscription-only datasets

Free: payment.price_usdc is 0. A POST answers without any payment.
Subscription only: payment is null and subscription_offer is set. Ask it with a subscription, over MCP or POST /api/agent/query: see the Subscription API.

The contract is public and the same for everyone: it doesn't say whether you subscribe. Call quote_access for that.

The contract is cached for up to a minute, and can be served stale for five more while it refreshes (Cache-Control: public, s-maxage=60, stale-while-revalidate=300). A price change can take that long to show here. The 402 from a POST always carries the current price.

A dataset that doesn't exist or isn't published answers 404 with { "error": { "code": "NOT_FOUND", "message": "Not found" } }. Subscribers keep access to a dataset the seller stopped selling until their paid month ends, through the Subscription API.

Dataset contract

Example

Fields

Free and subscription-only datasets

Caching and errors

On this page