Tools API docs

Visualization API

Turn a natural-language query into an interactive HTML visualization, streamed over Server-Sent Events (SSE). The response's atlasArtifact.html is a complete HTML document (including DOCTYPE), so you can render it directly in an iframe srcdoc (or a webview). You don't need to write the visualization chart code yourself.

A single endpoint (/api/v1/tools/visualization) offers two packages depending on the request body.

Visualization only : Uses the query parameter only. Visualize directly without web search.
Web Search + Visualization : Uses the query parameter with is_search_context: true. Injects web search results as grounding for the visualization.

When to use it

When you need a rendered visualization — chart / diagram / process / summary — rather than text or links
When you want to show a user query as an instant visualization widget
When you run your own LLM/RAG pipeline and only want to delegate visualization rendering to Visualization
(Web + Visualization) When you want to visualize with references grounded in fresh web results

What you get

atlasArtifact.html: a complete HTML document. Inject directly into iframe srcdoc
(Web Search + Visualization) data-search-references: source links used for grounding

Packages

Package	Trigger (body)	Description
Visualization only	`query`	Visualization of the result only; requires building your own search engine separately.
Web Search + Visualization	`query` • `is_search_context: true`	Visualization with web search grounding + references.

Branching rule: if is_search_context: true, Web Search + Visualization; otherwise Visualization only.

Endpoints

HTTP (Streaming)

Bash

POST https://platform.liner.com/api/v1/tools/visualization

The response is Content-Type: text/event-stream (SSE).

Authentication

Every request must include your API key in the x-api-key header.

Bash

x-api-key: <YOUR_API_KEY>

Request

Headers

Header	Value
`x-api-key`	API key
`Content-Type`	`application/json`

Body: Visualization only

Field	Type	Required	Description
`query`	string	Yes	The natural-language query to visualize
`appearance`	string	No	"light" or "dark". Default "light".
stream	boolean	No	Set to `false` to receive one JSON response instead of an SSE stream. Defaults to `true`.

Body: Web Search + Visualization

Field	Type	Required	Description
`query`	string	Yes	The natural-language query to visualize
`is_search_context`	boolean	Yes	When set to `true`, injects web search results as grounding
`date_range`	string	No	One of past_day, past_week, past_month, past_year
`max_results`	integer	No	1–20, default 10
`appearance`	string	No	"light" or "dark". Default "light".
stream	boolean	No	Set to `false` to receive one JSON response instead of an SSE stream. Defaults to `true`.

Examples: Visualization only

JSON

{ "query": "Step-by-step process of photosynthesis" }

Examples: Web Search + Visualization

JSON

{
  "query": "Apple vs Microsoft 2024 revenue comparison",
  "is_search_context": true,
  "date_range": "past_year",
  "max_results": 10,
  "appearance": "light"
}

Response (SSE)

Content-Type: text/event-stream. Each event uses the SSE message format below.

Bash

event: data
data: {"type":"<event-type>", ...}

The stream ends with data: [DONE].

Event order

Bash

start → start-step
      → (data-search-references)   // Web Search + Visualization only, before the artifact
      → data-atlas
      → finish-step → finish → [DONE]

Event types

Type	Description
`start`	Carries `message_id` and `message_metadata` (`request_id`, `trace_id`).
`start-step`	Beginning of a processing step.
`data-search-references`	(Web Search + Visualization) source links used for grounding. Emitted before `data-atlas`.
`data-atlas`	The visualization artifact. Contains `atlasArtifact`.
`data-error`	Error payload. Fixed id `data-error-1`. Followed by `[DONE]`.
`finish-step` / `finish`	Step / stream completion markers.

`atlasArtifact` fields

Field	Type	Description
`html`	string	Complete HTML document. Inject directly into `iframe srcdoc`.
`theme`	string	comparison, hierarchy, process, trend_analysis, summary, distribution, explainer, calculator, game, instrument.
`description`	string	Model-generated description of the visualization.

Example SSE stream

Bash

event: data
data: {"type":"start","message_id":"msg-...","message_metadata":{"request_id":"...","trace_id":"api_visualization_..."}}
 
event: data
data: {"type":"start-step"}
 
// Web Search + Visualization only
event: data
data: {"type":"data-search-references","id":"data-search-references-a1b2c3d4","data":{"references":[{"title":"...","url":"...","hostname":"...","date":"..."}]}}
 
event: data
data: {"type":"data-atlas","id":"data-atlas-e5f6g7h8","data":{"atlasArtifact":{"html":"<!DOCTYPE html>...","theme":"comparison","description":"...","resourceId":"viz_..."}}}
 
event: data
data: {"type":"finish-step"}
event: data
data: {"type":"finish"}
data: [DONE]

Non-streaming response (`stream: false`)

Send "stream": false in the request body to receive a single JSON object instead of an SSE stream.

JSON

{
  "answer": "Paris is the capital of France ((1)). ...",
  "references": [
    {
      "title": "Paris - Wikipedia",
      "url": "https://en.wikipedia.org/wiki/Paris",
      "hostname": "en.wikipedia.org",
      "date": ""
    }
  ],
  "chunks": [{ "type": "data-follow-up-questions", "data": { "questions": ["..."] } }]
}

Field	Description
`answer`	The complete answer, with every `text-delta` already concatenated. Omitted when the endpoint returns no text.
`references`	Sources merged from all `data-search-references` events. Fields are not trimmed. Omitted when there are none.
`chunks`	Events that cannot be folded into the fields above, passed through unchanged. Omitted when empty.

stream defaults to true, so existing integrations are unaffected.
Treat chunks as open-ended. New event types are passed through here rather than dropped, so do not assume a fixed set.
The response is sent only after the request finishes. A long-running request can hit an intermediary timeout before the first byte arrives — prefer the streaming mode for those.

Code examples

Bash

curl -N -X POST https://platform.liner.com/api/v1/tools/visualization \
  -H "x-api-key: $LINER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "Apple vs Microsoft 2024 revenue comparison", "is_search_context": true }'

TypeScript

const res = await fetch('https://platform.liner.com/api/v1/tools/visualization', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.LINER_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'Apple vs Microsoft 2024 revenue comparison',
    is_search_context: true,
  }),
});
for await (const chunk of res.body!) {
  process.stdout.write(Buffer.from(chunk).toString());
}

Python

import os, requests
 
with requests.post(
    "https://platform.liner.com/api/v1/tools/visualization",
    headers={
        "x-api-key": os.environ["LINER_API_KEY"],
        "Content-Type": "application/json",
    },
    json={"query": "Apple vs Microsoft 2024 revenue comparison", "is_search_context": True},
    stream=True,
) as r:
    for line in r.iter_lines(decode_unicode=True):
        if line:
            print(line)

Errors

Status	Code	Retryable	Meaning
400	`INVALID_REQUEST`	❌	Malformed body or missing required field.
401	`UNAUTHORIZED`	❌	Missing or invalid `x-api-key`.
402	`INSUFFICIENT_CREDITS`	❌	Account credit balance too low. Top up, then send the request again.
429	`RATE_LIMITED`	✅	Rate limit exceeded. Honor the `Retry-After` header.
500	`INTERNAL_ERROR`	✅	Server-side failure. Retry with backoff.
502	`DOWNSTREAM_ERROR`	Depends	Upstream failure. Use `retryable` in the response body to decide whether to retry.

For how to decide on retries and the shape of the error body, see Rate limits → "Error responses and retries".

Implementation notes

Render the returned html in an iframe srcdoc. Consider CSP / sandbox and mobile webview policies; in environments where srcdoc is restricted, host the HTML and load it via src.
Recommended pattern: call from your backend and forward the SSE stream to the frontend.
Web Search + Visualization performs search + visualization, so it has higher latency than Visualization only. References arrive before data-atlas.
Average latency is about 20–30 seconds (including visualization rendering).

Where to go next

Use the navigation below to get started or go deeper:

When to use it

What you get

Packages

Endpoints

Authentication

Request

Headers

Body: Visualization only

Body: Web Search + Visualization

Examples: Visualization only

Examples: Web Search + Visualization

Response (SSE)

Event order

Event types

atlasArtifact fields

Example SSE stream

Non-streaming response (stream: false)

Code examples

Errors

Implementation notes

Where to go next

`atlasArtifact` fields

Non-streaming response (`stream: false`)