Quickstart

Set your key once:

export TILION_API_KEY="ph_live_..."

Create a session. The Idempotency-Key header is optional; with it a retry after a lost reply returns the same session instead of starting a second one.

curl -X POST https://back.tilion.dev/v1/session \
  -H "Authorization: Bearer $TILION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-1" \
  -d '{}'

{
  "session_id": "sess_6ac44536ab704d77b335f09ca281ada1",
  "state": "ready",
  "mode": "ephemeral",
  "region": null,
  "owner": "acme",
  "created_at": 1792420162.081036,
  "last_active": 1792420162.0894966,
  "idle_timeout": 300.0,
  "ttl": 3600.0,
  "expires_at": 1792420462.0894966,
  "connect_url": "wss://back.tilion.dev/v1/session/sess_6ac44536ab704d77b335f09ca281ada1/cdp?token=<token>",
  "connect_expires_in": 1800,
  "playwright_url": "wss://back.tilion.dev/v1/session/sess_6ac44536ab704d77b335f09ca281ada1/playwright?token=<token>",
  "exit_id": null,
  "persona": "tenant-e348aa33fc1f00377fb8b75b",
  "full_browser": false,
  "geo_applied": null,
  "geo_unsupported": null,
  "site_check": null,
  "replay_url": null
}

The status is 201. A retry with the same Idempotency-Key answers 201 with the same session_id and a fresh connect_url; no second browser is started. Open a page in the session’s tab:

curl -X POST https://back.tilion.dev/v1/session/sess_6ac44536ab704d77b335f09ca281ada1/navigate \
  -H "Authorization: Bearer $TILION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/"}'

{
  "session_id": "sess_6ac44536ab704d77b335f09ca281ada1",
  "final_url": "https://example.com/",
  "title": "Example Domain",
  "status": "ok",
  "http_status": 200,
  "error": null,
  "failure_type": null,
  "cause": null,
  "self_healed": false,
  "recovery": null,
  "detected": null,
  "held": null,
  "requested_url": "https://example.com/",
  "redirected": false
}

Fetch a page and get its text back in one call:

curl -X POST https://back.tilion.dev/v1/fetch \
  -H "Authorization: Bearer $TILION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "sess_6ac44536ab704d77b335f09ca281ada1", "url": "https://example.com/"}'

{
  "session_id": "sess_6ac44536ab704d77b335f09ca281ada1",
  "final_url": "https://example.com/",
  "status": "ok",
  "http_status": 200,
  "job_id": "sess_6ac44536ab704d77b335f09ca281ada1.37c653d22892473ebab5ed247224dd4a",
  "job": null,
  "captcha": "none",
  "title": "Example Domain",
  "text": "This domain is for use in documentation examples without needing permission. ...",
  "html_len": 1974,
  "html": null,
  "self_healed": false,
  "recovery": null,
  "held": null,
  "detected": null,
  "content_ok": true,
  "status_reconciled": null,
  "requested_url": "https://example.com/",
  "redirected": false,
  "error": null,
  "failure_type": null,
  "cause": null,
  "reason": null,
  "origin": null,
  "premium_required": null,
  "readiness": null,
  "selector_found": null,
  "settle": null
}

Extract an article as Markdown plus page metadata. formats picks what comes back; max_chars cuts the Markdown at a block boundary and reports truncated.

curl -X POST https://back.tilion.dev/v1/extract \
  -H "Authorization: Bearer $TILION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_6ac44536ab704d77b335f09ca281ada1",
    "url": "https://en.wikipedia.org/wiki/Web_scraping",
    "formats": ["markdown", "metadata"],
    "max_chars": 1200
  }'

{
  "job_id": null,
  "data": null,
  "extract_tokens": null,
  "session_id": "sess_6ac44536ab704d77b335f09ca281ada1",
  "final_url": "https://en.wikipedia.org/wiki/Web_scraping",
  "status": "ok",
  "blocked_reason": null,
  "self_healed": false,
  "premium_required": null,
  "title": "Web scraping - Wikipedia",
  "markdown": "# Web scraping\n\nFrom Wikipedia, the free encyclopedia\n\n...",
  "markdown_len": 963,
  "tokens_estimate": 240,
  "text": null,
  "html": null,
  "links": null,
  "metadata": {
    "title": "Web scraping - Wikipedia",
    "description": null,
    "canonical": "https://en.wikipedia.org/wiki/Web_scraping",
    "lang": "en",
    "og_title": "Web scraping - Wikipedia",
    "og_description": null,
    "og_image": null,
    "og_site_name": null,
    "published_time": null,
    "modified_time": null,
    "author": null,
    "word_count": 4353,
    "reading_time_min": 22
  },
  "truncated": true
}

Search the web. No session is needed; the API runs the search on its own browser pool.

curl -X POST https://back.tilion.dev/v1/search \
  -H "Authorization: Bearer $TILION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "chrome devtools protocol", "count": 3}'

{
  "query": "chrome devtools protocol",
  "engine": "duckduckgo",
  "count": 3,
  "offset": 0,
  "total_found": 10,
  "has_more": true,
  "results": [
    {
      "title": "Chrome DevTools Protocol",
      "url": "https://chromedevtools.github.io/devtools-protocol/",
      "snippet": "Chrome DevTools Protocol The Chrome DevTools Protocol (CDP) is a JSON-based protocol that connects debug and automation targets ...",
      "rank": 1,
      "engine": "duckduckgo",
      "domain": "chromedevtools.github.io",
      "published": null
    }
  ],
  "status": "ok",
  "reason": null,
  "engines_tried": [{"engine": "duckduckgo", "status": "ok", "reason": null, "took_ms": 1122}],
  "fallback_from": null,
  "cached": false,
  "took_ms": 1238,
  "suggestion": null,
  "operators": [],
  "knowledge_graph": null,
  "people_also_ask": [],
  "related_searches": [],
  "answer_box": null,
  "region": null,
  "exit": null
}

Release the session:

curl -i -X DELETE https://back.tilion.dev/v1/session/sess_6ac44536ab704d77b335f09ca281ada1 \
  -H "Authorization: Bearer $TILION_API_KEY"

The answer is 204 No Content with Location: /v1/session/sess_6ac44536ab704d77b335f09ca281ada1/status. A second DELETE answers 204 again. Reading the session afterwards answers 410 with its terminal record; see Errors.

Get started

Account

Sessions

Reading pages

Automation

MCP