{"openapi":"3.1.0","info":{"title":"webatla API","version":"v1","description":"Public-facing API. Authenticate with a Bearer token from `/account/api`. Automated security testing is not authorized without prior written permission, see `/.well-known/security.txt`.","contact":{"email":"support@webatla.com"}},"servers":[{"url":"https://webatla.com/api/v1","description":"Production"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"wbtl_…","description":"Issued from `/account/api`. Send as `Authorization: Bearer wbtl_…`."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"User":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"role":{"type":"string","description":"Account role, `customer` for API users."}},"required":["id","email","role"]},"Dataset":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"category":{"type":"string"},"rowCount":{"type":"integer","nullable":true},"priceCents":{"type":"integer"},"currency":{"type":"string","example":"EUR"},"updatedAt":{"type":"string","format":"date-time"},"pageUrl":{"type":"string","format":"uri","description":"The dataset's page: what the file contains, a live sample and the price.","example":"https://webatla.com/datasets/dns"},"checkoutUrl":{"type":"string","format":"uri","description":"Where a person buys one month of access to this dataset. Opens without an account; paying needs one, which the page offers to create.","example":"https://webatla.com/account/checkout?dataset=dns"}},"required":["slug","name","category","priceCents","currency","updatedAt","pageUrl","checkoutUrl"]},"Order":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"datasetSlug":{"type":"string"},"datasetName":{"type":"string"},"status":{"type":"string","enum":["pending","paid","failed","refunded"]},"amountCents":{"type":"integer"},"currency":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"paidAt":{"type":"string","format":"date-time","nullable":true},"accessExpiresAt":{"type":"string","format":"date-time","nullable":true}}},"Download":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"datasetSlug":{"type":"string"},"datasetName":{"type":"string"},"downloadedAt":{"type":"string","format":"date-time"},"fileSizeBytes":{"type":"integer","nullable":true},"fileKey":{"type":"string"}}}}},"security":[{"bearerAuth":[]}],"paths":{"/me":{"get":{"summary":"Current API key's user","responses":{"200":{"description":"Identified","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/User"},"apiKeyId":{"type":"string","format":"uuid"},"scopes":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"Invalid or missing API key, or the key has an IP whitelist that does not include your address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (200/min per key)"}}}},"/datasets":{"get":{"summary":"List published datasets","security":[],"description":"Public endpoint — no auth required. IP-based rate limit: 60/min.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"datasets":{"type":"array","items":{"$ref":"#/components/schemas/Dataset"}}}}}}},"429":{"description":"Rate limit exceeded (60/min per IP)"}}}},"/me/orders":{"get":{"summary":"List your orders","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}}}}}},"401":{"description":"Invalid or missing API key, or the key has an IP whitelist that does not include your address"}}}},"/me/downloads":{"get":{"summary":"List your download history","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"downloads":{"type":"array","items":{"$ref":"#/components/schemas/Download"}}}}}}},"401":{"description":"Invalid or missing API key, or the key has an IP whitelist that does not include your address"}}}},"/download/{slug}":{"servers":[{"url":"https://webatla.com/api"}],"get":{"summary":"Download a purchased dataset (full export)","description":"Streams the full `.jsonl.zst` export (JSON Lines, zstd). Requires paid, unexpired access to the dataset. Single-range `Range` requests are supported for resume; multipart ranges are rejected with 416. Rate limit: 240/min per user.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"all-data"}],"responses":{"200":{"description":"File stream (`application/zstd`, `Content-Disposition: attachment`)"},"206":{"description":"Partial content (resume via `Range: bytes=N-`)"},"302":{"description":"Browser session missing → redirect to login (API keys get 401 instead)"},"401":{"description":"Invalid or missing API key, or the key has an IP whitelist that does not include your address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No active paid access to this dataset"},"404":{"description":"Unknown dataset or file not uploaded yet"},"416":{"description":"Malformed or multipart Range"},"429":{"description":"Rate limit exceeded (240/min per user)"}}}},"/download/{slug}/{scope}/{key}":{"servers":[{"url":"https://webatla.com/api"}],"get":{"summary":"Download a per-scope slice of a purchased dataset","description":"One file per TLD / TLD suffix / country / technology. Exactly ONE dimension per request (filters cannot be combined, so intersect locally, e.g. WordPress sites hosted in Germany: `zstdcat wordpress.jsonl.zst | jq -c 'select(.[\"Country by IP\"] == \"DE\")'`). A dataset only has slices for the scopes it participates in (see its `scope_kinds`). Same auth, Range and rate-limit semantics as the full download.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"technologies"},{"name":"scope","in":"path","required":true,"schema":{"type":"string","enum":["tld","tld_suffix","country","technology"]}},{"name":"key","in":"path","required":true,"schema":{"type":"string"},"description":"TLD slug (`com`), suffix with dots (`com.ua`), ISO 3166-1 alpha-2 country (`DE`), or technology slug (`wordpress`).","example":"wordpress"}],"responses":{"200":{"description":"File stream (`application/zstd`, `Content-Disposition: attachment`)"},"206":{"description":"Partial content (resume via `Range: bytes=N-`)"},"302":{"description":"Browser session missing → redirect to login (API keys get 401 instead)"},"401":{"description":"Invalid or missing API key, or the key has an IP whitelist that does not include your address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No active paid access to this dataset"},"404":{"description":"Unknown dataset/entity, dataset has no slices for this scope, or slice not uploaded yet"},"416":{"description":"Malformed or multipart Range"},"429":{"description":"Rate limit exceeded (240/min per user)"}}}},"/preview":{"get":{"summary":"Free 10,000-row sample of one dataset","description":"The first 10,000 rows of a dataset's export, as JSONL with the paid file's field names. Needs an account: a signed-in browser session (a free account is enough) or any valid Bearer key (keys come with a purchase). The sample itself needs no purchase or scope.","parameters":[{"name":"dataset","in":"query","required":true,"schema":{"type":"string"},"description":"Dataset slug, see `GET /datasets`.","example":"dns"}],"responses":{"200":{"description":"JSONL file (`Content-Disposition: attachment; filename=webatla-{slug}-preview-10k.jsonl`)"},"401":{"description":"No account: anonymous requests get a sign-up hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown dataset, or no preview file yet"},"429":{"description":"Rate limit exceeded (30/min per IP, shared with /sample)"}}}},"/sample/{scope}/{key}":{"get":{"summary":"Free sample: up to 20 rows for one TLD, suffix, country or technology","description":"Real rows for one entity, projected onto the chosen dataset's columns, as JSONL. When the entity has no rows of its own yet, the dataset's 10,000-row preview is returned instead. Needs an account: a signed-in browser session (a free account is enough) or any valid Bearer key (keys come with a purchase).","parameters":[{"name":"scope","in":"path","required":true,"schema":{"type":"string","enum":["tld","tld_suffix","country","technology"]}},{"name":"key","in":"path","required":true,"schema":{"type":"string"},"description":"TLD slug (`com`), suffix with dots (`co.uk`), ISO 3166-1 alpha-2 country (`DE`), or technology slug (`wordpress`).","example":"wordpress"},{"name":"dataset","in":"query","required":false,"schema":{"type":"string","default":"all-data"},"description":"Dataset slug whose columns to use."}],"responses":{"200":{"description":"JSONL file (`webatla-{dataset}-{scope}-{key}-preview.jsonl`)"},"400":{"description":"Unknown scope, or malformed key or dataset slug"},"401":{"description":"No account: anonymous requests get a sign-up hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown dataset, or nothing to sample yet"},"429":{"description":"Rate limit exceeded (30/min per IP, shared with /preview)"}}}},"/health":{"servers":[{"url":"https://webatla.com/api"}],"get":{"summary":"Service health","security":[],"description":"Service status as JSON: `status` (ok, degraded or down) and `timestamp`. Public.","responses":{"200":{"description":"`status` ok, or degraded when an optional component fails"},"503":{"description":"`status` down: a required component fails"}}}}}}