Scravity API — Full Tutorial

Scravity is a scraping and automation API that turns any URL into clean Markdown, raw HTML, or structured JSON — with proxy rotation and stealth bot-evasion built in. This guide walks through every endpoint, one working example at a time.

⚠ Heads up: Scravity is under heavy active development. Endpoints, parameters, and response shapes may change without notice — check back here before shipping to production.

New here? Grab an API key from /api-key before you start — every endpoint except the free scraper requires it.

1. Getting Started

The base URL for every request is your Scravity host root. Requests and responses are JSON by default, though scraper endpoints can also return raw HTML or Markdown directly depending on the output parameter you choose.

curl -X POST "https://scravity.com/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "engine": "http",
    "output": "markdown"
  }'

That single call fetches example.com, renders it with the fast http engine, and returns the page as clean Markdown. The rest of this guide breaks down every option available to you.

2. Authentication

All authenticated endpoints use standard HTTP Bearer authentication. Pass your API key in the Authorization header on every request:

Authorization: Bearer YOUR_API_KEY

If the key is missing, malformed, or invalid, the API responds with 401 Unauthorized and an API_KEY_ERROR error code (see the Error Codes section below). Manage and rotate your key any time from /api-key.

3. Check Your Credit Balance

Returns your account's current available credit balance. Useful for showing usage in a dashboard or guarding against failed requests before they happen.

curl "https://scravity.com/credits" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

resp = requests.get(
    "https://scravity.com/credits",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(resp.json())

const resp = await fetch("https://scravity.com/credits", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
console.log(await resp.json());

Requires authentication. Returns 401 if the key is invalid or missing.

4. Full Feature Scraper

The main scraping endpoint. Supports managed proxies, stealth bot evasion, configurable wait times, and multiple output formats. Available as both POST (JSON body — better for complex requests) and GET (query params — better for quick tests and browser use).

Rendering Engines

Choose the engine based on how much the target site relies on JavaScript and bot protection:

Engine	Description	Best for
http	Very fast, no JS rendering. Emulates real browser TLS fingerprints.	Static pages, APIs disguised as HTML, high-volume crawls
jslite	Small, fast rendering engine with JS support, but not very stealthy.	JS-rendered pages with minimal bot protection
stealth	Full feature stealthy browser to evade advanced bot protection.	Sites behind Cloudflare, Akamai, DataDome, etc.

Request Parameters

Parameter	Type	Default	Description
url	string	required	Target URL to scrape (1–2083 characters).
engine	enum	http	One of http, jslite, stealth.
wait	integer	0	Wait 0–30 extra seconds after page load before extracting content. Only applies to jslite and stealth; ignored on http.
proxy	enum / null	datacenter	residential, datacenter, or null to disable proxying.
output	enum	markdown	markdown for cleaned Markdown, or html for raw HTML.
simple_response	boolean	true	When true, returns just the scraped content. When false, wraps it in a JSON envelope with cost, headers, cookies, and other metadata.

Example: POST request

curl -X POST "https://scravity.com/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/123",
    "engine": "stealth",
    "wait": 5,
    "proxy": "residential",
    "output": "markdown",
    "simple_response": false
  }'

import requests

resp = requests.post(
    "https://scravity.com/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "url": "https://example.com/product/123",
        "engine": "stealth",
        "wait": 5,
        "proxy": "residential",
        "output": "markdown",
        "simple_response": False,
    },
)
data = resp.json()
print(data["content"])

Example: GET request (quick test)

curl "https://scravity.com/?url=https://example.com&engine=http&output=markdown" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response (simple_response = true)

# Scraped!

This is the markdown content.

Example response (simple_response = false)

{
  "success": true,
  "cost": 3,
  "content": "# Scraped!\n\nThis is the markdown content."
}

5. Free Scraper

A no-cost endpoint for basic scraping. Limited to the http and jslite engines — no stealth engine, no managed proxies, no screenshots. Bring your own proxy if you need one.

Request Parameters

Parameter	Type	Default	Description
url	string	required	Target URL to scrape.
engine	enum	http	http or jslite only.
wait	integer	0	Wait 0–15 extra seconds after page load. Only supported with jslite; ignored on http.
output	enum	markdown	markdown, html, or rendered (HTML generated from the extracted Markdown).
proxy	string / null	none	Optional bring-your-own proxy. Accepts host:port, user:pass@host:port, or a full URL with http, https, socks4, socks5, or socks5h scheme.

Example

curl "https://scravity.com/free?url=https://example.com&engine=jslite&wait=3&output=markdown"

const params = new URLSearchParams({
  url: "https://example.com",
  engine: "jslite",
  output: "html",
  proxy: "socks5://user:pass@myproxy.example:1080",
});

const resp = await fetch(`https://scravity.com/free?${params}`);
const html = await resp.text();
console.log(html);

No Authorization header required — this endpoint is open by design.

6. Response Formats

The two scraper endpoints handle responses differently — the full feature scraper can switch between a raw body and a JSON envelope, while the free scraper always returns the content directly.

Full Feature Scraper (/)

Controlled by simple_response:

• Raw content — with simple_response: true (default), the response body is the scraped content: plain Markdown or HTML, served with a matching Content-Type.
• JSON envelope — with simple_response: false, you get a JSON object containing content, cost, and a success flag, plus any extra metadata like headers and cookies.

Free Scraper (/free)

The free scraper has no simple_response option — it always returns the content directly, with the shape controlled entirely by output:

• markdown — cleaned Markdown text.
• html — the raw HTML as fetched from the target page.
• rendered — a simplified HTML page built from the extracted Markdown, handy for quickly eyeballing the scraped content in a browser while testing.

7. Error Codes

Every error follows the same shape, making it easy to handle failures with one piece of logic across all endpoints:

{
  "success": false,
  "message": "Human-readable error message.",
  "error_code": "INSUFFICIENT_CREDITS",
  "details": null
}

Status	error_code	Meaning
401	API_KEY_ERROR	The provided API key is invalid or missing.
402	INSUFFICIENT_CREDITS	Your account doesn't have enough credits for this request.
404	NO_DATA_FOUND	The requested page or matching data could not be found.
422	VALIDATION_ERROR	One or more request parameters are invalid or missing.
422	PARSING_FAILED	The target content could not be parsed or extracted.
500	UNKNOWN_SCRAPING_FAILURE	An unexpected scraping error occurred.
500	INTERNAL_SERVER_ERROR	An unexpected internal server error occurred.
502	TARGET_SERVER_ERROR	The target website returned an HTTP error (typically 5xx).
502	CONNECTION_ERROR	Failed to establish a connection to the target website.
502	PROXY_ERROR	The configured proxy failed while processing the request.
503	RESOURCE_UNAVAILABLE	The requested resource is temporarily unavailable or offline.
504	TIMEOUT_ERROR	The scraping request exceeded the configured timeout.

Only successful requests are billed — a failed scrape (any non-200 response) never consumes credits.

8. Billing & Credits

Credit usage on the full feature scraper scales dynamically with the features you request — a plain http scrape costs less than a stealth render with a residential proxy and a long wait. Check your balance anytime with GET /credits, and inspect the cost field on any response with simple_response: false to see exactly what a call charged.

The /free endpoint never consumes credits — it's rate-limited instead, and works without an API key.

9. FAQ

Which engine should I start with?

Start with http. It's the fastest and cheapest option, and it's often enough — try upgrading to jslite or stealth only if the response looks empty or you're getting blocked.

Can I get a screenshot instead of text?

Not yet — screenshots aren't available at the moment. Support for screenshots on the stealth engine is coming soon.

Do I need a proxy for the free endpoint?

No — proxy is optional on /free. Add your own if the target site blocks the shared IP pool, using any of the supported proxy URL formats.

10. Resources & Support

• Interactive documentation — try every endpoint live at api.scravity.com/docs.
• More tutorials — browse the /blog for deeper dives and use cases.
• Support — stuck on something? Email support@scravity.com.