Data Marketplace

Search, Get, Quote and Run

Four steps cover buying. The first three need no API key.

# 1. Search the catalog (free, keyless)
curl "https://api.alterlab.io/api/v1/listings?q=coffee+shops&limit=5"

# 2. Read one listing: manifest, input schema, price and reliability
curl https://api.alterlab.io/api/v1/listings/SLUG

# 3. Quote a run (free, keyless, nothing is reserved)
curl -X POST https://api.alterlab.io/api/v1/listings/SLUG/quote \
  -H "Content-Type: application/json" \
  -d '{"max_results": 100}'

# 4. Run it (API key with the scrape scope)
curl -X POST "https://api.alterlab.io/api/v1/listings/SLUG/run?wait=true" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"input": {"query": "coffee shops in Austin"}, "max_results": 100}'

Take SLUG from the search results. The input object must match the listing's input_schema; invalid input returns field errors and reserves nothing. Search takes q, category, limit (1 to 100) and offset.

Price and max_results

A listing is priced per valid result. The quote returns unit_microcents (the price of one result), the split between base_unit_microcents and the seller's markup_unit_microcents, and max_cost_microcents for max_results. Credits are microcents: 1,000,000 equals $1.00.

max_results is a hard cap (1 to 10,000, default 100). A run reserves the quoted maximum, bills only the valid results and refunds the rest. A run that returns nothing valid is refunded in full and answers with blocked_upstream. A key spend limit is applied on top: an over-limit run fails with spend_cap_exceeded.

Reliability

GET /api/v1/listings/{slug} returns a reliability object with success_rate, the runs sample behind it, customer_runs, canary_runs, window_days, p50_latency_ms and last_test_run_at, plus a health snapshot. A success_rate of null means there are too few runs to say. Every listing is probed on a schedule with its own test inputs, so the figure does not depend on buyer traffic alone. A listing in degraded status still runs; run errors carry listing_degraded and a next_action with a retry hint.

Keyless and Keyed Calls

Search, get and quote are open: no key, no account. Running needs an API key with the scrape scope, or an x402 payment for callers that have no account. Run results come back inline with wait=true (up to about 25 seconds). A longer run answers 202 with a run_id; poll GET /api/v1/listings/runs/{run_id} and read the records from GET /api/v1/listings/runs/{run_id}/results (limit up to 1,000). GET /api/v1/listings/runs lists your run history.

Feeds

A feed runs a listing on a cron and delivers only what changed. Each run sends one signed webhook with the new, changed and removed entities.

curl -X POST https://api.alterlab.io/api/v1/listings/SLUG/feeds \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {"query": "coffee shops in Austin"},
    "cron_expression": "0 6 * * *",
    "timezone": "UTC",
    "webhook_url": "https://example.com/hooks/alterlab",
    "monthly_cap_microcents": 5000000
  }'

• The monthly cap is hard. The feed stops with status capped instead of exceeding it, and only valid results are billed. Raising the cap does not resume a capped feed; set status to active as well.
• A schedule that fires more often than the server minimum (60 minutes by default) is rejected with a 422.
• delivery_mode is delta (only changes, the default) or full (every result). max_results limits results per run.
• The create response returns the feed, its expected_monthly_cost_microcents and the webhook secret once. Deliveries carry X-AlterLab-Signature: sha256=HMAC_SHA256("{timestamp}.{body}").
• Some AlterLab Official listings ship feed presets. Pass preset to take its cron (monthly_cap_microcents is still required); the preset names are listed in the alterlab_feed_create tool description.

Manage a feed with GET, PATCH and DELETE on /api/v1/listings/{slug}/feeds/{feed_id}, and list a listing's feeds with GET /api/v1/listings/{slug}/feeds. Read delivered runs, newest first, with GET /api/v1/listings/feeds/{feed_id}/deltas (page, page_size, format=ndjson).

A delta run looks like this:

{
  "run_id": "5f0c...",
  "status": "completed",
  "dataset_version": 7,
  "new": [{"name": "Blue Door Coffee", "rating": 4.6}],
  "changed": [{"key": "...", "previous": {"rating": 4.2}, "current": {"rating": 4.4}}],
  "removed": [{"name": "Old Roast Co"}]
}

MCP Tools

Nine buy-side tools cover the whole flow:

• alterlab_store_search, alterlab_store_get and alterlab_store_quote: keyless catalog reads and quotes.
• alterlab_store_run: run a listing (needs a key with the scrape scope; wait defaults to true).
• alterlab_feed_create, alterlab_feed_list, alterlab_feed_update, alterlab_feed_delete and alterlab_feed_deltas: manage feeds and read their deltas.

Selling uses three more tools; see selling on the marketplace.

Per-Listing agent.md

Every listing has a setup document written for an AI agent at https://store.alterlab.io/{slug}/agent.md. It is generated from the listing manifest, so the input schema, example call and price cannot drift. It walks an agent through connecting the MCP server, getting human-approved access, quoting and running within a cap. The Copy prompt button on each listing page hands that URL to your agent.