schemas

The request and response bodies of the HTTP API. The rows of a table have no schema here: their shape is the table's own. See the OpenAPI document of a server for them.

ApiError

The error body every failing request comes back with.

key	type	default	description
error	string	required	What went wrong, as one line.

ApplyResult

What became of an applied change: POST /v1/config/apply.

key	type	default	description
change	integer		The pending change, when queued.
plan	PlanInfo	required
status	string	required	applied (live now), rebuilding (live when the rebuild is done), queued (waiting for approval) or unchanged.
version	integer	required	The config version: the new one when applied.

ConfigChange

A proposed change: files to set or remove (null), against base_version. Files not named stay as they are, unless replace is set: then the named files are the whole config (a revert).

key	type	default	description
agent	boolean		An agent makes it: the server applies it only as agents.auto_apply allows (never to a dashboard a person wrote last), and proposes it otherwise. Always so with the agent token.
approve	boolean	false	Apply even if it destroys data (plan §8.2, destructive).
author	string		Who makes it, for the history and the commit message.
base_version	integer	required
files	map of string
propose	boolean	false	Put it in the approval queue instead of applying it.
replace	boolean	false

ConfigError

Why a change wasn't made (409 or 422).

key	type	default	description
current_version	integer	required	The version changes are made against now.
error	string	required
plan	PlanInfo

ConfigState

GET /v1/config: the files of the current version.

key	type	default	description
external	ExternalEdits		Edits in the config directory that aren't applied.
files	list of ConfigFile	required
live_version	integer	required	The version the server runs: behind version while a change is being rebuilt.
rebuild	RebuildInfo
version	integer	required
writeback	boolean	required	Whether applied changes are written back to the config directory.

ConfigVersion

One version's files: GET /v1/config/versions/{version}.

key	type	default	description
files	list of ConfigFile	required
info	VersionInfo	required

EmbedRequest

POST /v1/auth/embed: the views a token may open.

key	type	default	description
views	list of string	required

EmbedToken

A token for embedded views.

key	type	default	description
idle_seconds	integer	required	How long it lasts unused.
token	string	required	Send it as ?token= on /v1/ws.

IngestError

A rejected write: nothing was written.

key	type	default	description
error	string	required	One line: the problem, or how many there are.
errors	list of RowError	required	The problems, by row and column (at most 100).
more	integer	required	Problems beyond the ones listed.

IngestResponse

What a successful write answers (POST/DELETE /v1/tables/{table}/rows).

key	type	default	description
epoch	integer	required	The epoch from which the change is visible to queries. With ?wait=visible it already is when the response arrives.
missing	integer	required	Keys that matched no row (deletes only).
replaced	integer	required	Existing rows replaced (upserts) or deleted.
written	integer	required	Rows written.

ModelInfo

The semantic model as the UI shows it (GET /v1/model).

key	type	default	description
ai_context	any		The model's Ossie ai_context (instructions, synonyms, examples for an agent), as written.
datasets	list of DatasetInfo	required
description	string
filter_direction	string	one_to_many	Which way selections flow along relationships: one_to_many (from the one side to the many side) or both.
metrics	list of MetricInfo	required
name	string		The Ossie model's name.
relationships	list of RelationshipInfo	required

PendingChange

A change waiting for approval: GET /v1/changes.

key	type	default	description
at	string	required	RFC 3339.
author	string	required
base_version	integer	required
by	string	person	person or agent, as in [VersionInfo::by].
files	map of string	required	The files it sets or removes.
id	integer	required
plan	PlanInfo	required
replace	boolean	false
source	string	required

PlanInfo

What a change would do: POST /v1/config/plan.

key	type	default	description
base_version	integer	required
changes	list of PlannedChange	required
class	string		The worst class among the changes; None without changes.
problems	list of ConfigProblem	required
problems_text	string	required	The problems as tidepool validate prints them.
text	string	required	The plan as tidepool plan prints it.
valid	boolean	required	Whether the config compiles.
warnings	list of string	required

Preview

The newest rows of a table (GET /v1/tables/{table}/preview).

key	type	default	description
columns	list of string	required
epoch	integer	required
rows	list of list of any	required	Newest first; values as JSON (decimals, dates and timestamps as strings).

ProbeStatus

What the probes (GET /healthz, GET /readyz) answer.

key	type	default	description
status	ProbeState	required

QueryRequest

A query: metrics grouped by dimensions, under a selection. The same engine dashboards use, without a subscription.

key	type	default	description
dimensions	list of QueryDimension	[]	Fields to group by, in result order.
filters	list of QueryFilter	[]	The selection: conditions on fields. A metric is filtered by the fields its table reaches; the others don't apply to it.
limit	integer		At most this many rows.
metrics	list of string	required	Metrics by name, as in the model.
sort	list of QuerySort	[]	Result columns to sort by. Default: the dimensions, ascending.

QueryResult

A query's answer.

key	type	default	description
as_of	string		When that epoch was published (RFC 3339, UTC): how fresh the data the answer reads is.
columns	list of QueryColumn	required	Dimensions first, then metrics, in request order.
epoch	integer	required	The data epoch the answer was computed from.
rows	list of list of any	required	Values as JSON: decimals, dates and timestamps as strings, so nothing is lost on the way through.

RowsRequest

The newest rows of a table that pass some filters (POST /v1/rows).

key	type	default	description
fields	list of string	required	The columns, dataset.field: fields of the table whose rows these are, and of tables it reaches. The table is the one that reaches all of them (and the fewest others).
filters	list of QueryFilter	[]	As in a query: the fields the table reaches filter its rows.
limit	integer		How many rows, newest first: 100 when not given, 1000 at most.

SelectionChange

A session's new selection, whole: one condition per field, as a query's filters are written. One step in its history, so Back undoes it.

key	type	default	description
fields	list of QueryFilter	required

ServerInfo

What GET /v1/info answers: which server this is.

The UI shows it in its footer, and a client can check api_version before it relies on anything else.

key	type	default	description
api_version	integer	required	The version of the HTTP API this server speaks. Bumped on breaking changes to anything under /v1; currently 1.
name	string	required	Always "tidepool".
version	string	required	The server's crate version, e.g. 0.0.1.

SessionInfo

What a request may do: GET/POST /v1/auth/session. A level that needs no token is true for everyone.

key	type	default	description
admin	boolean	required
ingest	boolean	required
read	boolean	required

SessionSelection

A live session's selection (GET and PUT /v1/sessions/{id}/selection).

key	type	default	description
can_back	boolean	required
can_forward	boolean	required
dashboard	string		The dashboard or view it shows, if any.
fields	list of SelectedField	required
session	string	required

StatusInfo

What the server is doing (GET /v1/status).

key	type	default	description
cache_bytes	integer	required	Memory held by the engine's caches (join columns, kept answers).
config_version	integer	0	The config version the server runs.
dictionary_bytes	integer	required	Memory held by dictionary values.
durability	DurabilityStatus		None when data lives in memory only.
epoch	integer	required
epoch_publish_ms	number	0.0	The last epoch's publish, in milliseconds.
live_refresh_ms	number	0.0	The last refresh of every live session after an epoch, in milliseconds.
rebuild	RebuildInfo		A model change being rebuilt in the background.
sessions	integer	required	Live dashboard sessions.
tables	list of TableStatus	required
uptime_seconds	integer	required

TableInfo

A table, as listed by GET /v1/tables.

key	type	default	description
bytes	integer	required	Approximate memory held by the table's segments.
columns	list of ColumnInfo	required
epoch	integer	required	The epoch these numbers are from.
event_time	string		The column that says when a row happened, if the table has one.
mode	string	required	append or upsert.
name	string	required
primary_key	list of string	required
retention	string		How long rows are kept, by their event time (730d).
rows	integer	required	Rows currently stored (not counting deleted ones).
rows_per_second	number	required	Write rate over the last ten seconds.
segments	integer	0	Segments the table's rows are held in.
written_total	integer	required	Rows written since the server started.

VersionInfo

One applied version: GET /v1/config/versions.

key	type	default	description
at	string	required	RFC 3339.
author	string	required
by	string	person	Who wrote it: person, agent, files (the config directory) or startup.
class	string
source	string	required	startup, api, files or revert.
summary	string	required
version	integer	required

ViewInfo

A view (POST /v1/views): a dashboard that lives only in memory.

key	type	default	description
dashboard	DashboardInfo	required
id	string	required	What open_dashboard opens it by: ~ and 32 hex digits.
yaml	string	required	Its dashboard file, as YAML: what saving it writes.

ViewProblems

Why a view couldn't be made.

key	type	default	description
error	string	required
problems	list of ConfigProblem	required
problems_text	string	required	The problems as the CLI prints them, with the lines they point at.

ExternalEdits

Edits found in the config directory that the server hasn't applied.

key	type	default	description
change	integer		Waiting for approval as this pending change.
problems	string		They don't compile: what's wrong, rendered.

ConfigFile

One config file, by its path in the config directory.

key	type	default	description
path	string	required
text	string	required

RebuildInfo

A change being built in the background (plan §8.2, rebuild).

key	type	default	description
rows	integer	required
rows_done	integer	required
version	integer	required

RowError

One problem with a write.

key	type	default	description
column	string
message	string	required
row	integer		The row's position in the batch, from 0; absent for problems with the body as a whole (or, for Arrow, a whole column).

DatasetInfo

key	type	default	description
ai_context	any		The dataset's Ossie ai_context, as written.
description	string
fields	list of FieldInfo	required
name	string	required
table	string	required	The table it reads.

MetricInfo

key	type	default	description
ai_context	any		The metric's Ossie ai_context, as written.
anchor	string		The table whose rows a base metric aggregates.
dashboards	list of string	required	Dashboards that show it.
description	string
expression	string	required	The SQL expression.
format	string		How its value shows, when a visual does not set a different format: currency:EUR compact.
ignores	list of string	required	Fields whose selection it ignores (* for all).
kind	string	required	base (aggregates rows) or derived (combines other metrics).
name	string	required
time_offset	string		E.g. -1 year on orders.ordered_at.
time_window	string		E.g. ytd on orders.ordered_at.
totals	list of string		The dimensions it is computed without (* for all): a total.

RelationshipInfo

key	type	default	description
ai_context	any		The relationship's Ossie ai_context, as written.
from	string	required	The many side.
from_columns	list of string	required
name	string	required
role	string		Tells apart relationships between the same two tables (order date vs ship date).
to	string	required	The one side.
to_columns	list of string	required

PlannedChange

One change a plan makes.

key	type	default	description
class	string	required	safe, rebuild or destructive.
detail	string
kind	string	required	table, column, relationship, dataset, field, metric, dashboard or setting.
note	string
op	string	required	add, remove, change or rename.
subject	string	required

ConfigProblem

One problem with a config, located.

key	type	default	description
column	integer
file	string
help	string
line	integer		1-based, when the problem points at a token.
message	string	required
severity	string	required	error or warning.

ProbeState

value	description
ok	The process is up and serving HTTP.
ready	Ready to take traffic: config applied, data recovered.
starting	Up, but not ready yet (still starting, or recovering).

QueryDimension

A field to group by.

key	type	default	description
field	string	required	dataset.field.
grain	string		For time fields: day, week, month, quarter or year, and for timestamps also minute or hour.
level	integer		For hierarchy fields: group by each node's ancestor at this depth (0 is the roots); nodes not that deep group as null.

QueryFilter

A condition on a field: in, a half-open range from <= value < to (either end may be left out), a window of time relative to now ({"unit": "day", "last": 7}), or for a string field the values that contains a text, ignoring the case of ASCII letters. Values are written as in ingested rows: decimals, dates and timestamps as strings or numbers.

key	type	default	description
contains	string		The text a string field's values contain.
field	string	required	dataset.field.
from	any
in	list of any
relative	RelativeWindow
to	any

QuerySort

A result column to sort by, by its name in [QueryResult::columns].

key	type	default	description
column	string	required
desc	boolean	false

QueryColumn

key	type	default	description
name	string	required	dataset.field (with :grain) for dimensions, the metric's name for metrics.
role	string	required	dimension or metric.
type	string	required	bool, int, float, decimal(s), string, date, timestamp or timestamptz.

SelectedField

One field's selection.

key	type	default	description
contains	string		The text searched for.
field	string	required
from	any
relative	RelativeWindow		A window relative to now; from and to are where it is now.
to	any
values	list of any		The values selected, for a value selection.

DurabilityStatus

key	type	default	description
checkpoint_age_seconds	integer		Seconds since that checkpoint was written (None: none yet).
checkpoint_lsn	integer	required	The last write the newest checkpoint holds.
data_dir	string	required
last_lsn	integer	required	The last write logged.
mode	string	required	fsync or async.

TableStatus

key	type	default	description
bytes	integer	required
name	string	required
rows	integer	required
rows_per_second	number	required
segments	integer	required

ColumnInfo

key	type	default	description
encoding	string	required	dict or plain.
filled	string		credential or received when the server fills the column on every write: producers leave it out.
name	string	required
nullable	boolean	required
type	string	required	The column type as written in the table file, e.g. decimal(14,2).

DashboardInfo

key	type	default	description
columns	integer	required
filters	list of FilterInfo	required
id	string	required	The file name, and the dashboard's URL path.
name	string	required
row_height	integer	required
visuals	list of VisualInfo	required

FieldInfo

key	type	default	description
ai_context	any		The field's Ossie ai_context, as written.
description	string
expression	string		The expression, for a derived field.
grains	list of string		The grains a visual may group a time field by (day, month, …); empty for other fields.
hierarchy	HierarchyInfo		For a hierarchy field: the columns its tree is made of.
is_time	boolean	required
label	string		What to call the field on screen.
name	string	required
type	string	required	string, int, decimal(2), date, …

RelativeWindow

A window of whole periods relative to now: last periods of unit, ending with the current one, or ago periods before it. "The last 7 days" is {unit: day, last: 7} (today and the six days before it); "last month" is {unit: month, last: 1, ago: 1}. Periods start where grains do (weeks on Monday), in UTC.

key	type	default	description
ago	integer
last	integer	required
unit	RelativeUnit	required

FilterInfo

key	type	default	description
default	RelativeWindow		The window a date_range starts with when the dashboard is opened.
field	string	required	dataset.field.
measure	string		The metric shown beside each value instead of its rows.
measure_format	string		The measure's format (currency:EUR compact, …; see the metric's format).
timed	boolean	false	Whether the field has a time of day, so windows of hours and minutes apply to it (a date has none).
widget	string	required	list, tree, date_range or search.

VisualInfo

key	type	default	description
across	list of QueryDimension		A pivot's dimensions along the top; its dimensions are down the side. Its frames' rows are grouped by both, dimensions first.
at	GridAt	required
compare	string		A KPI's comparison metric.
description	string
dimensions	list of QueryDimension	required
formats	map of string		How each metric reads here, by name: the visual's own format for it, else the metric's. Metrics without one aren't listed.
id	string	required
metrics	list of string	required
on_brush	boolean	required	Brushing a range selects it.
on_click	boolean	required	Clicking a value selects it.
title	string		What its header says, when the file gives it.
totals	boolean		A pivot's total row and column come in its frames' totals.
type	string	required	kpi, bar, line, table, pie, scatter, heatmap, pivot, filter or rows.
widget	string		A filter visual's list: list or tree. Its frames are the filter frames of its dimension's field.

HierarchyInfo

A hierarchy field's columns (plan §5.6).

key	type	default	description
key	string	required	The key: a node's identity, and the field's values.
kind	string
label	string
parent	string	required	The parent's key.

RelativeUnit

Type: minute · hour · day · week · month · quarter · year.

GridAt

key	type	default	description
h	integer	required
w	integer	required
x	integer	required
y	integer	required