Docs › Reference

The HTTP API

Every endpoint the browser calls, grouped by the screen that calls it — with its parameters, what it answers and the permission it needs.

Everything the browser client does, it does through this API. There is no second surface: static/app.js is a static file that talks to the endpoints below, which means every screen can be rebuilt from this document, and every endpoint a screen uses is documented under that screen.

210 endpoints: 95 GET, 64 POST, 25 PUT, 5 PATCH, 21 DELETE. All of them appear below. The ones no screen calls are under Not called by any screen at the end; they are integration and administrative endpoints and matter to an integrator.

How authentication works

The session cookie

SESSION_COOKIE = "krisid_session". SESSION_HOURS = 12, and it is an idle timeout: every request that lands slides the expiry forward twelve hours (_read_session).

A session is created in exactly three places, and each one sets the cookie on the response:

new_session inserts a user_session row holding the SHA of the token, the user id, expires_at = now + 12 hours and the first 200 characters of the User-Agent. The token itself is never stored.

The cookie is set by _cookie:

Set-Cookie: krisid_session=<token>; HttpOnly; SameSite=Lax; Path=/;
            Max-Age=43200[; Secure]

Secure is added only when request.url.scheme == "https", because the product runs on http://localhost on a laptop and a Secure cookie there is a cookie the browser drops.

DELETE /api/session sets revoked_at = now on the row and clears the cookie with delete_cookie(SESSION_COOKIE, path="/").

What a 401 looks like

The middleware (session_middleware) reads the cookie, resolves the session, and for any path under /api/ that is not open returns:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"detail": "Your session has ended. Sign in again to carry on."}

_actor raises the same sentence as a 401 if it is somehow reached without a session.

Sign-in failure is a different 401 and is deliberately vague about which half was wrong: {"detail": "That username and password do not go together."}. After 8 consecutive failures within 15 minutes it becomes 429 — "Too many attempts. Wait fifteen minutes, or ask for a new invite link.".

One exception, and it is narrow: if the password given matches a sign-up that is still waiting for its email to be confirmed, the answer is a 403 naming that address and telling the person to follow the link. The vagueness exists so that nobody can discover who works here; somebody who has proved the password already knows, so there is nothing left to protect. A wrong password and an unknown address get the vague sentence either way, and the lookup costs one scrypt whichever way it goes so the clock says nothing either. See POST /api/session.

What needs no session

_is_open(path, method) is the whole list, and it is exact paths and exact methods rather than prefixes:

Note the deliberate care: /api/signup-settings begins with the same eleven characters as /api/signup and is an administrator endpoint, so the check is path == "/api/signup" and not startswith.

The X-Actor header — honoured nowhere

108 endpoints still declare x_actor: str | None = Header(default=None). It is ignored, deliberately and permanently. _actor(cur, name=None) takes the name argument and never looks at it:

name is the X-Actor header that 108 endpoints still declare. It is ignored, deliberately and permanently: the header was how this worked before there was a login, and leaving it live would mean the login was decoration. verify sends one and proves it changes nothing.

Who you are comes from CURRENT — a contextvars.ContextVar the middleware sets from the session cookie . A ContextVar rather than a global, because one process serves many requests and a global would hand one person's session to the next person's request.

There is exactly one other way in, and it is named rather than hidden: the lineage intake key, sent as Authorization: Bearer <key> to POST /api/lineage/openlineage. It identifies one connection, can do one thing (append an event to that connection's inbox), creates no session, is never seen by _actor, and can read nothing at all — including the events it has itself sent.

Viewing as somebody else

POST /api/session/view-as sets viewing_as_id on the session row. While it is set:

• every read answers as that person — _actor and _whoever return them ;
• every write is refused by the middleware, before any endpoint sees it, with 403 and {"detail": "You are viewing the repository as <Name>, which shows you what they see and changes nothing. Stop viewing as them to make this change as yourself."} The only exceptions are /api/session/view-as itself and /api/session.

That is enforced in the middleware rather than per endpoint on purpose, so a new endpoint is safe the day it is written.

Maintenance

While maintenance is on , every API path except /api/maintenance, /api/health, /api/licence, /api/brand, /api/brand/logo and /api/session answers:

HTTP/1.1 503 Service Unavailable

{"detail": "<the message, or 'KRISID is being worked on.'>",
 "maintenance": true, "back_at": "<iso|null>", "contact": "<email|null>"}

Whoever holds ACCESS_MANAGE passes straight through, which is how it gets switched off again (_may_pass_maintenance). The client watches for body.maintenance on any refusal and replaces the screen .

Licensing

Checked per request, because the hostname is a property of the request. If the licence names other hosts and on_mismatch is refuse, every /api/ path except /api/licence answers 451 with {"detail": "<why>", "licence": "wrong_host"}. If on_mismatch is read_only, only non-GET/HEAD/OPTIONS methods get the 451.

Conventions

How errors are shaped

Two shapes, because two things refuse.

FastAPI's HTTPException — every deliberate refusal in app.py:

{"detail": "A sentence written to be read."}

The application's own not-ready answer — NotReady, raised when the database is unreachable, empty, or on the wrong schema version:

{"error": "The database is on schema v83; this build expects v91.",
 "remedy": "Run:  bash run.sh upgrade   — it applies what is missing and keeps everything in the repository."}

Status 503. The client reads both keys, in that order (body.error || body.detail), and keeps remedy to show beside the message.

Database refusals are passed through rather than reworded, from every route. The mapping is an exception handler registered for everything psycopg raises, not a block each endpoint has to wrap itself in — it was a block, wrapped at 27 of the 91 routes that write, and a trigger firing from one of the other 64 came back as 500 Internal Server Error with its sentence left on the server. _refusals maps them:

Two writers meeting is not an outage. DeadlockDetected, SerializationFailure, QueryCanceled and LockNotAvailable are all psycopg.OperationalError, which is also what an unreachable database raises — so a collision used to be answered with "Cannot reach Postgres: deadlock detected. Is it running? Try: brew services start postgresql@16", wrong about the cause and about the cure. They are separate branches now, above the one about the connection:

Both mean nothing was written — not part of it — so a client may retry the same request as it stands. Each is recorded in the System log with its Postgres error class by name, so the four are distinguishable without parsing prose.

A bug in this build answers 500, and says which bug

An unhandled exception used to answer with FastAPI's four default words and put its traceback on the server's terminal. It now carries the exception's class and a reference:

{"detail": "Something in this build went wrong handling that request
            (KeyError), so nothing was written. Reference 3ce9a093 — the
            System tab of the Logs screen has it, with the full trace in the
            application log.",
 "reference": "3ce9a093",
 "fault": "KeyError"}

The same reference appears on a trouble line in the System log, carrying the exception's message, and above the traceback in the application log. The message is deliberately not in the answer: a message can carry data, a class name cannot. nothing was written is a fact rather than a reassurance — every write is inside db(), whose connection rolls back when an exception leaves it.

Refusals name the permission and the roles that carry it

Every permission check goes through _may(cur, who, perm, asset_id, doing, what=None). It asks the database function may(username, permission, asset_id), and on a no it asks roles_granting(permission) and builds the sentence:

403 {"detail": "Rohan Iyer may not edit \"CUSTOMERS\". That needs ASSET_EDIT.
                It comes with Steward, Metadata Manager or Sysadmin.
                A role held over a data domain reaches everything the domain
                owns, so the fix is usually one assignment further up, not one
                per asset."}

The shape is: {display_name} may not {doing}[ "{what}"]. That needs {PERM}. then " It comes with A, B or C." (or " It comes with A.", or nothing if no role carries it), then always the sentence about domains.

_may is skipped entirely while a workflow is applying something it approved (_AUTHORITY.on). Database and metamodel refusals still fire — this skips who may ask, never what may be true.

_may_bool(cur, who, perm) answers the same question without the refusal, for a screen deciding what to offer. A hidden button is not a permission check: the endpoint always asks again.

Two endpoints use a different gate:

• _admin(cur, doing) is _may(..., "ACCESS_MANAGE", None, doing).
• _logs_or_refuse(cur) allows either LOG_VIEW or being named on the Logs screen, and says so in the refusal.

The per-request SQL breakdown is the one place that asymmetry matters: it asks for LOG_VIEW and nothing else. Being named as a reader of the logs lets somebody see what this installation did; it does not let them read the shape of the build.

What a read needs

Three rules apply to every endpoint at once, in the middleware, rather than to a hundred of them one at a time: no session no API, a session that is viewing as somebody may not write, and — since v91 — what a read needs.

Asked with may_anywhere(username, permission) and not may(username, permission, NULL): reading is all or nothing here, and most people's roles sit on a data domain rather than on the repository. Holding one of these over anything at all counts everywhere; a catalogue that quietly omitted the rows somebody may not see would be a worse answer than a refusal.

The refusal is shaped like every other one:

403 {"detail": "Holds Nothing may not read this. That needs ASSET_VIEW.
                It comes with Viewer, Data Steward or Sysadmin.
                A role held over anything at all carries it: reading is not
                restricted asset by asset."}

Everything else is either gated inside the endpoint, because the endpoint knows which of several answers it is giving — SOURCE_VIEW opens one source while the list of sources is everybody's — or open to anybody signed in, each for a stated reason. app.py holds all three lists (READ_NEEDS, GATED_INSIDE, OPEN_READS), and verify asserts that every GET under /api is in exactly one of them: an endpoint written tomorrow fails the check until somebody decides which it is.

What stays open, and why:

• The access model. Who exists, what the roles are and who holds them is how somebody finds who to ask. Usernames and email addresses need PERSON_IDENTIFY; the access workbook — the whole model in one file, and the shape an upload is read from — needs ACCESS_VIEW as well.
• The list of sources, and where this repository can call out to.
• Your own session, details and notifications; the manual; the brand, the licence and the maintenance state, which have to answer before anybody is anybody.

What a uid is

A uid is a UUID — the asset's public identity. _resolve(cur, uid) is the only place the public uuid and the internal bigint meet:

if not UUID_RE.match(str(uid)):
    raise HTTPException(404, f"'{uid}' is not an asset id")
cur.execute("SELECT id FROM asset WHERE uid = %s", (uid,))
row = cur.fetchone
if not row:
    raise HTTPException(404, "no asset with that id")

UUID_RE is the strict 8-4-4-4-12 hex form, case-insensitive.

{uid} does NOT accept an external key. _resolve matches asset.uid only, and a non-UUID string is a 404 with "'<x>' is not an asset id" rather than a 500. This is stated here because it is a reasonable thing to assume and it is not true: external keys are matched only inside the bulk loader (bulk_plan) and the SQL-lineage resolver (_find_asset), never by a path parameter.

Other {...} path parameters are not asset uids:

How paging is signalled

There are three shapes, and which one an endpoint uses is stated per endpoint.

has_more + next_offset — /api/logs, /api/assets/{uid}/history. The handler asks for limit + 1 rows, sets has_more = len(rows) > limit, trims to limit, and returns next_offset = offset + limit.

more — /api/access/inheritance. more = len(rows) == limit, which can be a false positive on an exact multiple; the handler says so by construction rather than paying for a count.

paged + after + limit + line_counts + lines_total — /api/runs/harvest/{uid}?full=1.

Several endpoints cap instead of paging, and say so:

Asking where a request's seconds went

Any /api/ request may ask the application to time its own statements, and the answer comes back on a header. It is how a slow screen says what is slow about it, and it is what run.sh timing asks for automatically on any screen it has just measured above half a second.

Send x-krisid-sql: 1. Get back the same header, holding JSON:

The SQL is trimmed to 140 characters a statement. If statements is larger than the length of slowest, the total not adding up is itself the signal: a statement run many times shows up as the gap rather than as a line.

Send x-krisid-sql: plan and any statement over 250 milliseconds also comes back with its EXPLAIN (ANALYZE, BUFFERS) — real row counts, not estimates. At most three plans in one answer, 2200 characters each; the whole plan also goes to the application log. plan:40 sets the threshold in milliseconds instead, which is how you ask for the plan of everything on a page without a different build.

Four things worth knowing before building anything on it:

• It needs LOG_VIEW — the permission that opens the Logs screen. Note that this is the permission ONLY: unlike the Logs screen itself, being named as a reader there does not buy it, because this is about the shape of the build rather than about the contents of a log.
• A refusal does not change the answer. Asking without the permission serves the request exactly as it would have been served and adds x-krisid-sql-refused: LOG_VIEW (or sign in first with no session). A client that saw only a missing header could not tell "you may not" from "this build is older than the feature".
• It carries no data from the repository. Parameters travel separately from statements, so what is recorded is the SQL this build contains and never a value out of your data. That is also why the header is always ASCII.
• Nothing is timed unless asked. A request that does not send the header pays one context-variable read per statement, and gets no header back.

A statement that FAILED is reported too, with the time it took before it raised — a query that runs for four seconds and then errors is the one most worth seeing.

Only reads are ever explained: EXPLAIN ANALYZE runs the statement, so a write explained would be a write done twice. The rule is deliberately unclever — the statement must begin with SELECT or WITH and must not contain the words INSERT, UPDATE, DELETE, MERGE or TRUNCATE anywhere — because WITH gone AS (DELETE … RETURNING id) SELECT * FROM gone is a SELECT by its first word.

Anything else consistent across the surface

• Everything is JSON except the file downloads, which answer application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (xlsx), text/csv; charset=utf-8 (CSV, always with a UTF-8 BOM so Excel does not read it as Latin-1), application/json with a Content-Disposition (workflow export), or an image media type (the brand logo).
• Writes take a JSON body and the client always sends content-type: application/json. File uploads take multipart/form-data with a field called file.
• One field per call. Almost every edit endpoint changes one thing, because each save is its own line in History naming the field and both values. The exceptions are the deliberately whole-list writes below.
• Whole lists, not deltas. PUT /api/logs/viewers, PUT /api/working-days, PUT /api/usage/networks, PUT /api/connectors/availability, PUT /api/lineage-views/{uid} (shares) and PUT /api/workflows/{uid} (the canvas) each replace their whole list. The reason is always the same: what somebody decides is "this is the shape of it", and saving it a row at a time leaves a half-applied policy behind whenever something in the middle is refused.
• 202 Accepted means a write became a proposal rather than a change. Body: {"proposed": true, "request": "<uid>", "detail": "…"}.
• 204 is never returned; the client handles it anyway.
• Workbooks are download → preview → apply. GET …/export hands you the current state, POST …/preview says what a file would do and writes nothing, POST …/apply recomputes the plan against live state and commits only if safe. Three screens share one client panel (uploadPanel) pointed at /api/metamodel, /api/bulk and /api/access.
• A plan's shape, returned by every preview and apply (p.as_dict): {"safe": bool, "empty": bool, "blockers": [str], "warnings": [str], "added": [{"key","kind","detail"}], "changed": [{"key","field","was","now"}], "removed": [{"key","kind","blocking","dependents"}]} plus filename, and applied on an apply.
• Derived answers are cached on the change log. _derived(cur, key, build, ttl, stamped) rebuilds once per repository change rather than once per request, with exactly one caller building and the rest waiting. Applies to /api/metamodel, /api/stats, /api/tree, /api/semantic/model, /api/semantic/yaml, /api/ask/home and /api/search/status.
• A field somebody may not read is ABSENT, not null. PERSON_IDENTIFY takes username and email out of GET /api/access and GET /api/users/{uid} for everybody but the reader themselves, and it takes the KEYS out rather than emptying them: on that screen an empty email already means "nobody has recorded one" next to an editable field and an Invite button, so a null would have been a statement, and a false one. Both payloads also carry a boolean (may_identify, identity_shown) so a client can tell not served to you from not recorded. Where redacting a payload would make it dangerous rather than merely poorer — the access workbook, which is keyed on the usernames — the endpoint refuses with 403 instead.
• Proposed assets are invisible. asset.proposed_by IS NOT NULL means an asset exists only for whoever proposed it, whoever may decide on it, and whoever manages access (_may_see_proposal). Every list query carries a.proposed_by IS NULL; GET /api/assets/{uid} answers 404 "no such asset" to anybody else, which is true for them.

The permission codes used below

ACCESS_MANAGE, ASSET_BULK_LOAD, ASSET_CREATE, ASSET_DELETE, ASSET_EDIT, ASSET_VIEW, CONNECTION_MANAGE, CONNECTOR_ALLOW, HARVEST_RUN, HARVESTED_DELETE, LOG_VIEW, METAMODEL_MANAGE, METAMODEL_VIEW, PERSON_IDENTIFY, RELATION_MANAGE, RESPONSIBILITY_ASSIGN, SEMANTIC_EDIT, SOURCE_VIEW, TAG_PUSH, USAGE_MANAGE, USAGE_VIEW, VIEW_AS, VIEW_CREATE, VIEW_SHARE, WORKFLOW_BYPASS_LOAD, WORKFLOW_DESIGN, WORKFLOW_RAISE, WORKFLOW_VIEW.

Which roles carry which is data, not code — it is the access workbook — so the refusal reads it at the moment of refusing.

LOG_VIEW buys two things rather than one: the Logs screen, and the right to ask a request where its seconds went (above). PERSON_IDENTIFY buys two as well: other people's username and email address on People and Persona, and the access workbook — which since v91 needs ACCESS_VIEW beside it.

Each permission also carries how far a holding of it reaches, which the People and Persona grid shows beside its name and GET /api/access returns as scope:

verify asserts the column against how the application actually asks, so a label cannot drift away from the behaviour.

Index: all 210 endpoints

The lookup table. "Screen" is the screen that calls it; "—" means no screen does. "Permission" is what the handler actually checks — session means a live session and nothing more, open means no session at all.

There is no /api/overview: the Overview screen is drawn from /api/stats.

Every screen's calls

Each page below is one screen of KRISID and every endpoint it calls, in the order it calls them.

• Signing in and the frame
• The invite and sign-up screens
• Ask and search
• Browsing: overview, roll-up, estate, layers, type lists
• One asset
• Lineage and the explorer
• The metamodel
• People, teams, roles and access
• Workflows, requests and change sets
• Sources, connections and harvesting
• The semantic layer
• Bulk load and exports
• Administration
• The help centre
• Not called by any screen