SetSwap API Reference

Base URL: https://setswap.polsia.app · All payloads: application/json

POST/v1/datasets/search

Query the dataset catalog. Returns ranked results by quality score. No charge for searching.

Request Body (all fields optional)

Field	Type	Description
domain	string	`finance` \| `nlp` \| `computer_vision`
format	string	`csv` \| `jsonl` \| `parquet` \| `images`
min_quality	float	Minimum quality score 0.0–1.0
query	string	Free-text search against name, description, tags
limit	int	Max results (default 20, max 100)
offset	int	Pagination offset

Example

curl -X POST https://setswap.polsia.app/v1/datasets/search \
  -H "Content-Type: application/json" \
  -d '{"domain":"finance","min_quality":0.9,"query":"sentiment"}'

// 200 OK
{
  "datasets": [{
    "id": 1, "slug": "fin-sentiment-sp500-q1-2026",
    "quality_score": 0.94, "price_usd": "12.40",
    "domain": "finance", "format": "jsonl", "row_count": 50000
  }],
  "total": 1, "limit": 20, "offset": 0
}

GET/v1/datasets/:id/preview

Inspect schema, sample rows, and bias metrics before purchasing. Free.

Path Params

Field	Type	Description
id	integer	Dataset ID from search

Example

curl https://setswap.polsia.app/v1/datasets/1/preview

// 200 OK
{
  "id": 1, "quality_score": 0.94, "price_usd": "12.40",
  "schema": [{"name":"sentiment","type":"enum","description":"bull|bear|neutral"}],
  "sample_rows": [{"company_ticker":"AAPL","sentiment":"bull","confidence":0.97}],
  "bias_metrics": {"sector_distribution":"balanced","annotation_agreement":0.91},
  "purchase_count": 47
}

POST/v1/purchase

Purchase a one-time micro-license. Returns a license_token and download_url valid for 24 hours.

Request Body

Field	Type	Description
dataset_id	integer	ID of dataset to purchase
buyer_emailoptional*	string	Buyer email address
buyer_agent_idoptional*	string	Machine buyer identifier
stripe_session_idoptional	string	Stripe checkout session for payment verification

* One of buyer_email or buyer_agent_id required.

Example

curl -X POST https://setswap.polsia.app/v1/purchase \
  -H "Content-Type: application/json" \
  -d '{"dataset_id":1,"buyer_agent_id":"agent_abc123","stripe_session_id":"cs_live_..."}'

// 201 Created
{
  "license_token": "ss_4f2a8b...",
  "download_url": "https://datasets.setswap.io/fin-sentiment-sp500-q1-2026.jsonl.gz",
  "expires_at": "2026-05-11T02:06:00Z",
  "amount_paid_usd": "12.40",
  "dataset": {"id":1,"slug":"fin-sentiment-sp500-q1-2026","domain":"finance"}
}