API Overview

Essence exposes five REST endpoints under /api/v1/. All endpoints accept JSON POST requests and return JSON responses.

Base URL

http://localhost:8080

Authentication

None required. Essence is self-hosted with no API keys.

Common Parameters

These parameters are shared across the scrape, crawl, and map endpoints:

Parameter	Type	Default	Description
`url`	string	—	Required. The URL to process
`formats`	string[]	`["markdown"]`	Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`
`engine`	string	`"auto"`	Engine selection: `"auto"`, `"http"`, or `"browser"`
`timeout`	integer	`30000`	Request timeout in milliseconds
`headers`	object	`{}`	Custom HTTP headers to send

Response Structure

All endpoints return a consistent response shape:

{
  "success": true,
  "data": {
    "title": "Page Title",
    "description": "...",
    "url": "https://example.com",
    "markdown": "# Page Title\n\nContent...",
    "metadata": {
      "title": "Page Title",
      "description": "...",
      "url": "https://example.com",
      "statusCode": 200,
      "contentType": "text/html",
      "wordCount": 1234,
      "readingTime": 5
    }
  }
}

Metadata is always included regardless of the formats parameter. Other fields (markdown, html, rawHtml, links, images, screenshot) appear only when requested.

Error Responses

{
  "success": false,
  "error": "Description of what went wrong"
}

Health Check

GET /health → "ok"