Skip to main content
DocumentationLibraryReference

Kater API

Kater API

The Kater API is what Kater promises to your code and your agents: find what the data team built, read its numbers, learn what each metric means, keep definitions in step with your other tools, and read what people asked. Every call acts as the signed-in person, with that person’s access.

Authentication

Send the access token of a signed-in person: Authorization: Bearer <token>. Run kater login once to get one. The token expires, so a job that runs with nobody signed in, such as a CI pipeline, cannot use the API yet. Some routes also need a permission, which their description names.

Terminal window
export KATER_API_URL="URL"
export KATER_API_TOKEN="TOKEN"

Stability

A stable route changes only by adding: a route, an optional field, an answer field or an error code. A route marked Beta can change, after a changelog entry 30 days before. A route that goes is first marked Deprecated with the day it goes: six months ahead for a stable route, 30 days for a beta one.

Usage

Start with the connections. Each other route takes a connection's name, or a path in it.

Terminal window
curl "$KATER_API_URL/v1/connection/list" \
  -H "Authorization: Bearer $KATER_API_TOKEN"

JSON in and out. Every failure answers one error body, with <code>error</code>, <code>code</code> and <code>request_id</code>. OpenAPI 3.1.0, version 1.0.0 of the Kater API: 24 routes.

Who you are

Check a token, and read the permissions of the person it signs in.

GET
/v1/me/access

Read the caller's permissions, groups and attributes

Reads who the caller is: their organisation, their user, their permissions, their groups and their attributes. Use it to check a token, and to learn what the caller may do before other requests.

Response

organizationId
string | null The caller's organisation, from their access token. Left out only when the directory names no organisation.
AccessUser
id REQUIRED
string The caller's PropelAuth user id.
email REQUIRED
string | null The caller's email address.
firstName REQUIRED
string | null The caller's first name. Null when PropelAuth has none.
lastName REQUIRED
string | null The caller's last name. Null when PropelAuth has none.
role REQUIRED
string The caller's PropelAuth role, for display.
avatarColor
string | null The colour the member selected for their avatar: the name of one of app-kit's `AVATAR_COLORS`, or a custom colour as lower-case `#rrggbb`. Null when they selected none, and the portal then gives them a colour from their user id.
permissions REQUIRED
Array<string> The caller's PropelAuth permissions. They decide what the caller can do, never the role name.
attributes REQUIRED
object The caller's own attributes together with those of their groups.
Array<Group> The groups the caller is in.
id REQUIRED
string The group's id. It stays the same when the group gets a new name.
name REQUIRED
string The group's name.
attributes REQUIRED
object Each attribute assigned to the group, by name, with the values the group holds for it.
followsRole
string | null For a role group, the role whose members it holds: Admin, Developer or Viewer. Its members follow the role, and nobody adds or removes them. Left out for a group an admin made.
directoryAvailable REQUIRED
boolean Whether this server has the PropelAuth directory that work on the whole organisation needs.

Request

Terminal window
curl -X GET "$KATER_API_URL/v1/me/access" \
  -H "Authorization: Bearer $KATER_API_TOKEN"

Response

{
  "organizationId": "string",
  "user": {
    "id": "string",
    "email": "string",
    "firstName": "string",
    "lastName": "string",
    "role": "string",
    "avatarColor": "string"
  },
  "permissions": [
    "string"
  ],
  "attributes": {},
  "groups": [
    {
      "id": "grp_1a2b3c4d",
      "name": "finance",
      "attributes": {
        "department": [
          "Finance"
        ]
      },
      "followsRole": "string"
    }
  ],
  "directoryAvailable": true
}

Find what the data team built

List the connections, then the workspaces, queries, dashboards and apps in each one.

GET
/v1/connection/list

List the connections

Lists the organisation's connections that the caller can read. A connection is one warehouse and the models that the data team built on it. Use a connection's name in every other request that takes connection or a namespace.

Request Parameters

limit
string Stop after this many visible connections. Minimum: 1. Maximum: 1000.

Response

Array<ConnectionListItem>
connection REQUIRED
string
label REQUIRED
string
warehouse_type
string | null
database_count
integer | null
schema_count
integer | null
Array<ConnectionDiagnostic> Why connection.yaml could not be read; the counts are absent when it is invalid.
code REQUIRED
string
message REQUIRED
string
severity
"error""warning""info""hint"
Default: "error".
Range | null Where in connection.yaml the problem is; absent when it isn't about one line.
Position
line REQUIRED
integer Minimum: 0.
character REQUIRED
integer Minimum: 0.
Position
line REQUIRED
integer Minimum: 0.
character REQUIRED
integer Minimum: 0.

Request

Terminal window
curl -X GET "$KATER_API_URL/v1/connection/list" \
  -H "Authorization: Bearer $KATER_API_TOKEN"

Response

{
  "connections": [
    {
      "connection": "string",
      "label": "string",
      "warehouse_type": "string",
      "database_count": 0,
      "schema_count": 0,
      "diagnostics": [
        {
          "code": "string",
          "message": "string",
          "severity": "error",
          "range": {
            "start": {
              "line": 0,
              "character": 0
            },
            "end": {
              "line": 0,
              "character": 0
            }
          }
        }
      ]
    }
  ]
}
GET
/v1/connection/read

Read one connection

Reads one connection's settings, as its file saves them, and whether the organisation stored a warehouse credential for it. A connection without a credential cannot run a query.

Request Parameters

connection REQUIRED
string

Response

Connection | null Absent when connection.yaml has an error; diagnostics say what to fix.
id REQUIRED
string Written once by kater admin connection create. Never change it.
name REQUIRED
string The connection's lower snake case name. It must match its folder under connections/.
SnowflakeWarehouseMetadata | DuckDBWarehouseMetadata The warehouse Kater connects to: `warehouse_type` names it, and the other keys are that warehouse's settings. Secrets stay out of this file.
warehouse_type REQUIRED
string The warehouse this connection is on. It decides which other keys `warehouse_metadata` takes.
auth_method REQUIRED
"username_password""key_pair"
Supported warehouse authentication methods.
snowflake_account_id REQUIRED
string Snowflake account identifier. The connection's stored credential signs in to this account; run kater admin connection test after changing it.
warehouse REQUIRED
string Snowflake warehouse that runs queries. The server's SNOWFLAKE_WAREHOUSE must match it; run kater admin connection test after changing it.
role REQUIRED
string Snowflake role that queries run as. The server's SNOWFLAKE_ROLE must match it; run kater admin connection test after changing it.
label
string | null Display name for people.
description
string | null Notes about this connection.
Array<ConnectionDatabase> Databases Kater reads. Run kater sync --resource-type db_dataset after changing it, and commit the result.
db__database REQUIRED
string The database's exact name in the warehouse. Run kater sync --resource-type db_dataset after changing it, and commit the result.
name REQUIRED
string Kater's lower snake case name for this database.
label
string | null Display name for people.
description
string | null Notes about this database.
timezone REQUIRED
string IANA timezone of the timestamps stored in this database, such as `UTC` or `America/Los_Angeles`. Kater records it but does not use it yet.
Array<ConnectionSchema> Schemas Kater reads from this database. Run kater sync --resource-type db_dataset after changing it, and commit the result.
db__schema REQUIRED
string The schema's exact name in the warehouse. Run kater sync --resource-type db_dataset after changing it, and commit the result.
name REQUIRED
string Kater's lower snake case name for this schema.
label
string | null Display name for people.
description
string | null Notes about this schema.
tables
Array<string> Only these tables are synced, by their exact names in the warehouse. Leave it empty to sync every table in the schema. A table's name, label and description live in its DB dataset file. Run kater sync --resource-type db_dataset after changing it, and commit the result.
exclude_tables
Array<string> Tables that are never synced. Run kater sync --resource-type db_dataset --prune after adding one.
query_timezone_conversion REQUIRED
string How query results should convert timestamps. Kater records it but does not use it yet; `do_not_convert` is the usual value.
query_timeout REQUIRED
integer Seconds a query should run before it is stopped. Kater records it but does not use it yet. More than 0.
path REQUIRED
string At most 4096 characters.
revision REQUIRED
string
WarehouseCredential | null Whether Kater holds a credential to query the connection's warehouse. A run on a connection whose `present` is false fails until an admin adds one in Settings. Null when connection.yaml has an error.
present REQUIRED
boolean Whether Kater holds a credential for the warehouse. Without one, every query on the connection fails.
Array<ConnectionDiagnostic>
code REQUIRED
string
message REQUIRED
string
severity
"error""warning""info""hint"
Default: "error".
Range | null Where in connection.yaml the problem is; absent when it isn't about one line.
Position
line REQUIRED
integer Minimum: 0.
character REQUIRED
integer Minimum: 0.
Position
line REQUIRED
integer Minimum: 0.
character REQUIRED
integer Minimum: 0.

Request

Terminal window
curl -X GET "$KATER_API_URL/v1/connection/read?connection=<connection>" \
  -H "Authorization: Bearer $KATER_API_TOKEN"

Response

{
  "connection": {
    "id": "string",
    "name": "string",
    "warehouse_metadata": {
      "warehouse_type": "string",
      "auth_method": "username_password",
      "snowflake_account_id": "string",
      "warehouse": "string",
      "role": "string"
    },
    "label": "string",
    "description": "string",
    "databases": [
      {
        "db__database": "string",
        "name": "string",
        "label": "string",
        "description": "string",
        "timezone": "string",
        "schemas": [
          {
            "db__schema": "string",
            "name": "string",
            "label": "string",
            "description": "string",
            "tables": [
              "string"
            ],
            "exclude_tables": [
              "string"
            ]
          }
        ]
      }
    ],
    "query_timezone_conversion": "string",
    "query_timeout": 0
  },
  "path": "string",
  "revision": "string",
  "warehouse_credential": {
    "present": true
  },
  "diagnostics": [
    {
      "code": "string",
      "message": "string",
      "severity": "error",
      "range": {
        "start": {
          "line": 0,
          "character": 0
        },
        "end": {
          "line": 0,
          "character": 0
        }
      }
    }
  ]
}
GET
/v1/workspace/browse

List the caller's workspaces in a connection, one page at a time

Lists the workspaces of one connection that the caller can open. show keeps the connection's own workspaces, the caller's own or the ones shared with the caller. Read the next page with the answer's nextCursor.

Request Parameters

connection REQUIRED
string
show
"all""mine""shared"
All, Mine, or Shared with me: the connection's own, its connection workspaces included, and what someone shared with the reader from their own folder. An admin's All also holds everyone else's. Default: "all".
q
string Searched on the server, through everything about each item. Every word must match. It also takes `key:value` filters, such as `type:field owner:me expression:SUM -tag:draft`. Default: "". At most 512 characters.
cursor
string The `nextCursor` of the page before. Leave it out for the first page.
limit
integer How many items a page holds. Default: 10. Minimum: 1. Maximum: 50.
writable
boolean Only workspaces the reader can change, as a destination needs. Default: false.
source
string Only workspaces over this shared model, by its name. At most 256 characters.

Response

Array<BrowsedWorkspace>
ownership REQUIRED
"mine""shared""others"
`mine` in the reader's own folder; `shared` the connection's own, such as a connection workspace, or someone else's that a grant gives the reader; `others` someone else's an admin reaches through their full access, which only All lists. Independent of verification.
owner REQUIRED
string | null The owner's email, for a personal item.
OwnerProfile | null The owner as the organisation's directory names them. Left out where the host reads no directory, or the directory does not know them.
name REQUIRED
string Their first and last names, or their email address when the directory has no name.
pictureUrl
string | null The address of their picture. Null when they have none.
id
string | null Their PropelAuth user id, which gives them their automatic avatar colour.
avatarColor
string | null The name of the colour they selected for their avatar, one of app-kit's `AVATAR_COLORS`. Null when they selected none.
openedAt REQUIRED
string | null When the reader last opened it. Null where the host keeps no activity.
pinnedAt REQUIRED
string | null When the reader pinned it. Null where the host keeps no activity.
changedAt REQUIRED
string | null When it last changed: its newest committed file where the host keeps history, else its newest file.
recentAt REQUIRED
string | null `openedAt`, else `changedAt`: what the list is ordered and grouped by.
path REQUIRED
string The workspace's complete path, which names it everywhere. At most 4096 characters.
name REQUIRED
string
label REQUIRED
string
description
string | null
canWrite REQUIRED
boolean Whether the reader can change it.
nextCursor REQUIRED
string | null Where the next page starts. Null when this page is the last.

Request

Terminal window
curl -X GET "$KATER_API_URL/v1/workspace/browse?connection=<connection>" \
  -H "Authorization: Bearer $KATER_API_TOKEN"

Response

{
  "items": [
    {
      "ownership": "mine",
      "owner": "string",
      "ownerProfile": {
        "name": "string",
        "pictureUrl": "string",
        "id": "string",
        "avatarColor": "string"
      },
      "openedAt": "string",
      "pinnedAt": "string",
      "changedAt": "string",
      "recentAt": "string",
      "path": "string",
      "name": "string",
      "label": "string",
      "description": "string",
      "canWrite": true
    }
  ],
  "nextCursor": "string"
}
POST
/v1/query/list

List the queries of a workspace

Lists the queries of one workspace, with the fields that each one shows, and the workspace's own filters and tiles. A query is named by its workspace's path and its own name. Read a query's rows with POST /v1/result/resolve or POST /v1/run.

Request Parameters

WorkspaceNamespace
kind
string Default: "workspace".
path REQUIRED
string

Response

Array<QueryTab>
QueryRelationKey
name REQUIRED
string
model_type
string Default: "query".
WorkspaceNamespace
kind
string Default: "workspace".
path REQUIRED
string
id REQUIRED
string
name REQUIRED
string
path REQUIRED
string At most 4096 characters.
ordinal REQUIRED
integer Minimum: 0.
label
string | null
QueryCopyOrigin | null
QueryRelationKey
name REQUIRED
string
model_type
string Default: "query".
WorkspaceNamespace
kind
string Default: "workspace".
path REQUIRED
string
path REQUIRED
string At most 1024 characters.
label
string | null At most 4096 characters.
revision REQUIRED
string
Range
Position
line REQUIRED
integer Minimum: 0.
character REQUIRED
integer Minimum: 0.
Position
line REQUIRED
integer Minimum: 0.
character REQUIRED
integer Minimum: 0.
charts
integer Default: 0. Minimum: 0.
empty
boolean Default: false.
sql_only
boolean Default: false.
diagnostics
Array<string>
workspace_revision
string | null
label
string | null
layer
string | null
filters
Array<string>
tiles
integer Default: 0. Minimum: 0.
reads_model
boolean Default: false.
moved_to
string | null At most 1024 characters.
renamed
object
moved
object

Request

Terminal window
curl -X POST "$KATER_API_URL/v1/query/list" \
  -H "Authorization: Bearer $KATER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "namespace": {
    "kind": "string",
    "path": "string"
  }
}'

Response

{
  "queries": [
    {
      "query": {
        "name": "string",
        "model_type": "string",
        "namespace": {
          "kind": "string",
          "path": "string"
        }
      },
      "id": "string",
      "name": "string",
      "path": "string",
      "ordinal": 0,
      "label": "string",
      "copied_from": {
        "query": {
          "name": "string",
          "model_type": "string",
          "namespace": {
            "kind": "string",
            "path": "string"
          }
        },
        "path": "string",
        "label": "string"
      },
      "revision": "string",
      "selection": {
        "start": {
          "line": 0,
          "character": 0
        },
        "end": {
          "line": 0,
          "character": 0
        }
      },
      "charts": 0,
      "empty": true,
      "sql_only": true
    }
  ],
  "diagnostics": [
    "string"
  ],
  "workspace_revision": "string",
  "label": "string",
  "layer": "string",
  "filters": [
    "string"
  ],
  "tiles": 0,
  "reads_model": true,
  "moved_to": "string",
  "renamed": {},
  "moved": {}
}
POST
/v1/dashboard/open
Beta

Open a workspace's dashboard

Reads a workspace's dashboard: its tiles, its filters and the queries and charts that the tiles show. It does not run the queries. Read their rows with POST /v1/result/resolve or POST /v1/run.

Request Parameters

WorkspaceNamespace
kind
string Default: "workspace".
path REQUIRED
string
include_inputs
boolean Compile workspace.sql for the answer's `inputs` and for the problems of `filters`. False answers without that compile, in a fraction of the time. Default: true.
scaffold
boolean True saves Kater's scaffold when the workspace has no dashboard.yaml and the caller can write it. By default the open only reads: a missing file answers with the scaffold, unsaved, and `scaffolded` is true. Default: false.

Response

WorkspaceNamespace
kind
string Default: "workspace".
path REQUIRED
string
path REQUIRED
string At most 4096 characters.
revision REQUIRED
string | null The saved file's revision. Absent when the file does not exist, which happens only for a reader who cannot write the workspace.
saved REQUIRED
boolean Whether dashboard.yaml exists on disk after this call.
scaffolded REQUIRED
boolean Whether the file was missing, so this dashboard is Kater's scaffold. It was saved only when the caller can write the workspace.
can_write REQUIRED
boolean
file REQUIRED
object | null dashboard.yaml as data, which the renderer edits for a drag or a resize and saves whole. Absent when the file is not a YAML mapping.
Array<DashboardProblem>
severity REQUIRED
"error""warning"
message REQUIRED
string
at
string | null Where in dashboard.yaml the problem is, such as `tiles[2].span`; absent when it is about the whole file.
code
"cards-cut-off" | "money-format" | "crowded-series" | "crowded-slices" | "window-title" | "no-legend" | null What a tile's check found, for a problem about how one tile reads: `cards-cut-off`, `money-format`, `crowded-series`, `crowded-slices`, `window-title` or `no-legend`. Absent for a problem with the file itself.
chart
string | null The saved chart of the tile the problem is about, by name. Absent for a problem with the file itself.
DashboardSpec The dashboard as the renderer draws it, built from dashboard.yaml, charts/ and workspace.sql on every open. It is never stored.
template REQUIRED
"contract""operations""realtime""transactions"
title REQUIRED
string
description
string | null
DashboardTile | null
chart
string | null The saved chart's name. Absent only for a text tile and an empty slot.
text
string | null A text tile's words in `tiles`, in Markdown. Each figure in them is a <kater-value> tag on a query of this workspace.
card
boolean A text tile drawn on a card, as a chart tile is. Otherwise its words draw as plain words on the page. Default: false.
empty
boolean An empty slot in `tiles`: a place and a size with no chart yet, which a person fills from the dashboard's chart list. Default: false.
region REQUIRED
"kpis" | "figures" | "primary" | "hero" | "aside" | "ledger" | "tiles" | "rail" | string
position REQUIRED
integer The tile's index in its region's list in dashboard.yaml. Minimum: 0.
tab
string | null
section
string | null The declared section the tile sits in, by name. Absent for a tile in no section.
x
integer | null The column a tile in `tiles` starts at, 0 at the board's left edge. Absent when the file leaves it out: the tile follows the one before it, or starts a row when there is no room. Minimum: 0. Maximum: 11.
span
integer | null How many of the board's 12 columns a tile in `tiles` takes. In another region, whose place the template fixes, the span it takes when moved into `tiles`; absent for a chart that can't be read. Minimum: 1. Maximum: 12.
height
integer | null The tile's outer height in pixels, in 16px steps, from 160 for a chart and from 48 for a text tile, which draws taller when its words need more. In another region, the height it takes when moved into `tiles`; absent for a chart that can't be read. Minimum: 48. Maximum: 960.
sizes_to_content
boolean The chart's kind sizes to its content, such as a band of figures or a list. Outside `tiles` it takes the height its content needs rather than `height`. Default: false.
kind
string | null
label
string | null
available REQUIRED
boolean
problem
string | null Why an unavailable tile cannot draw, naming what is missing.
DashboardChart | null
path REQUIRED
string At most 4096 characters.
revision REQUIRED
string
spec REQUIRED
object
sql REQUIRED
string
formats
object Each output the chart gives its own `@format`, by its name. A tile shows it over its query's format.
Array<DashboardTakeaway>
position REQUIRED
integer Minimum: 0.
insight REQUIRED
string
query REQUIRED
string
columns REQUIRED
object
parameters
object
label
string | null The insight template's own label.
available REQUIRED
boolean
problem
string | null
Array<HiddenTakeaway> Kater's takeaways removed for everyone, by template and query.
insight REQUIRED
string
query REQUIRED
string
Array<DashboardTab>
name REQUIRED
string
label REQUIRED
string
index REQUIRED
integer Minimum: 0.
Array<DashboardSection> The declared sections in `index` order. Empty when the file declares none.
name REQUIRED
string
label REQUIRED
string
index REQUIRED
integer Minimum: 0.
regions REQUIRED
object The template's regions in the order it draws them, each tile in file order.
single_tile_regions
Array<"kpis" | "figures" | "primary" | "hero" | "aside" | "ledger" | "tiles" | "rail"> The template's regions that hold one tile, or one per tab.
full_width
boolean Whether the dashboard takes the full width of its pane, or keeps a readable width, centred. Default: true.
filters
Array<string> The workspace's optional filters the dashboard opens with switched on, by name, for a reader who hasn't set their own. A filter's default gives its value and never switches it on.
theme
string The theme the dashboard draws in, as dashboard.yaml names it: a Kater preset, a data team's theme as `team:<id>`, or a mapping of the theme it builds on (`preset`) and the tokens it changes (`overrides`). Absent: the Kater theme.
rail_width
"narrow" | "wide" | null
sticky_rail
boolean | null
refresh_seconds
integer | null
ContractInput | null The filters and parameters workspace.sql declares, in the order it declares them.
Array<ContractParameter>
Parameter One reusable, provenance-aware semantic parameter declaration.
name REQUIRED
string The parameter's lower snake case name, as the SQL reads it.
default_value
any | null The value used when none is given. It never switches a filter on.
label
string | null The name people see on the input.
description
string | null What the input is for, for the people who set it.
ai_context
string | null Guidance for an assistant that sets this input.
kater_data_type
SemanticDataType | null The value's type: string, number, boolean, date, time or timestamp.
subtype
ParameterSubtype | null How many values it takes: single_value for one, range for two ordered endpoints, multiselect for several, or records for rows of fields.
relative
boolean Whether it also takes a period, such as the last 30 days. Only on a date, time or timestamp. Default: false.
ParameterAllowedValues | null The choices: a list written out, or a field whose values supply them.
from_field
ParameterAllowedValuesFromField | null A field whose values are the choices.
from_list
Array<any> | null The choices, written out: values of one type, each once.
ParameterBound | null The smallest value it takes, inclusive: written out, or a field's lowest value.
from_value
any | null The bound, written out: a number, or an ISO date, time or timestamp.
from_field
ParameterBoundFromField | null A field whose lowest or highest value is the bound.
ParameterBound | null The largest value it takes, inclusive: written out, or a field's highest value.
from_value
any | null The bound, written out: a number, or an ISO date, time or timestamp.
from_field
ParameterBoundFromField | null A field whose lowest or highest value is the bound.
Array<Parameter> | null A records parameter's columns, each a typed single_value parameter.
name REQUIRED
string The parameter's lower snake case name, as the SQL reads it.
default_value
any | null The value used when none is given. It never switches a filter on.
label
string | null The name people see on the input.
description
string | null What the input is for, for the people who set it.
ai_context
string | null Guidance for an assistant that sets this input.
kater_data_type
SemanticDataType | null The value's type: string, number, boolean, date, time or timestamp.
subtype
ParameterSubtype | null How many values it takes: single_value for one, range for two ordered endpoints, multiselect for several, or records for rows of fields.
relative
boolean Whether it also takes a period, such as the last 30 days. Only on a date, time or timestamp. Default: false.
allowed_values
ParameterAllowedValues | null The choices: a list written out, or a field whose values supply them.
min
ParameterBound | null The smallest value it takes, inclusive: written out, or a field's lowest value.
max
ParameterBound | null The largest value it takes, inclusive: written out, or a field's highest value.
fields
Array<Parameter> | null A records parameter's columns, each a typed single_value parameter.
position REQUIRED
integer
db_data_type REQUIRED
string
encoding REQUIRED
"scalar""json_array"
required
boolean Default: true.
control
string Default: "".
Array<ContractFilter>
name REQUIRED
string
label
string | null
description
string | null
ai_context
string | null
required REQUIRED
boolean
activation_position
integer | null
parameters REQUIRED
Array<string>
Array<ContractFilterOwner>
name REQUIRED
string
model_type REQUIRED
"db_dataset""kater_dataset""workspace""semantic""query""chart""test""scratch""local"
Kater adds values to this list as it adds kinds. In an answer, treat a value you do not know as a kind you cannot show yet.
charts
Array<string> Every saved chart in the workspace, in Explorer order, whether or not it is a tile.
Array<DashboardSavedChart> Every readable saved chart in Explorer order, with its kind and query, whether or not it is a tile.
chart REQUIRED
string
label
string | null
kind REQUIRED
string
path REQUIRED
string At most 4096 characters.
query REQUIRED
string The query the chart reads, by its name in this workspace.
query_label
string | null
spec
object | null The chart's spec, for a chart no tile draws: a tile carries the spec of its own. A fill that puts the chart on reads its counts with it, as it does a tile's.
Array<DashboardQuery> Every query in the workspace in Explorer order, whether or not it has a saved chart.
query REQUIRED
string The query's name in this workspace.
label
string | null
path REQUIRED
string At most 4096 characters.
id
string | null The query's relation id, which a `run` of it names its `inputs` by, as a figure in a text tile reads it.
DashboardWorkspaceModel | null
path REQUIRED
string At most 4096 characters.
name REQUIRED
string
revision REQUIRED
string

Request

Terminal window
curl -X POST "$KATER_API_URL/v1/dashboard/open" \
  -H "Authorization: Bearer $KATER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "namespace": {
    "kind": "string",
    "path": "string"
  },
  "include_inputs": true,
  "scaffold": true
}'

Response

{
  "namespace": {
    "kind": "string",
    "path": "string"
  },
  "path": "string",
  "revision": "string",
  "saved": true,
  "scaffolded": true,
  "can_write": true,
  "file": {},
  "problems": [
    {
      "severity": "error",
      "message": "string",
      "at": "string",
      "code": "cards-cut-off",
      "chart": "string"
    }
  ],
  "dashboard": {
    "template": "contract",
    "title": "string",
    "description": "string",
    "headline": {
      "chart": "string",
      "text": "string",
      "card": true,
      "empty": true,
      "region": "kpis",
      "position": 0,
      "tab": "string",
      "section": "string",
      "x": 0,
      "span": 0,
      "height": 0,
      "sizes_to_content": true,
      "kind": "string",
      "label": "string",
      "available": true,
      "problem": "string",
      "definition": {
        "path": "string",
        "revision": "string",
        "spec": {},
        "sql": "string",
        "formats": {}
      }
    },
    "takeaways": [
      {
        "position": 0,
        "insight": "string",
        "query": "string",
        "columns": {},
        "parameters": {},
        "label": "string",
        "available": true,
        "problem": "string"
      }
    ],
    "hidden_takeaways": [
      {
        "insight": "string",
        "query": "string"
      }
    ],
    "tabs": [
      {
        "name": "string",
        "label": "string",
        "index": 0
      }
    ],
    "sections": [
      {
        "name": "string",
        "label": "string",
        "index": 0
      }
    ],
    "regions": {},
    "single_tile_regions": [
      "kpis"
    ],
    "full_width": true,
    "filters": [
      "string"
    ],
    "theme": "string",
    "rail_width": "narrow",
    "sticky_rail": true,
    "refresh_seconds": 0
  },
  "inputs": {
    "parameters": [
      {
        "definition": {
          "name": "string",
          "default_value": null,
          "label": "string",
          "description": "string",
          "ai_context": "string",
          "kater_data_type": "string",
          "subtype": "single_value",
          "relative": true,
          "allowed_values": {
            "from_field": {
              "ref": "string",
              "limit": 0
            },
            "from_list": [
              null
            ]
          },
          "min": {
            "from_value": null,
            "from_field": {
              "ref": "string"
            }
          },
          "max": {
            "from_value": null,
            "from_field": {
              "ref": "string"
            }
          },
          "fields": [
            {
              "name": "string",
              "default_value": null,
              "label": "string",
              "description": "string",
              "ai_context": "string",
              "kater_data_type": "string",
              "subtype": "single_value",
              "relative": true,
              "allowed_values": {
                "from_field": {
                  "ref": "string",
                  "limit": 0
                },
                "from_list": [
                  null
                ]
              },
              "min": {
                "from_value": null,
                "from_field": {
                  "ref": "string"
                }
              },
              "max": {
                "from_value": null,
                "from_field": {
                  "ref": "string"
                }
              },
              "fields": [
                {
                  "name": "string",
                  "default_value": null,
                  "label": "string",
                  "description": "string",
                  "ai_context": "string",
                  "kater_data_type": "string",
                  "subtype": "single_value",
                  "relative": true,
                  "allowed_values": {
                    "from_field": {
                      "ref": null,
                      "limit": null
                    },
                    "from_list": [
                      null
                    ]
                  },
                  "min": {
                    "from_value": null,
                    "from_field": {
                      "ref": null
                    }
                  },
                  "max": {
                    "from_value": null,
                    "from_field": {
                      "ref": null
                    }
                  },
                  "fields": [
                    {
                      "name": null,
                      "default_value": null,
                      "label": null,
                      "description": null,
                      "ai_context": null,
                      "kater_data_type": null,
                      "subtype": null,
                      "relative": null,
                      "allowed_values": null,
                      "min": null,
                      "max": null,
                      "fields": null
                    }
                  ]
                }
              ]
            }
          ]
        },
        "position": 0,
        "db_data_type": "string",
        "encoding": "scalar",
        "required": true,
        "control": "string"
      }
    ],
    "filters": [
      {
        "name": "string",
        "label": "string",
        "description": "string",
        "ai_context": "string",
        "required": true,
        "activation_position": 0,
        "parameters": [
          "string"
        ],
        "owners": [
          {
            "name": "string",
            "model_type": "db_dataset"
          }
        ]
      }
    ]
  },
  "charts": [
    "string"
  ],
  "saved_charts": [
    {
      "chart": "string",
      "label": "string",
      "kind": "string",
      "path": "string",
      "query": "string",
      "query_label": "string",
      "spec": {}
    }
  ],
  "queries": [
    {
      "query": "string",
      "label": "string",
      "path": "string",
      "id": "string"
    }
  ],
  "workspace_model": {
    "path": "string",
    "name": "string",
    "revision": "string"
  }
}

Read the numbers

Read a query’s rows from the result Kater keeps, or run it when no result is kept.

What a metric means

Search the catalog, and explain how a field gets its value.

Keep definitions in step

Read and save the files that define the models, compile them, and sync them with the warehouse.

What people asked

Read the questions people asked Kater, each conversation, and the logs.