POST /v1/parse

File → markdown (Firecrawl /parse parity). Accepts either a multipart file upload or a JSON { url } pointing at a document, and returns markdown + extracted text.

Supports PDF (always) and DOCX (when the optional mammoth dependency is installed on the server, returns 415 otherwise).

Request, multipart upload

curl -X POST https://api.superscraper.dev/v1/parse \
  -H "x-api-key: ss_live_xxxxxxxxxxxxxxxxxxxx" \
  -F "file=@invoice.pdf"

Request, JSON body (fetch a URL)

POST /v1/parse
Content-Type: application/json
x-api-key: YOUR_KEY

Field	Type	Required	Description
`url`	string	Yes (JSON path only)	URL of a PDF or DOCX document to fetch and parse.

curl -X POST https://api.superscraper.dev/v1/parse \
  -H "x-api-key: ss_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/contracts/license-2026.pdf"}'

Response

HTTP 200 on success.

Field	Type	Description
`ok`	boolean	`true` on success
`markdown`	string	Document content converted to markdown
`text`	string	Plain-text extraction
`format`	`"pdf"` \| `"docx"`	Detected document format
`pages`	number \| undefined	Page count (PDF only)

Example response

{
  "ok": true,
  "markdown": "# Contractor License Agreement\n\n...",
  "text": "Contractor License Agreement\n\n...",
  "format": "pdf",
  "pages": 4
}

Errors

Status	Error	Cause
400	`file` field is required (multipart upload)	Multipart request with no `file` part
400	`Invalid multipart form data`	Malformed multipart body
400	`url` is required	JSON path with no `url` field
400	`Invalid URL`	`url` isn't a valid URL
400	`Blocked URL: ...`	URL rejected by the SSRF guard (DOCX-by-URL path)
415	`DOCX parsing not available`	Server doesn't have the optional `mammoth` dependency installed
422	`Could not extract text from file` / `document`	The file couldn't be parsed (corrupt, unsupported, or scanned image with no OCR match)
422	`Fetch failed: HTTP <status>`	URL fetch (DOCX path) returned a non-2xx status

Notes

PDF extraction uses the engine's pdfjs → Claude Vision fallback (same cascade as /v1/scrape on a .pdf URL).
With SCRAPER_MOCK_MODE=true, both paths return a small fixed sample document, useful for integration testing without burning credits.
This endpoint is not part of the mandated Core group (Scrape/Extract/Search/Crawl/Map/Batch) but is a real, working endpoint, file conversion, not web scraping.

GET /v1/jobs Pre-built scrapers