MarkUDown

Smart Extract API — MarkUDown AI web extraction API docs

POST/api/smart-extract

Smart Extract

Three-phase guided extraction: analyze the site difficulty, plan the required interactions with an LLM, then execute navigation and extraction automatically. Returns Markdown or structured JSON.

ParameterTypeRequiredDefaultDescription
urlstringrequired—URL of the page or site to extract.
goalstringrequired—Plain-language description of what to extract.
hintsarray<string>optional[]Optional interaction hints (e.g. "click the Load More button").
schemaobjectoptionalnullField definitions for structured output, e.g. {"title": "string", "price": "number"}. Needed for json_data.
output_formatstringoptional"markdown""markdown" or "json". With "json" and a schema, the records are also returned in json_data.
max_pagesintegeroptional20Maximum pages to traverse during extraction.
timeoutintegeroptional60Per-page timeout in seconds.
callback_urlstringoptionalnullWebhook URL to POST the result to when the job completes.

Request

{
  "url": "https://books.toscrape.com",
  "goal": "Extract all books with title, price and rating",
  "output_format": "json",
  "schema": {
    "title": "string",
    "price": "string",
    "rating": "string"
  },
  "max_pages": 10
}

Response

{
  "success": true,
  "id": "job_abc123",
  "url": "/api/smart-extract/job_abc123"
}

// Poll GET /api/smart-extract/{id}
{
  "success": true,
  "id": "job_abc123",
  "status": "completed",
  "data": {
    "success": true,
    "data": {
      "url": "https://books.toscrape.com",
      "markdown": "# Books\n\n...",
      "json_data": [
        { "title": "A Light in the Attic", "price": "£51.77", "rating": "Three" }
      ],
      "metadata": {
        "layer_used": "playwright",
        "pages_traversed": 4,
        "records_extracted": 80,
        "difficulty": "medium",
        "actions_executed": 3,
        "planner_reasoning": "...",
        "duration_ms": 38200
      }
    },
    "processing_time_ms": 38400
  }
}