# Dataset contract (/docs/api)

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

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

## Example [#example]

A dataset that sells single questions and a monthly subscription:

```json
{
  "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 [#fields]

| Field                              | Meaning                                                                                                                                                             |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`, `description`              | The dataset's name and description (`description` can be `null`)                                                                                                    |
| `payment`                          | Paying per question with [x402](/docs/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](/docs/api/query)                                                                                                          |
| `response`, `error_response`       | The answer and error formats. `results` names every field (shortened above): see [Ask over HTTP](/docs/api/query#result-fields) and [Error codes](/docs/api/errors) |
| `listing`                          | The dataset's public page                                                                                                                                           |
| `terms`                            | The [terms](/terms) you accept by asking the dataset, with the rules on [using passages](/terms#using-passages)                                                     |
| `mcp`                              | quarry's [MCP server](/docs/mcp) 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-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](/docs/api/subscriptions).

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

## Caching and errors [#caching-and-errors]

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](/docs/api/subscriptions).