API reference

GET /api/extract

Extract one public URL as normalized JSON or raw Markdown. Only GET requests are supported.

To discover URLs from a query first, use GET /api/search. Dedicated GET endpoints cover news, images, places, and stock search plus market data.

Authentication and credits

Authentication is optional. Anonymous successful uncached operations use the free allowance of 10 per IP each UTC day. New accounts receive a one-time 1,000-credit welcome bonus. Signed-in requests from the homepage and platform playgrounds automatically use the account balance, while external integrations use the same balance with Authorization: Bearer ext_live_…. Identical cache hits are always free.

Authorization: Bearer ext_live_your_key

Create and revoke up to two active keys in the private dashboard. Full keys are stored only as hashes and shown once.

Query parameters

Parameter	Required	Description
`url`	Yes	An absolute public HTTP or HTTPS URL, up to 2,048 characters.
`format`	No	`json` (default) or `markdown`.
`focus`	No	A 1–80 character topic for a relevant section of a generic webpage. Structured platform entities may ignore it.

JSON response

{
  "schemaVersion": 1,
  "type": "article",
  "source": "web",
  "id": null,
  "url": "https://example.com/article",
  "title": "Example article",
  "author": null,
  "publishedAt": null,
  "content": "# Example article\n\n...",
  "media": [],
  "attributes": {}
}

schemaVersion is currently 1.
type is document, article, product, post, profile, video, audio, or feed.
source identifies the recognized platform or provider-neutral capability, including web, web-search, image-search, place-search, finance, and supported URL platforms.
content is always Markdown, even inside a JSON response.
items is present for feed and profile results and omitted for individual entities.

Markdown response

With format=markdown, the body is raw Markdown and the response uses Content-Type: text/markdown; charset=utf-8.

Errors

{
  "error": {
    "code": "invalid_url",
    "message": "Enter a complete, valid URL."
  }
}

Status	Meaning
`400`	Missing, invalid, or unsupported input.
`401`	The Bearer API key is invalid or revoked.
`402`	The account has insufficient credits.
`404`	The public source was not found or is unavailable.
`413`	The source or extracted result is too large.
`415`	The source is not an HTML, Markdown, or plain-text page.
`422`	The page was reachable but useful content could not be extracted.
`429`	The daily anonymous allowance or a per-client rate limit was exceeded. Anonymous allowance errors prompt the caller to create an account.
`500`	The extracted data could not be represented by the public response schema.
`502`	The public source blocked access, rate-limited the request, or returned an upstream error. The error message includes the source status when available.
`504`	The source did not respond or finish loading before the timeout.

Metering headers

Responses expose X-Extractor-Cache: HIT|MISS. An uncached response using either free tier exposes X-Extractor-Free-Remaining for that tier. Once an account uses prepaid balance, responses expose X-Extractor-Credits-Used and X-Extractor-Credits-Remaining. Metering headers are never stored in shared cache entries.

Machine-readable contract

Use the JSON Schema for the versioned entity contract and the OpenAPI 3.1 document for the complete endpoint definition. The schema guide explains price units, null values, media, attributes, and nested items.