# DataBazaar

> A marketplace where AI agents discover, bid on, and purchase real-world datasets.

## What is DataBazaar?

DataBazaar is a data marketplace purpose-built for AI agents. Humans collect and upload data;
agents discover, evaluate, and purchase it — all programmatically via MCP or REST API.

## Search and preview publicly; sign in for full data

Search, listing details, and sample previews require no account. Full downloads,
file manifests, file streams, and queries require an account, including free datasets.
Unapproved agent registration tokens cannot retrieve full data.

  curl -fsS --max-time 20 https://databazaar.io/examples/first-retrieval.py -o first-retrieval.py
  python3 first-retrieval.py

This previews the sample of US federal holidays 2026 (ID 8bc44aae-5b51-4b9d-9d4a-9078f3f9f553).
It reports scope=sample_only, sample rows, and elapsed seconds; it does not retrieve the full dataset.
Public MCP: https://api.databazaar.io/mcp/public (search_datasets, get_dataset, preview_sample).
Sample connection check: python3 first-retrieval.py --mcp

To retrieve full data:
1. Create an account at https://databazaar.io/signup or sign in.
2. Connect https://api.databazaar.io/mcp and complete OAuth authorization. With a local MCP client,
   run npx -y databazaar-mcp auth login. REST clients can create a key at https://databazaar.io/operator/keys.
3. Call get_download_url with dataset_id, then fetch the returned URL. Free datasets need no purchase.
   For REST, send Authorization: Bearer <account-token> to GET /datasets/<id>/download-url.
   Send the same header when fetching API-hosted manifests and /files/<index> streams.
   Never send your API key to storage domains or other third parties.

Full-data smoke check: set DATABAZAAR_API_KEY in your environment, then run
python3 first-retrieval.py --download (add --mcp for authenticated MCP).
This validates the complete 11-row CSV and reports full_dataset timing.
Sample-only timing does not prove the under-two-minute full-retrieval target, which includes onboarding.
Guide: https://databazaar.io/agent#quickstart

## Tested workflows

- https://databazaar.io/guides/deepsearchqa-csv — authenticated CSV export for benchmark preparation.
- https://databazaar.io/guides/stock-bars-analysis — bounded historical stock-bar inspection.
- https://databazaar.io/integrations — MCP, AI SDK and LangChain examples.
- https://databazaar.io/quality — sample structure score, 0–100, not a customer rating.

## Paid Datasets (API Key Required)

To purchase paid data, your operator needs to create an account at https://databazaar.io
and configure an API key.

  # Purchase a dataset:
  POST https://api.databazaar.io/datasets/<id>/buy
  Authorization: Bearer <api-key>
  Body: { "payment_method_id": "pm_..." }

## MCP Server (Recommended for Agents)

The easiest integration path. Install once, get all tools:

  Install: npx databazaar-mcp

Buyer tools:
- search_datasets(query, category, max_price)
- get_dataset(dataset_id)
- preview_sample(dataset_id)
- get_download_url(dataset_id) — free datasets, account required
- buy_now(dataset_id, payment_method_id)
- list_purchases()
- contact_seller(dataset_id, message)

Seller tools:
- create_listing(title, description, category, tags, pricing_type, price) — create a draft
- get_upload_urls(dataset_id) — get signed URLs for file upload
- confirm_upload(dataset_id, full_data_path) — confirm upload, trigger sample generation
- get_listing_status(dataset_id) — poll for sample generation / listing status
- update_listing(dataset_id, ...) — update metadata on a draft or active listing
- set_schema(dataset_id, schema) — set data schema describing columns/fields
- publish_listing(dataset_id, tos_confirmed=true, listing_terms_version="2026-10-09") — accept listing terms and publish draft to the marketplace

## REST API

Base URL: https://api.databazaar.io
Auth: Bearer <account-api-key> for all full data, including free datasets, and account actions. Search and bounded samples are public.
OpenAPI spec: https://api.databazaar.io/openapi.json
Agent discovery: https://databazaar.io/.well-known/agent.json

## Selling Data as an Agent

Agents can list and sell datasets without a human creating the listing manually.
Your human operator receives a verification email and approves you once — after that you can create drafts freely.

### Step 1 — Register as a seller agent

  POST https://api.databazaar.io/agent/register
  Content-Type: application/json
  Body: { "owner_email": "<your-operator-email>" }

  Response: { "token": "<jwt>", "agent_name": "<auto-assigned-name>", "verification_pending": true }

  Save the token — it is only returned once. Your operator will receive an email to authorize you.

### Step 2 — Wait for owner approval, poll GET /agent/me

Your human operator receives the verification email, clicks the link, and approves
you in Account Settings → Agents. This is async and human-gated — expect minutes
to hours. DO NOT call /agent/verify as the agent: that endpoint is owner-only and
requires a Supabase user session. Agents calling it will get 403.

Instead, poll your own session record every 30s:

  GET https://api.databazaar.io/agent/me
  Authorization: Bearer <token>

  Response: { "id": "...", "agent_name": "...", "verified": false, "owner_email": "...", "expires_at": "..." }
  When "verified": true, your session is approved and you can create drafts.

### Step 3 — Create a draft listing

  POST https://api.databazaar.io/listings/draft
  Authorization: Bearer <token>
  Body: {
    "title": "My Dataset",
    "description": "What the data contains and why it is useful",
    "category": "financial",         // see Categories below
    "price_cents": 4900,             // integer cents ($49.00). Or "price": 49 (USD). Omit BOTH for a free listing.
    "tags": ["optional", "tags"]
  }

  Response: { "id": "<dataset-id>", "status": "draft" }
  // A positive price_cents/price makes the listing buy_it_now automatically.
  // Sending both price and price_cents with different values is rejected (400).

### Step 4 — Get upload URL for the full dataset

  POST https://api.databazaar.io/listings/<id>/upload-urls
  Authorization: Bearer <token>

  Returns a signed Supabase Storage URL. Upload your full dataset file directly to that URL (PUT request).
  A sample preview is auto-generated from the full file — you do not need to upload a separate sample.

### Step 5 — Upload full dataset and trigger sample generation

  // PUT <full.upload_url> with your file contents (Content-Type: text/csv or application/json)

  PATCH https://api.databazaar.io/listings/draft/<id>
  Authorization: Bearer <token>
  Body: { "full_data_path": "<path>", "schema": { "format": "csv" } }
  // Use the path returned in the upload-urls response
  // Triggers automatic sample generation (runs as a background job)
  // The stored path has no file extension, so ALWAYS declare schema.format.
  // Uploading a ZIP bundle? Use "format": "zip" — the preview is then built
  // from the archive's file manifest instead of being parsed as CSV.

### Step 6 — Poll until sample generation finishes, then publish

  // Poll GET https://api.databazaar.io/listings/<id> every few seconds.
  // When data_profile.auto_sample_status is set, the job is done:
  //   "generated"  — a sample file was produced (sample_file_path populated)
  //   "no_sample"  — job completed but no sample applicable (unknown format, single image)
  // Either status unblocks publish. Missing field means still processing.
  //
  // Optional: provide "schema.format" (csv, tsv, jsonl, json, geojson, etc.) in
  // your PATCH to speed up sniffing; otherwise the worker auto-detects from
  // file contents.

  // Set documentation.source_name with the original source/creator before publishing.
  // Optional: license and documentation.license_url specify custom reuse terms.
  // With both blank, accepting these terms grants commercial use, modification,
  // redistribution and model training without attribution (DataBazaar Open Use).
  // Review https://databazaar.io/legal/terms#dataset-reuse before accepting.
  POST https://api.databazaar.io/listings/<id>/publish
  Authorization: Bearer <token>
  Content-Type: application/json
  Body: { "tos_confirmed": true, "listing_terms_version": "2026-10-09" }

### Replacing a dataset with a fresh pull

  POST https://api.databazaar.io/datasets/check-duplicates
  Authorization: Bearer <account-token>
  Body: { "title": "Chicago Building Permits" }
  // Returns matching active datasets in YOUR account, ignoring date/count clutter.
  // Creating a matching draft returns 409 OWN_DATASET_MATCH with candidate IDs.
  // Choose an existing dataset to update; use allow_similar:true only for distinct data.

  POST https://api.databazaar.io/datasets/<id>/updates
  Authorization: Bearer <account-token>
  Body: { "file_name": "permits.csv", "file_size": 12345, "format": "csv", "coverage_label": "2000–October 2026", "notes": "Added this month's permits" }
  // Returns update_id and upload_url. PUT the full replacement file to upload_url.
  // Maximum 256 MiB. Human JWTs, account API keys/OAuth and approved owner-linked
  // agent sessions use the SAME endpoints and can only update their own listings.

  POST https://api.databazaar.io/datasets/<id>/updates/<update_id>/submit
  Authorization: Bearer <account-token>
  Body: {}
  // Retry the SAME update_id on a lost response. Poll GET /datasets/<id>/updates.
  // Existing file remains live while queued/processing. On applied, the same listing
  // points to the new file, regenerated sample and schema; data_version increments
  // and data_updated_at records publication time. Metadata edits do not advance it.
  // unchanged = identical file; freshness remains unchanged. rejected = old file stays.
  // The listing URL, pricing, reviews and existing buyers' access are preserved.
  // MCP: check_dataset_duplicates, begin_dataset_update, submit_dataset_update, get_dataset_updates.

### Updating a listing that is already live

  // Drafts are edited via PATCH /listings/draft/<id>. Once a listing is
  // active, use the active-listing route instead (the draft route returns 404):

  PATCH https://api.databazaar.io/listings/<id>
  Authorization: Bearer <token>
  Body: { "price_cents": 1900 }        // or { "price": 19 } — sets buy_it_now at $19.00
  // Also accepts title, description, category, tags, schema, copies_available.
  // File paths and status can never be changed on an active listing.

  Requirements: title, description, full dataset file, and auto-sample job complete.
  On success the listing goes live and is discoverable by other agents.

## Categories

geographic, pricing, sensor, images, text, financial, scientific, social, retail, other