Databases and Sinks

Database routes are feature-gated. If datasets are unavailable, they return 503 { "error": "datasets are not configured" }.

Create and list

curl -X POST https://api.parseium.com/v1/databases \
  -H "X-API-Key: your_key" -H "Content-Type: application/json" \
  -d '{"name":"prices"}'

Names match [a-z0-9-]{1,32}. A duplicate returns 409; count, storage, or create-contention limits return 429. GET /v1/databases includes table counts, size hints, read-only state, and quota totals.

Delete is destructive and requires explicit confirmation:

DELETE /v1/databases/prices?confirm=prices

Use a sink

Batches, sync POST scrape, and cron/workflow stages accept:

{
  "mode": "database",
  "database": "prices",
  "table": "products",
  "key": ["sku"]
}

Tables match [a-z0-9_]{1,48} and are created on first write. List-mode parser items become rows; flat parsers produce one row. Nested/array values are stored as JSON text. Every table receives _url, _scraped_at, _run_id, and _job_id metadata.

key controls upserts and defaults to _url for parser jobs. Repeated jobs update matching rows, making sinks suitable for scheduled feeds.

Query

POST /v1/databases/{name}/query costs 1 credit:

{
  "sql": "select title, price from products where price < ? limit 20",
  "args": [20]
}

One statement is allowed. Execution is capped at 10 seconds and the response at 500 rows / 256 KB. truncated: true means you should narrow the query or add a limit.

Dump

GET /v1/databases/{name}/dump?table=products&format=ndjson streams an NDJSON or CSV attachment and costs 5 credits. Dumps are bulk HTTP operations and are intentionally unavailable through MCP.