Share URLs and Embedding

Every shared item of Kvery has a stable address. The share windows show them, and you can also build them yourself.

Address formats

Address	What it opens
https://app.kvery.io/query/execute/hash/{hash}	The page of a shared query: its form and result
https://app.kvery.io/query/api/{hash}	The public query API: the result as JSON
https://app.kvery.io/dashboard/hash/{hash}	A shared dashboard
https://app.kvery.io/deeplink?data=…	The mobile link: opens the shared query or dashboard in the Kvery mobile app
https://app.kvery.io/swagger/{hash}	The Swagger page of a group
https://app.kvery.io/swagger/data/{hash}	The OpenAPI document (JSON) of that Swagger page, for tools that import it

{hash} is the identifier of the item as the share window shows it. A query's Custom URL replaces the query's own part of it, and the $variables of a custom URL are path segments that the caller fills in with letters, digits, _ or - (for example users/$id is called as …/users/42).

The share windows

The Query sharing window of a query shows three blocks, each with a Copy to clipboard! button:

• Normal — the address of the shared query page.
• API (JSON) — the API endpoint, shown also while sharing is off. While sharing is off or the share has a password, the block notes "- Basic Auth (Username, Password)": API calls then need Basic Auth (see Calling a query that is not shared).
• Mobile — the mobile link with its QR code.

Normal and Mobile appear while sharing is on, and only when the method in front of the Custom URL is All or GET; a URL limited to POST, PUT, PATCH or DELETE has only the API endpoint. The Share dashboard window of a dashboard shows the Normal and Mobile blocks.

Parameters in the address

• Form values — query-string parameters fill the form variables of a shared query, for example …/query/execute/hash/{hash}?status=open.
• Draft — an editor of the query who is signed in can open the draft by adding ?draft.
• Cache — ?cache=0 bypasses the result cache (see Export and cache).

Display parameters

These parameters override the query's table settings on its pages:

Parameter	Overrides
hdscr=1 / hdscr=0	Hide description in shared view?
form=0 / form=1	Hide form in shared view? (form=0 hides the form)
sot=1 / sot=0	Show only table in shared view?
jsonSlug=1 / jsonSlug=0	Slug JSON keys of the API endpoint
responsive=1 / responsive=0	Responsive?
responsiveType=1 / responsiveType=0	Responsive data in modal?
scrollY=<pixels>	Table fix height in pixels
fixedColumnsFromLeft=<n>, fixedColumnsFromRight=<n>	Fixed columns from left / right (without responsive mode)
rowsPerPage=<n>	Rows per page (-1 shows every row)
refresh=<seconds>	Auto refresh table (sec) (5 or more)

Embedding in a frame

A shared query page, a shared dashboard, the Swagger page and the API endpoint can be shown in a frame (<iframe>) on a page of another site, and so can the run page of a query with ?iframe=1 (it needs a viewer who is signed in to Kvery and may run the query); the other pages of Kvery cannot.

<iframe src="https://app.kvery.io/query/execute/hash/{hash}?hdscr=1"
        style="width: 100%; height: 600px; border: 0;"></iframe>

The page of a shared query fills its frame and shows the result in a frame of its own, so give your frame the height you want.

Height messages

The page that runs the query reports its content height to the page that frames it with window.postMessage, each time the height changes. The message is an object:

Field	Value
sender	"kolt"
type	"documentReady" or "tableInitComplete"
documentHeight	The height of the content in pixels
locationHref	The address of the run page

The message has further fields (dashboardQueryId, chart) that Kvery's own dashboards use.

On the shared query page these messages go to the frame around the result, which is part of Kvery's page. To receive them on your own page, frame the run page itself: https://app.kvery.io/query/execute/hnif/{hash} (the same address with hnif in place of hash), and listen for the messages:

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://app.kvery.io') return;
  const data = event.data;
  if (data && data.sender === 'kolt' && data.documentHeight) {
    document.getElementById('kvery-frame').style.height = data.documentHeight + 'px';
  }
});