API overview

SeeKi exposes a small HTTP API that backs its own grid. It is stable, read-only, and designed for direct consumption from any HTTP client. Everything the web UI does is a request you can make yourself.

Base URL

SeeKi binds to 127.0.0.1:3141 by default. All API routes are served under the /api prefix.

http://127.0.0.1:3141/api

The host and port come from the server.host and server.port fields in config.toml, or from the SEEKI_BIND environment variable. The API is reachable from the same machine only unless you deliberately change the bind address.

Endpoints at a glance

Method	Path	Purpose
`GET`	`/api/status`	Report whether the server is in normal or setup mode.
`GET`	`/api/tables`	List the tables the user is allowed to see. Details.
`GET`	`/api/tables/{table}/columns`	Column metadata for one table. Details.
`GET`	`/api/tables/{table}/rows`	Paginated rows with optional sort, search, and filters. Details.
`GET`	`/api/config/display`	Branding + display-name overrides for all allowed tables and columns.
`GET`	`/api/export/{table}/csv`	Stream all matching rows for a table as CSV.
`POST`	`/api/setup/test-connection`	Used by the setup wizard. See note below.
`POST`	`/api/setup/save`	Used by the setup wizard. See note below.

Response shape

Successful responses are JSON objects whose top-level keys name the payload — tables, columns, rows, and so on. There is no generic envelope and no data wrapper.

{
  "tables": [
    { "name": "vehicles_log", "display_name": "Fleet Log", "row_count_estimate": 523401 }
  ]
}

The rows endpoint is richer — it returns columns, rows, total_rows, page, and page_size together so the grid can render without a second round-trip.

Error shape

Errors are JSON objects with a single error field and an appropriate HTTP status code.

{ "error": "Table 'vehicles_log' not found" }

Status	Meaning
`400 Bad Request`	An invalid or unknown column was passed to `sort_column` or a `filter.*` parameter; or the database type does not support the requested operation.
`404 Not Found`	The table does not exist, or is not in the configured allow-list.
`503 Service Unavailable`	The server is still in setup mode and the endpoint is only available after a database is configured.
`500 Internal Server Error`	An unexpected failure. The message is always the literal string `"Internal server error"` — detail is written to the server log, not the response.

Authentication

No authentication

SeeKi has no login, no tokens, and no session layer. It listens on localhost and trusts the operating-system boundary around it. Anyone who can reach the bind address can read everything the configured database user can read. If you expose SeeKi beyond localhost, put it behind your own authentication proxy.

Read-only guarantee

Every query SeeKi issues is a SELECT. There is no endpoint that accepts row edits, schema changes, or raw SQL. Column and filter names are validated against the live schema before interpolation, and all user values are bound as parameters.

The one exception is the setup wizard, which writes config.toml on disk — never to the database.

Setup-mode endpoints

The two /api/setup/* routes exist only to power the first-run setup wizard. They accept a candidate connection URL (and optional SSH tunnel config) and write the resulting configuration to config.toml. They are documented here for completeness but are not intended as a general integration surface — once the server enters normal mode, the data endpoints above are the supported interface.

Try it

curl http://127.0.0.1:3141/api/status
curl http://127.0.0.1:3141/api/tables
curl "http://127.0.0.1:3141/api/tables/vehicles_log/rows?page=1&page_size=10"