Perceive

POST /v2/perceive renders a URL once in a real browser and hands back every output you ask for from that single render: Markdown, cleaned or raw HTML, a screenshot, a PDF, the link and image inventory, and structured data (page metadata, JSON-LD, headings, tables). It replaces a stack of separate calls — url-to-markdown, url-to-screenshot, url-to-pdf, plus your own scraping — with one request.

Here is the smallest useful call. Send a URL, get clean Markdown and the page's structured metadata back:

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "outputs": ["markdown", "structured"]
  }'

The response carries a pre-signed download URL for the Markdown file and the structured block inline:

{
    "operation_id": "per_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7",
    "status": "completed",
    "url": "https://example.com/pricing",
    "url_final": "https://example.com/pricing",
    "content_hash": "9f2b8c1a...d4e5",
    "render_quality": 0.93,
    "cache_hit": false,
    "outputs": {
        "markdown": {
            "url": "https://spaces.example.com/...signed...",
            "object_key": "env/files/4127/v2-perceive/per_3f9a..._markdown.md",
            "size_bytes": 8421,
            "content_type": "text/markdown; charset=utf-8",
            "expires_in": 900
        }
    },
    "structured": {
        "metadata": {
            "title": "Pricing",
            "description": "Simple, usage-based pricing."
        },
        "structured_data": [
            {"@type": "Product", "name": "Pro", "offers": {"price": "99"}}
        ]
    },
    "extraction_tier": "heuristic",
    "tokens": {"input": 0, "output": 0},
    "cost_cents": 0.0,
    "duration_ms": 6230,
    "warnings": []
}

Worth flagging up front. /v2/perceive is a V2 endpoint with its own quota counter. V1 conversion plans do not include any V2 perceive operations — you need a V2-inclusive plan to call it. See the pricing page for the per-tier allowances.

Endpoints

Content-Type: application/json on every POST.

Authentication

Authenticate with a private key in the X-API-Key header for server-to-server calls. This is the path the examples below use.

X-API-Key: sk_live_your_private_key

Public keys with a JWT bearer token also work, using the same flow as every other endpoint — generate a token with your pk_ key, then send it as Authorization: Bearer <token>. The full flow, including domain locking and token refresh, is in the authentication guide.

Each API key carries an allowed-endpoints allowlist. If /v2/perceive is not on the key's list, the request is rejected with 403.

How perceive works

One request triggers one browser render through a shared headless Chrome singleton, then materialises every output from that render. You never pay for the same page twice in a single call.

1. Render. The page loads in headless Chrome. Cookie banners are dismissed, the page is scrolled to trigger lazy-loaded content, sticky headers are handled, and images are given time to load — the same capture pipeline that powers the url-to-pdf endpoint.
2. Materialise. From the rendered DOM, perceive builds whatever you listed in outputs: Markdown, cleaned/raw HTML, links, images, a screenshot, a PDF.
3. Extract. If you requested structured output, perceive runs a heuristic pass for page metadata, JSON-LD, headings, and tables. If you also send a schema and your plan carries the LLM tier, an Anthropic Claude Haiku model fills the schema when the heuristic pass comes up short.
4. Score. A render-quality score (0.0–1.0) flags pages that look blocked by anti-bot protection or hidden behind a login wall, so you can tell a real render from a challenge page.

Binary and text outputs (Markdown, HTML, screenshots, PDFs, the link and image JSON) are uploaded to storage and returned as pre-signed URLs that expire after 15 minutes. The structured block is returned inline in the JSON. Re-fetch any operation with GET /v2/perceive/{operation_id} to get a fresh set of signed URLs.

Request parameters

Core

Outputs

outputs accepts any combination of these names:

Rendering and waiting

Authenticated and custom requests

Structured extraction

When structured is in outputs, the extract list controls which fields perceive pulls. Ask for nothing and it defaults to metadata and structured_data.

To be straight about it: prices, contacts, and technologies are reserved names. Request one today and it does not error — it lands in the warnings array and is dropped from structured.

Schema-driven extraction

Send a schema to pull specific fields into structured.extracted:

{
    "url": "https://example.com/product/widget",
    "outputs": ["markdown", "structured"],
    "schema": {
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "price": {"type": "number"},
            "in_stock": {"type": "boolean"}
        }
    }
}

The LLM extraction tier (Anthropic Claude Haiku) fills the schema, and it fires only when all of these hold: you sent a schema, your plan carries the LLM tier (Starter and up), the page was not scored as blocked, and the heuristic pass left schema fields empty. When it runs, extraction_tier is "llm", and tokens and cost_cents report what that extraction cost; otherwise extraction_tier is "heuristic" and both are zero.

Note. Schema extraction is hard-capped to protect your bill: a single extraction is capped per request, and per-project daily spend is capped by plan. If a cap is hit, perceive returns the heuristic result with a note in warnings rather than overspending. On a plan without the LLM tier, you get heuristic structured data only.

Response

Both POST /v2/perceive and GET /v2/perceive/{operation_id} return the same object.

Retrieve an operation

Signed URLs expire after 15 minutes. To download an output later, re-fetch the operation — perceive re-signs every URL from the stored object keys. No re-render happens, so this does not consume quota.

curl https://api.enconvert.com/v2/perceive/per_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7 \
  -H "X-API-Key: sk_live_your_private_key"

An unknown operation ID, or one that belongs to a different project, returns 404 — existence is never leaked across projects.

Batch perception

POST /v2/perceive/batch perceives a list of URLs that share one options block. Each URL is rendered through the same pipeline as a single call and produces its own operation row.

curl -X POST https://api.enconvert.com/v2/perceive/batch \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com/a",
      "https://example.com/b",
      "https://example.com/c"
    ],
    "options": {"outputs": ["markdown"]},
    "output_mode": "manifest"
  }'

Batches of 10 URLs or fewer run inline and answer 200 with every result populated. Larger batches answer 202 with a job_id; the URLs are drained one at a time and you poll for results:

curl https://api.enconvert.com/v2/perceive/batch/{job_id} \
  -H "X-API-Key: sk_live_your_private_key"

The batch response reports aggregate progress and carries one full perceive result per URL once rendered:

{
    "job_id": "bat_8c1a...",
    "status": "partial",
    "output_mode": "manifest",
    "total": 3,
    "completed": 2,
    "failed": 1,
    "pending": 0,
    "items": [
        {"operation_id": "per_...", "status": "completed", "url": "https://example.com/a"},
        {"operation_id": "per_...", "status": "completed", "url": "https://example.com/b"},
        {"operation_id": "per_...", "status": "failed", "url": "https://example.com/c"}
    ]
}

status is queued, processing, completed, failed, or partial (some URLs succeeded, some failed). Set output_mode to zip to bundle every artifact into a single ZIP, returned under the zip field once the batch finishes. Batch access and the maximum batch size are plan-gated; see the pricing page.

Caching

cache_mode controls how perceive treats its 1-hour result cache, keyed by your project, the URL, and the render-affecting request options.

Worth flagging: a cache hit still counts as one perceive operation against your monthly quota. The quota meters operations, not browser renders — the cache saves you render time, not quota.

Code examples

curl — Markdown only

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/blog/post",
    "outputs": ["markdown"]
  }'

curl — Markdown plus structured data

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "outputs": ["markdown", "structured"],
    "extract": ["metadata", "structured_data", "tables"]
  }'

curl — Full outputs plus PDF

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/report",
    "outputs": ["markdown", "html_cleaned", "screenshot_full_page", "pdf"],
    "pdf_options": {"format": "A4", "print_background": true}
  }'

Python

import requests

response = requests.post(
    "https://api.enconvert.com/v2/perceive",
    headers={"X-API-Key": "sk_live_your_private_key"},
    json={
        "url": "https://example.com/pricing",
        "outputs": ["markdown", "structured"],
        "extract": ["metadata", "tables"],
    },
)
response.raise_for_status()
data = response.json()

# Download the Markdown artifact from its signed URL
markdown_url = data["outputs"]["markdown"]["url"]
markdown_text = requests.get(markdown_url).text

print(data["structured"])
print(markdown_text)

Node.js

const res = await fetch("https://api.enconvert.com/v2/perceive", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "sk_live_your_private_key"
    },
    body: JSON.stringify({
        url: "https://example.com/pricing",
        outputs: ["markdown", "structured"],
        extract: ["metadata", "tables"]
    })
});

const data = await res.json();

// Download the Markdown artifact from its signed URL
const markdownText = await fetch(data.outputs.markdown.url).then(r => r.text());

console.log(data.structured);
console.log(markdownText);

If you call EnConvert from Claude, Cursor, or another MCP client, the same capability is exposed as the perceive_url tool — see the MCP server page.

Plan gating

V2 perceive operations are a separate counter from V1 conversions. V1 plans include no perceive quota; you need a V2-inclusive plan.

Batch access and per-batch size limits, basic-auth/cookie/header support, and proxy_url (Business+, when it ships) are gated by plan. Current numbers live on the pricing page.

Error responses

The full status-code reference is in the error-codes guide.

Limits