Docs/Response_Format

Response Format

Strict JSON typings for all ingestion modes. Understand the data topography before you build.

Data Topography

Mode	Primary Output	Binary Data	Cost	Use Case
`read`	Markdown / Text	null	1 Credit	LLM RAG Context
`map`	Coordinate Tree	null	2-10 Credits	Agent Navigation
`visual`	Coordinates + Screenshot	base64_png	10 Credits	Multimodal Vision

Engine Specifications

Engine	Flag	Latency	Accuracy	Cost (Map)
Servo (Fast)	performance	<400ms	97% (No JS)	2 Credits
Chrome (Full)	precision	~1.5s	99.9% (Full JS)	10 Credits

Reader Mode

Input Request

curl -X POST https://api.sentienceapi.com/v1/observe \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "url": "https://example.com",
    "mode": "read",
    "format": "markdown",
    "options": {
      "contentLimit": 50000
    }
  }'

Output JSON

{
  "status": "success",
  "url": "https://example.com",
  "title": "Example Domain",
  "content": "Example Domain\n\nThis domain is for use in...",
  "format": "markdown",
  "author": null,
  "published_date": null,
  "word_count": 95,
  "reading_time_minutes": 1,
  "timestamp": "2025-12-12T10:30:00.123Z"
}

Map Mode

Input Request

curl -X POST https://api.sentienceapi.com/v1/observe \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "url": "https://example.com",
    "mode": "map",
    "options": {
      "render_quality": "performance" 
    }
  }'

Output JSON

{
  "engine": "performance",
  "status": "success",
  "url": "https://example.com",
  "layout_viewport": {
    "width": 1024,
    "height": 768,
    "device_pixel_ratio": 1.0
  },
  "interactable_elements": [
    {
      "id": 1,
      "uid": "more-info-link",
      "tag": "a",
      "role": "link",
      "text": "More information...",
      "selector": "a[href='https://www.iana.org/domains/example']",
      "bbox": {
        "x": 100,
        "y": 200,
        "w": 150,
        "h": 20
      },
      "is_visible": true,
      "z_index": 0,
      "attributes": {
        "href": "https://www.iana.org/domains/example"
      }
    }
  ],
  "timestamp": "2025-12-12T10:30:00.456Z",
  "total_elements_extracted": 1,
  "filters_applied": {
    "limit": null,
    "filter": null
  }
}

Visual Mode

Input Request

curl -X POST https://api.sentienceapi.com/v1/observe \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "url": "https://example.com",
    "mode": "visual"
  }'

Output JSON

{
  "engine": "precision",
  "source": "precision_visual",
  "status": "success",
  "url": "https://example.com",
  "layout_viewport": {
    "width": 1024,
    "height": 768,
    "device_pixel_ratio": 1.0
  },
  "interactable_elements": [
    {
      "id": 1,
      "uid": "more-info-link",
      "tag": "a",
      "role": "link",
      "text": "More information...",
      "selector": "a[href='https://www.iana.org/domains/example']",
      "bbox": {
        "x": 100,
        "y": 200,
        "w": 150,
        "h": 20
      },
      "is_visible": true,
      "z_index": 0,
      "attributes": {
        "href": "https://www.iana.org/domains/example"
      }
    }
  ],
  "screenshot": {
    "type": "base64",
    "data": "iVBORw0KGgoAAAANSUhEUgAAA...",
    "format": "png",
    "size_bytes": 665432
  },
  "screenshot_error": null,
  "timestamp": "2025-12-12T10:30:00.812Z",
  "total_elements_extracted": 1
}

Screenshot Field Formats

The screenshot field supports two formats based on options.screenshot_delivery:

Format 1: Base64 (default)screenshot_delivery: "base64"

"screenshot": {
  "type": "base64",
  "data": "iVBORw0KGgoAAAANSUhEUgAAA...",
  "format": "png",
  "size_bytes": 665432
}

Format 2: Presigned URL (recommended for AI agents)screenshot_delivery: "url"

"screenshot": {
  "type": "url",
  "url": "https://sentience-screenshots.sfo3.digitaloceanspaces.com/screenshots/76795555-80be-4d27-84f0-73e0a0ce68c4.png?x-id=GetObject&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=7UL6GTGZBN3M2LVTRGVD%2F20251219%2Fsfo3%2Fs3%2Faws4_request&X-Amz-Date=20251219T051045Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&X-Amz-Signature=06ac3c6d6111109329417b82e35edb7438a40b29d0c806c85c5e39b7eac8cc4c",
  "format": "png",
  "size_bytes": 158277,
  "expires_at": "2025-12-20T05:10:45.401346170+00:00"
}

Universal Primitives

statusRequest health. Values: "success" | "error"

urlFinal resolved URL (post-redirects).

timestampISO 8601 server time.

errorDebug message (only present on non-200 status).

← Back: Authentication Next: Reader Mode →