Developers

Read the register, from any agent.

One record, six channels. Everything below is generated from the dataset packs, so a new dataset — any niche, any country — shows up in every channel without new code.

Agent quickstart

If you are an AI agent, start at /llms.txt — citation rules, the recommended call order, every URL pattern and what never to invent. Each dataset has its own guide at /v1/{dataset}/llms.txt with the exact filter names (generated from its schema) and its MCP tools.

# 1. which datasets exist            (free)
curl https://robotsdataset.com/v1/datasets
# 2. is the data fresh? what filters? (free)
curl https://robotsdataset.com/v1/auto_service_sofia/status
curl https://robotsdataset.com/v1/auto_service_sofia/llms.txt
# 3. which values does a filter accept? (free)
curl "https://robotsdataset.com/v1/auto_service_sofia/facets?by=district"
# 4. search, asking only for the fields you need
curl -H "Authorization: Bearer $DBG_KEY" \
  "https://robotsdataset.com/v1/auto_service_sofia/entities?services=oil_change&fields=name,price.oil_change_eur&total=true&limit=20"
# 5. full records (batch), then cite with the `attribution` string
curl -H "Authorization: Bearer $DBG_KEY" "https://robotsdataset.com/v1/auto_service_sofia/entities/batch?ids={id1},{id2}"

Machine entry points: /llms.txt · /v1/datasets · /v1/catalog (linkset) · /openapi.json · MCP server card · https://robotsdataset.com/ with Accept: application/json returns the same map.

REST

Base URL https://robotsdataset.com/v1. Free: catalog, schema, llms.txt, 20 public-field previews per day per IP. Paid: search, get, facts, prices, compare, stats (prices per dataset on Pricing). Auth: Authorization: Bearer dbg_… (or X-API-Key).

# catalog + schema (free)
curl https://robotsdataset.com/v1/datasets
curl https://robotsdataset.com/v1/auto_service_sofia/schema

# search with filters generated from the schema
curl -H "Authorization: Bearer $DBG_KEY" \
  "https://robotsdataset.com/v1/auto_service_sofia/entities?services=oil_change&max_price.oil_change_eur=400&district=…&sort=price.oil_change_eur&limit=10"

# one record with provenance + freshness, then its history
curl -H "Authorization: Bearer $DBG_KEY" https://robotsdataset.com/v1/auto_service_sofia/entities/{id}
curl -H "Authorization: Bearer $DBG_KEY" "https://robotsdataset.com/v1/auto_service_sofia/entities/{id}/facts?attribute=price.oil_change_eur"

# geo + full text + cursor paging
curl -H "Authorization: Bearer $DBG_KEY" "https://robotsdataset.com/v1/auto_service_sofia/entities?near=LAT,LNG,3&q=…&limit=50"
# -> {"items":[…],"next_cursor":"…"}  then &cursor=…

Filter rules (generated from each dataset's schema; the full list with types is GET /v1/{dataset}/schema → filters, and /v1/{dataset}/llms.txt lists them in prose):

• <attr>=value for strings, enums and arrays — case-insensitive, comma = any of (chain.slug=lidl,billa); like_<attr>= substring; not_<attr>= none of.
• min_<attr> / max_<attr> for numbers and price ranges (max_ compares the range's minimum: "within budget").
• has_<attr>=true|false presence · q= full text, every word prefix-matched · near=lat,lng,km · sort=<attr>|-<attr>|quality|updated.
• Shaping: fields=a,b.c (only these attributes, provenance trimmed to match) · total=true (match count) · ids=a,b · updated_since=<ISO> · min_quality= · format=md|csv|ndjson (csv/ndjson: up to 1000 rows per page with a key, X-Next-Cursor header).
• An unknown filter name returns 400 naming it — nothing is silently ignored.

Every paid response carries provenance (source_url, observed_at, confidence, evidence per attribute), freshness (age in hours per attribute), quality_score, completeness, verified_owner and the license.

Facets, batch, similar, stats, timeseries, status

# which values exist for a filter, with counts (free; other filters narrow the set)
curl "https://robotsdataset.com/v1/auto_service_sofia/facets?by=district&limit=50"
# dataset health: counts, median value age, share within SLA, last/next collection run (free)
curl https://robotsdataset.com/v1/auto_service_sofia/status
# up to 100 full records in one call (priced as get × n), unknown ids listed in `missing`
curl -H "Authorization: Bearer $DBG_KEY" "https://robotsdataset.com/v1/auto_service_sofia/entities/batch?ids={id1},{id2}&fields=name,price.oil_change_eur"
# the most similar records by name, only in *other* groups (dataset default differ_by)
curl -H "Authorization: Bearer $DBG_KEY" "https://robotsdataset.com/v1/auto_service_sofia/entities/{id}/similar?limit=5"
# median / quartiles / mean of a numeric attribute; two group keys = a table
curl -H "Authorization: Bearer $DBG_KEY" "https://robotsdataset.com/v1/auto_service_sofia/stats?attribute=price.oil_change_eur&group_by=district"
# the same attribute over time, as of each day, from the fact history
curl -H "Authorization: Bearer $DBG_KEY" "https://robotsdataset.com/v1/auto_service_sofia/timeseries?attribute=price.oil_change_eur&days=90&step=week&group_by=district"
# up to 5 records side by side
curl -H "Authorization: Bearer $DBG_KEY" "https://robotsdataset.com/v1/auto_service_sofia/compare?ids={id1},{id2}"

facets and status are free. batch costs get × ids, similar costs a search, timeseries costs a stats call. All of them take the same filters as search. Every one has a Markdown twin (.md).

Markdown mode (≈ 70–80% fewer tokens)

curl -H "Accept: text/markdown" -H "Authorization: Bearer $DBG_KEY" \
  "https://robotsdataset.com/v1/auto_service_sofia/entities?services=oil_change&limit=20"
# or append .md to any /v1 path: https://robotsdataset.com/v1/auto_service_sofia/entities/{id}.md

Search returns a compact table; a single entity returns the dataset's Markdown template (the same text an MCP resource returns). Every JSON response carries an attribution string — a ready-to-paste citation with a link to the record page — and a license.

llms.txt family

• /llms.txt — what this site is, one line per dataset.
• /v1/{dataset}/llms.txt — the dataset guide: what a record is, example queries, Query parameters (exact filter names, generated from the schema), MCP tools with parameters and prices, fields, sample records. Also an MCP tool: dataset_guide.
• /v1/{dataset}/status — health and freshness; /v1/{dataset}/facets?by= — the values a filter accepts.
• /v1/{dataset}/llms-full.txt — every record with public fields, regenerated nightly.
• /v1/{dataset}/examples (.md) — free real records with every field and provenance: the best few per group (district, category…), to see the data before buying.
• /v1/{dataset}/changelog (.md) — free public changelog: values that appeared or changed, newest first; the full feed for subscribers is /changes?since=.
• /v1/catalog — RFC 9264 linkset of every machine entry point; /.well-known/mcp/server-card.json — MCP discovery card.
• /.well-known/datasets.jsonld — schema.org Dataset graph; every HTML page also embeds JSON-LD.

MCP (streamable HTTP)

Endpoint https://robotsdataset.com/mcp. Free platform tools: datasets_list, dataset_guide (the llms.txt), dataset_schema, dataset_status, dataset_facets, dataset_examples, dataset_samples, dataset_changelog. Paid: entity_search (filters dict in the grammar above, plus fields, total, ids), entity_get, entity_batch, entity_similar, entity_history, dataset_timeseries; and one tool per pack entry, named with underscores (e.g. garage_search, garage_get, garage_prices, garage_compare) — the generated search/get tools also accept fields. Tool errors come back as {error, is_retriable}. Resources: robotsdataset://{dataset}/llms.txt, robotsdataset://{dataset}/entity/{id}. The server's instructions describe the recommended call order.

Claude Desktop

{
  "mcpServers": {
    "robotsdataset": {
      "type": "http",
      "url": "https://robotsdataset.com/mcp",
      "headers": { "Authorization": "Bearer dbg_…" }
    }
  }
}

Claude Code

claude mcp add --transport http robotsdataset https://robotsdataset.com/mcp \
  --header "Authorization: Bearer dbg_…"

Without a key, tools answer with the same 402 payload as REST (price + how to pay), so an agent can decide to pay via x402 or ask its operator for a key.

x402 — pay per request, no account

When enabled, a request without payment gets 402 with a PAYMENT-REQUIRED header (USDC or USDT on Base, price from the dataset pack; USDT settles through Permit2). The agent signs the payment, retries with PAYMENT-SIGNATURE, and receives the data plus PAYMENT-RESPONSE. Discovery: /.well-known/x402.json. Works with the official x402 client SDKs; nothing RobotsDataset-specific.

Apify

The Actor is a thin wrapper over REST with pay-per-event prices equal to the pack prices. Use it when you already run on Apify; otherwise call REST directly.

ETag, caching, rate limits

• ETag and Last-Modified on schema and record responses; a matching If-None-Match returns 304 before any charge or quota (on the HTML pages only preview responses are cached; a paid ?full=1 view is no-store).
• Rate limits: 60 requests/min per key or per IP for paid calls (per plan); free calls (guides, status, schema, facets, examples, changelog, catalog, HTML previews) have their own bucket of 300/min. Every gated response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset; 429 adds Retry-After and retry_after_seconds in the body.
• Pagination: opaque cursor (next_cursor), max 100 per page (1000 with format=csv|ndjson). Sort is stable. total=true adds the match count.

Errors

Every /v1 error is one JSON shape an agent can act on: {"error": "rate_limited", "message": "…", "is_retriable": true, "retry_after_seconds": 12, "alternative_action": "…", "documentation_url": "https://robotsdataset.com/llms.txt", "detail": …}. 402 keeps its price_eur / price_usd / how_to_pay.

Interactive OpenAPI: /docs. Opt-out for businesses: DELETE /v1/optout. Questions: webmaster@robotsdataset.com.