Every InventDB instance serves this HTTP API directly — SQL, record CRUD, pre-built queries, bulk writes, vector search, index management, the relationship graph, the workflows engine and per-record attachments. Every example below is copy-paste and fully working against a real property-management dataset (the pms namespace). Your instance also serves an interactive version at /api/docs (Scalar) and /api/docs/swagger (try-it-out), plus the raw spec at /api/openapi.json.
Base URL: https://<slug>.sandbox.inventdb.comAuth: Authorization: Bearer <JWT>Get a token: POST /api/auth/loginOpenAPI 3.1: /api/openapi.json
Product family.SOAR (AI Platform) = Serverless plus the AI/LLM endpoints (SOAR only). Serverless serves everything except those. Each instance’s own /api/openapi.json is filtered to its tier.
Authentication
Session and credential endpoints for InventDB. Exchange a username and password for a JWT via login, then send that token as Authorization: Bearer <token> on every protected request. get_current_user resolves the caller's identity and role (globally or per-app), change_password rotates the caller's own credential, forgot_password kicks off an out-of-band reset, and auth_health reports whether auth enforcement is on for the instance.
POST/api/auth/loginpublicSOAR + Serverless
Exchanges a username and password for a signed JWT. Use the returned token as Authorization: Bearer <token> on every subsequent protected call, and read user for the caller's id, global role, and email. On bad credentials the endpoint returns 401 with ok:false and an error message (token is null). This is the entry point for every API session; no token is required to call it.
Returns the identity behind the bearer token: id, username, role, email, and active flag. Without ?app= the role field is the user's global role from _system.users. Pass ?app=<software_id> (for example ?app=pms) to get the per-app role from app_roles[<id>] instead — though a global superadmin/admin always wins (RBAC bypass). A missing or expired token yields 401.
Path & query parameters
Name
In
Type
Description
app
query
string
Optional app/software id, e.g. pms. When set, role is the per-app role and globalRole carries the raw global role. Empty role means the user is not provisioned for that app.
Rotates the password of the currently authenticated user. Supply the current_password for verification and the desired new_password; both fields are snake_case. On success the endpoint returns { "ok": true }. If the current password is wrong it returns 401, and if the user record can't be found it returns 404 — both carry ok:false plus an error string.
Requests a password-reset link for an account, identified by verified email (common path) or by username (for accounts with no email on file, relayed via cmgmt). Anonymous — no JWT required. To avoid leaking which addresses are registered, it always returns 200 with { "ok": true } whether or not a user matched; when a match is found and a delivery channel is wired, the recovery link is sent out-of-band and email_dispatched may be present.
Reports whether authentication is enforced on this instance. Anonymous and cheap — use it from a client bootstrap to decide whether to prompt for login, or from a monitor to confirm the auth subsystem is up. Responds 200 with { "enabled": true } when a bearer token is required for protected routes.
Liveness and schema-discovery endpoints. Use /health for uptime and first-run detection, then walk the data plane top-down: list the namespaces you can see, drill into the types inside one, and pull per-type record counts and storage telemetry. These are the calls the InventDB Console uses to render its Browser tab.
GET/healthpublicSOAR + Serverless
Anonymous liveness check — no token required, and callable while the server is still in setup mode. Returns the running engine version plus setupRequired, which is derived from DB state (whether an active superadmin/admin exists in _system.users), not from config.json. Poll this from load balancers and uptime monitors, or read setupRequired to decide whether to route a new operator into the first-run wizard.
Request
curl -s -X GET 'https://acme.sandbox.inventdb.com/health'
Lists the namespaces (databases) the caller can see, as a bare sorted JSON array of names. RBAC filters the result to only the namespaces the caller's grants admit; superadmin and admin see everything. Pass ?includeSystem=false to hide the engine's _-prefixed system namespaces (such as _system and _soar), leaving just your application namespaces like pms.
Path & query parameters
Name
In
Type
Description
includeSystem
query
boolean
Include _-prefixed system namespaces such as _system/_soar. Default true. Set false to return only application namespaces like pms.
Request
curl -s -X GET 'https://acme.sandbox.inventdb.com/api/namespaces?includeSystem=false' \
-H 'Authorization: Bearer $TOKEN'
Response 200
[
"pms"
]
With the default includeSystem=true, the same caller (superadmin) also sees the engine's internal namespaces:
Lists the types (tables) inside a namespace. By default returns a bare array of type names such as ["owners", "properties", …]; pass ?metadata=true to instead get an array of {name, recordCount, …} objects. RBAC filters to the types the caller can read, and engine-internal _* types (attachments, embeddings, relationships) are hidden from non-admins.
Path & query parameters
Name
In
Type
Description
namespace
path
string
The namespace to inspect, e.g. pms.
metadata
query
boolean
If true, the response is an array of TypeInfo objects ({name, recordCount, …}) instead of bare name strings. Default false.
Request
curl -s -X GET 'https://acme.sandbox.inventdb.com/api/namespaces/pms/types' \
-H 'Authorization: Bearer $TOKEN'
Returns every type in a namespace with its per-type record count plus storage stats — the call that powers the InventDB Console "Browser" tab. For admin/superadmin the response includes dataSizeBytes, idLocatorSizeBytes, indexSizeBytes, and totalSizeBytes. Non-admin callers get only {namespace, typeName, recordCount} — the storage telemetry is stripped. Use it to build a namespace overview or to spot which types dominate on-disk footprint.
Path & query parameters
Name
In
Type
Description
namespace
path
string
The namespace to summarize, e.g. pms.
Request
curl -s -X GET 'https://acme.sandbox.inventdb.com/api/pms' \
-H 'Authorization: Bearer $TOKEN'
Direct SQL execution via POST /sql. This is the primary read path into the InventDB engine — SELECT-only on the data plane today (writes go through db / bulk). The caller's JWT principal is enforced as a row-level-security (RLS) scope over every referenced table, and an optional ?metrics flag wraps the rows in a server-side timing envelope.
POST/sqlBearerSOAR + Serverless
Executes a SQL query against the InventDB engine and returns the matching rows. Use it for every read: filtered SELECTs, multi-table JOINs, GROUP BY aggregates, ORDER BY / LIMIT windowing, and semantic MEANING() search. RLS is applied automatically from the caller's principal (superadmin / admin / setup bypass it). Append ?metrics=1 to get a { rows, metrics } wrapper with server-side timing instead of the bare array. CRUD (INSERT / UPDATE / DELETE) is rejected here — those belong on /db/:namespace/:type/*.
Result keys mirror your SELECT list verbatim. A bare qualified column such as p.property_id is returned under the qualified key "p.property_id" (kept intact so JOINed tables that share a column name don't collide). Add an explicit alias — SELECT p.property_id AS property_id — whenever you want clean, unqualified keys in the response.
Path & query parameters
Name
In
Type
Description
metrics
query
string
Optional. 1 or true switches the response from a bare JSON array to a { "rows": [...], "metrics": {...} } wrapper carrying elapsedMs, count, truncated, and rowCap. Omit it (or any other value) for the legacy bare-array shape.
Request body
Name
In
Type
Description
sql
body
string
Required. The SQL text, executed verbatim under the caller's RLS scope. Identifiers are namespace.type (e.g. pms.properties). SELECT-only. MEANING(text_col) = 'phrase' / LIKE routes through the embedded MiniLM-L6-v2 semantic search (falls back to text-equality if no embedder is loaded).
parameters
body
object | null
Optional / reserved. Placeholder for prepared-statement binds. The engine inlines literals today — put values directly in sql.
Request — filtered SELECT
curl -s -X POST 'https://acme.sandbox.inventdb.com/sql' \
-H 'Authorization: Bearer $TOKEN' \
-H 'content-type: application/json' \
-d '{ "sql": "SELECT property_id, city, state, type, beds, baths, market_rent, market_value, status FROM pms.properties WHERE state = '\''VA'\'' AND status = '\''Occupied'\'' ORDER BY market_rent DESC LIMIT 3" }'
{
"sql": "SELECT property_id, city, state, type, beds, baths, market_rent, market_value, status FROM pms.properties WHERE state = 'VA' AND status = 'Occupied' ORDER BY market_rent DESC LIMIT 3"
}
curl -s -X POST 'https://acme.sandbox.inventdb.com/sql?metrics=1' \
-H 'Authorization: Bearer $TOKEN' \
-H 'content-type: application/json' \
-d '{ "sql": "SELECT p.property_id, p.city, l.tenant_name, l.contract_rent, l.status FROM pms.properties p JOIN pms.leases l ON l.property_id = p.property_id WHERE l.status = '\''Active'\'' ORDER BY l.contract_rent DESC LIMIT 3" }'
{
"sql": "SELECT p.property_id, p.city, l.tenant_name, l.contract_rent, l.status FROM pms.properties p JOIN pms.leases l ON l.property_id = p.property_id WHERE l.status = 'Active' ORDER BY l.contract_rent DESC LIMIT 3"
}
Response 200 — { rows, metrics } wrapper
JOIN result columns are returned under their alias.column keys (e.g. p.property_id, l.tenant_name). The metrics block reports elapsedMs (parse + plan + execute + serialize; excludes network RTT), count (rows after RLS, equal to rows.length), and the unbounded-read guard (truncated / rowCap).
curl -s -X POST 'https://acme.sandbox.inventdb.com/sql?metrics=1' \
-H 'Authorization: Bearer $TOKEN' \
-H 'content-type: application/json' \
-d '{ "sql": "SELECT city, COUNT(*) AS units, AVG(market_rent) AS avg_rent, SUM(market_value) AS portfolio_value FROM pms.properties GROUP BY city ORDER BY portfolio_value DESC LIMIT 5" }'
{
"sql": "SELECT city, COUNT(*) AS units, AVG(market_rent) AS avg_rent, SUM(market_value) AS portfolio_value FROM pms.properties GROUP BY city ORDER BY portfolio_value DESC LIMIT 5"
}
Response 200 — aggregated rows
Aggregates come back as JSON numbers (AVG / SUM as floats, COUNT as an integer) under the projected column alias. Note the grouped text key (city) is normalized to lowercase by the group operator.
Record CRUD over /db/:namespace/:type[/:id]. Insert, read, update, and delete individual documents in any type, plus a cheap id-listing walk. The engine is schemaless — new properties and new types are created on first write, no migration step. Writes stamp _id, _createdAt, _createdBy, _updatedAt, and _updatedBy from the JWT principal, validate _relationships referential integrity (409 on conflict), and enforce row-level security so you only touch rows your grants admit.
POST/db/{namespace}/{type}BearerSOAR + Serverless
Insert a single document into :namespace.:type. The full JSON body is the document — there is no envelope. The engine assigns _id (UUID v4 unless you supply one) and stamps the created/updated audit fields from your token. New namespaces and types are created lazily on first write, and any new property is indexed on first sight. Use ?disableIndexing=true to defer property + vector index maintenance during bulk loads.
Path & query parameters
Name
In
Type
Description
namespace
path
string
e.g. pms. Created lazily if new.
type
path
string
e.g. properties. Created lazily if new.
disableIndexing
query
boolean
Skip property + vector index updates for this write.
Update an existing document by _id, which MUST be present in the request body. The body you send becomes the new latest version (append-only at the storage layer — older versions stay readable via point-in-time queries). Row-level filters must accept both the pre-image and the post-image: you can neither edit a row you don't own nor move one out of your ownership scope. Missing _id is 400; no matching row is 404; a referential-integrity conflict is 409.
Fetch a single document by _id. The response body is the document JSON itself — no envelope, including the system fields _id, _createdAt, and _updatedAt. RLS row filters apply: a row outside your scope returns 404 rather than 403, so the API never leaks whether an id you can't see exists.
Path & query parameters
Name
In
Type
Description
namespace
path
string
e.g. pms.
type
path
string
e.g. properties.
id
path
string
Document _id, e.g. 2bba668e-ad1c-447b-9e70-7cf9d9221b2c.
Request
curl -s -X GET 'https://acme.sandbox.inventdb.com/db/pms/properties/2bba668e-ad1c-447b-9e70-7cf9d9221b2c' \
-H 'Authorization: Bearer $TOKEN'
Delete a document by _id. This is a soft delete: a tombstone supersedes the row for normal SELECTs, but earlier versions stay queryable for point-in-time reads. Any attachments owned by this _id are removed transactionally. A row protected by referential integrity — referenced by another type via _relationships — cannot be deleted until those references clear, and the call returns 409.
List all document _ids in a type. This is cheap — it walks the per-type id index only and reads no property values. RLS row filters still apply, so you only see the ids of rows you're allowed to read. For paged fetches of full rows, use POST /sql with LIMIT and ORDER BY instead of hydrating every id here.
Path & query parameters
Name
In
Type
Description
namespace
path
string
e.g. pms.
type
path
string
e.g. properties.
Request
curl -s -X GET 'https://acme.sandbox.inventdb.com/db/pms/properties' \
-H 'Authorization: Bearer $TOKEN'
Convenience query wrappers that cover the most common single-type read patterns — substring search, numeric ranges, date ranges, and AND-composed multi-property filters — without hand-writing SQL. Each is a thin shim over the engine's SQL path (RLS row filters and per-table grants still apply), and every one returns a bare JSON array of full row objects. For OR semantics, joins, aggregation, or semantic MEANING() search, use POST /sql directly.
Substring search on a single string property. This is a convenience wrapper over SELECT * FROM ns.type WHERE prop LIKE '%q%'. It is fast on small types; for larger types prefer /sql with an explicit LIMIT. Use it for quick lookups like finding an owner by part of their name or a work order by a keyword in the issue text.
Path & query parameters
Name
In
Type
Description
namespace
path
string
e.g. pms
type
path
string
Type / table name, e.g. owners
prop
query
string
String property to scan, e.g. name
q
query
string
Substring to match (LIKE-style), e.g. Whitfield
Request
curl -s -X GET 'https://acme.sandbox.inventdb.com/query/pms/owners/contains?prop=name&q=Whitfield' \
-H 'Authorization: Bearer $TOKEN'
Closed-interval numeric range query: lo <= prop <= hi. Both bounds are inclusive doubles. Use it to pull rows where a numeric column falls inside a window — for example properties whose market_rent is between two dollar amounts, or work orders in a cost band. Returns a bare array of full row objects.
Path & query parameters
Name
In
Type
Description
namespace
path
string
e.g. pms
type
path
string
Type / table name, e.g. properties
prop
query
string
Numeric property to range over, e.g. market_rent
lo
query
number
Inclusive lower bound, e.g. 1500
hi
query
number
Inclusive upper bound, e.g. 1600
Request
curl -s -X GET 'https://acme.sandbox.inventdb.com/query/pms/properties/range?prop=market_rent&lo=1500&hi=1600' \
-H 'Authorization: Bearer $TOKEN'
Date / DateTime range query with inclusive bounds. Bounds are ISO 8601 strings; date-only literals are treated as midnight UTC, so to capture the entire end day pass a full timestamp such as end=2026-10-31T23:59:59Z. Use it for date-window reports like leases starting in a given month or transactions posted in a quarter. Returns a bare array of full row objects.
Path & query parameters
Name
In
Type
Description
namespace
path
string
e.g. pms
type
path
string
Type / table name, e.g. leases
prop
query
string
Date / datetime property to filter, e.g. lease_start
start
query
string
Inclusive start (ISO 8601), e.g. 2025-10-01
end
query
string
Inclusive end (ISO 8601), e.g. 2025-10-31
Request
curl -s -X GET 'https://acme.sandbox.inventdb.com/query/pms/leases/daterange?prop=lease_start&start=2025-10-01&end=2025-10-31T23:59:59Z' \
-H 'Authorization: Bearer $TOKEN'
AND-composed multi-property filter with pagination and ordering — a convenience over /sql for the very common "filter on N properties, sort, paginate" case. Each entry in conditions becomes one WHERE prop OP value clause and all clauses are AND'ed together; for OR semantics use /sql directly. Sort with order_by + order_dir and page with limit / offset. Returns a bare array of full row objects.
Path & query parameters
Name
In
Type
Description
namespace
path
string
e.g. pms
type
path
string
Type / table name, e.g. properties
conditions
body
array
Required. AND'ed list of { prop, op, value }. Empty list returns all readable rows (subject to RLS).
conditions[].op
body
string
One of eq, ne, gt, gte, lt, lte, like (SQL LIKE), contains (case-sensitive substring).
order_by
body
string?
Property to sort by, e.g. market_rent.
order_dir
body
string?
asc (default) or desc, case-insensitive.
limit
body
integer?
Max rows. No cap enforced if absent — use with care.
High-throughput, whole-batch operations against a type: insert many documents in one round-trip, and remove rows en masse by id, by filter, or all at once. Destructive endpoints layer on guard rails — referential-integrity checks, an explicit CONFIRM phrase, and admin-only type/namespace drops — so a single call can never quietly cascade.
Insert N documents in a single request instead of one POST per row. Accepts either a bare JSON array or an { "documents": [...] } envelope. RBAC and the writer's row-filter are validated once up front, then the batch streams into the engine; per-row failures are aggregated into error while the ids that landed are still returned. A successful insert responds 201 Created; an empty request (zero documents) is a 200 no-op. Pass ?disableIndexing=true on large loads and rebuild indexes afterward.
Path & query parameters
Name
In
Type
Description
namespace
path
string
e.g. pms. Created lazily on first write.
type
path
string
e.g. properties. Created lazily on first write.
disableIndexing
query
boolean
Skip property + vector index maintenance for write-throughput-sensitive loads. Rebuild via /api/indexes/:ns/:type/rebuild after.
Delete a set of documents by _id in one call. Referential integrity is validated for the entire batch before any row is removed — if any id is referenced by another type via _relationships, the whole call aborts with 409 and nothing is deleted. Ids that don't exist are skipped silently, so deletedCount may be less than ids.length. Returns 206 if some individual deletes errored after the RI gate passed.
Delete every row that matches a filter condition. The engine runs a SELECT _id with the filter applied, then deletes each matched row. The filter is a property→value map whose terms are AND'ed into a SQL WHERE clause — e.g. {"status": "void", "year": 2024} becomes WHERE status = 'void' AND year = 2024. Safer than deleteAll because the filter shape forces an explicit decision about what to drop.
Delete every row in a type — a truncate. The request body must carry the literal confirmation phrase "CONFIRM"; anything else refuses with 400 to guard against accidental cascades. The type folder, its properties, and history rows remain (use DELETE /api/:ns/:type to drop the type entirely). Requires delete access on the type.
Drop an entire type — its data directory, segments, indexes, and attachments — from disk. This is destructive and irreversible: unlike a soft-deleted row you cannot point-in-time-query it back. Admin / superadmin only. Use deleteAll instead if you only want to empty the rows but keep the type and its schema.
Drop an entire namespace and every type inside it — the whole namespace folder is removed. This is the most destructive operation in the API, equivalent to dropping every type sequentially. Admin / superadmin only. There is no undo and no point-in-time recovery once the folder is gone.
Universal vector embedding pipeline — MEANING() SQL is wired in transparently against per-segment HNSW indexes. Every user type with string properties is embedded automatically (MiniLM all-MiniLM-L6-v2, 384 dims); new writes are embedded inline and sealed segments are backfilled by a background worker. These admin-only endpoints expose install status, an aggregated per-segment overview for the Settings → Vector Indexes card, and a one-shot backfill trigger. You almost never call these to search — semantic search is done in SQL, e.g. WHERE MEANING('quiet condo near downtown') > 0.5.
Returns whether the universal vector embedding pipeline is installed and loadable on this instance. Use it as a lightweight health probe before relying on MEANING() semantic search in SQL, or from the admin console to confirm the MiniLM model + tokenizer files were found at boot. Admin/superadmin only; a non-admin caller gets 403.
Path & query parameters
None. The status is instance-wide, not scoped to a namespace or type.
Request
curl -s -X GET 'https://acme.sandbox.inventdb.com/api/vectors/universal/status' \
-H 'Authorization: Bearer $TOKEN'
Response 200
{
"embeddingGeneratorInstalled": true,
"modelFilesExist": true,
"note": "Universal vector embedding pipeline is active. New writes are auto-embedded; sealed segments are auto-backfilled in background."
}
Aggregates per-segment vector index counts across every user namespace.type (for example every table in the pms namespace) into a single round-trip for the Settings → Vector Indexes card. Cheap and lock-free — it walks each type's segments.json manifest from disk and tallies; it runs no DB queries. Use it to see how many sealed segments are still vectors_pending versus fully indexed. Admin/superadmin only.
Path & query parameters
None. Counts are aggregated across all user (non-_) namespaces and types.
Request
curl -s -X GET 'https://acme.sandbox.inventdb.com/api/vectors/universal/overview' \
-H 'Authorization: Bearer $TOKEN'
Response 200
{
"embeddingGeneratorInstalled": true,
"modelName": "all-MiniLM-L6-v2",
"modelDimensions": 384,
"typesTotal": 14,
"activeSegments": 14,
"sealedSegmentsTotal": 6,
"sealedSegmentsIndexed": 5,
"sealedSegmentsPending": 1,
"note": "Pipeline active. 1 sealed segment marked vectors_pending across pms.transactions; background worker will index it shortly."
}
Here typesTotal: 14 reflects the 14 pms tables (properties, owners, leases, tenants, transactions, work_orders, vendors, inspections, compliance, daily_tasks, …). Each type has exactly one active write segment, so activeSegments equals the number of types with data on disk. sealedSegmentsPending counts sealed segments the background backfill worker still needs to embed.
Triggers a one-shot, synchronous backfill across ALL types/segments tagged vectors_pending. A background thread already does this continuously, but this endpoint forces an immediate run from the admin console — useful right after a bulk import into pms.transactions or pms.leases when you want semantic search over the new rows without waiting for the worker. Returns the number of segments processed and wall-clock time. Admin/superadmin only; internal failure returns 500.
Path & query parameters
None. There is no request body — the backfill scope is every pending segment across all user types.
Request
curl -s -X POST 'https://acme.sandbox.inventdb.com/api/vectors/universal/backfill' \
-H 'Authorization: Bearer $TOKEN'
Response 200
{
"processedSegments": 1,
"elapsedMs": 3
}
When nothing is pending (all sealed segments already indexed), the response is { "processedSegments": 0, "elapsedMs": 3 } and the call is effectively a no-op.
Indexes (admin)
Property B-tree index management — inspect per-property index statistics, run full rebuilds (Server-Sent Events stream), poll rebuild progress, consolidate (flush + fsync) indexes to disk, and pause/resume property indexing globally during bulk loads. Every endpoint is admin-only; the index files live on disk under <data_root>/<ns>/<type>/prop_*.tree.
GET/api/indexesBearerSOAR + Serverless
Returns a status grid for every user-namespace type, with per-property B-tree statistics (tree height, leaf count, distinct values, estimated cardinality). Use it to power an admin index-health dashboard or to decide which types need a rebuild. Admin-only; internal _* namespaces are skipped.
indexStatus is active under normal operation; it reads rebuilding while a rebuild is in flight, or stale when property indexes lag the latest writes (usually self-heals on the next checkpoint).
Polling alternative to the SSE rebuild stream — returns a single snapshot of rebuild progress for one type. status is one of idle, rebuilding, completed, or failed. Poll this from tooling that can't (or shouldn't) hold an EventSource connection open while a rebuild runs.
While a rebuild is active the same shape carries live numbers, e.g. "status": "rebuilding", "progressPercent": 42.0, "recordsProcessed": 210, "totalRecords": 500.
Runs a full index rebuild for one type: it walks every row, drops the existing prop_*.tree files, and re-indexes from scratch. The response is a Server-Sent Events stream of progress frames; the terminal data: frame has status: completed or failed, followed by an event: done frame. Because EventSource can't send an Authorization header, pass the JWT via the ?token= query parameter instead.
Path & query parameters
Name
In
Type
Description
namespace
path
string
e.g. pms
type
path
string
e.g. leases
token
query
string
JWT bearer token (EventSource has no header support).
POST variant of the SSE rebuild — same outcome as GET /api/indexes/:ns/:type/rebuild, but addressable via POST so tooling that can't open an EventSource connection can still kick off a rebuild. It runs as the system principal and streams the same progress frames back. Prefer this from scripts and background jobs; prefer the GET/SSE form for browser-driven admin consoles.
Path & query parameters
Name
In
Type
Description
namespace
path
string
e.g. pms
type
path
string
e.g. leases
Request
curl -sN -X POST 'https://acme.sandbox.inventdb.com/api/pms/leases/reindex' \
-H 'Authorization: Bearer $TOKEN'
Flushes and fsyncs the indexes for one type to disk. Synchronous — the call returns only once every dirty page is durable. Use it before snapshotting the data directory or before a graceful shutdown so no index writes are lost.
Path & query parameters
Name
In
Type
Description
namespace
path
string
e.g. pms
type
path
string
e.g. properties
Request
curl -s -X POST 'https://acme.sandbox.inventdb.com/api/indexes/pms/properties/consolidate' \
-H 'Authorization: Bearer $TOKEN'
Response 200
{
"ok": true,
"message": "Index consolidation completed for pms.properties - all data synced to disk"
}
Flushes and fsyncs every user-namespace type to disk in one call — it walks list_namespaces() → list_types(), skipping internal _* stores, and syncs each. Returns 200 when all types sync cleanly, or 206 if some fail, with a message that summarizes the count.
Request
curl -s -X POST 'https://acme.sandbox.inventdb.com/api/indexes/consolidate-all' \
-H 'Authorization: Bearer $TOKEN'
Response 200
{
"ok": true,
"message": "Consolidated 20 type stores - all data synced to disk"
}
Response 206
{
"ok": false,
"message": "Consolidated 18 of 20 type stores - 2 failed to sync",
"error": "pms.transactions: disk I/O error"
}
Disabled by design — this endpoint is a no-op. It returns 200 with an explanatory message instead of deleting anything. The Rust engine rebuilds indexes incrementally from the source data, so an API-driven delete would leave a window of empty indexes with no safety net. To refresh indexes, use GET /api/indexes/:ns/:type/rebuild (or the POST /reindex variant) instead.
{
"ok": true,
"message": "Index deletion not recommended. Type pms.properties has 29 property indexes. Use /rebuild endpoint to refresh indexes instead."
}
POST/api/indexingBearerSOAR + Serverless
Globally enables or disables property indexing. When disabled, every write skips index maintenance — the standard trick for speeding up large bulk loads. Afterwards, re-enable with this endpoint and then call POST /api/indexes/:ns/:type/consolidate (or run a full rebuild) so the indexes catch up with the loaded rows.
Path & query parameters
Name
In
Type
Description
enabled
query
boolean
true to re-enable indexing, false to pause it. Required.
Request
# pause indexing before a bulk load
curl -s -X POST 'https://acme.sandbox.inventdb.com/api/indexing?enabled=false' \
-H 'Authorization: Bearer $TOKEN'
# ...bulk-load pms.properties, then re-enable...
curl -s -X POST 'https://acme.sandbox.inventdb.com/api/indexing?enabled=true' \
-H 'Authorization: Bearer $TOKEN'
Response 200
{
"ok": true,
"indexingEnabled": true
}
POST/api/indexing/waitBearerSOAR + Serverless
Blocks until all pending index work has drained, then returns 200. Handy in scripted workflows that bulk-load a type (e.g. pms.transactions) and then immediately query it by an indexed column — call this first to guarantee the indexes are caught up before the read.
Request
curl -s -X POST 'https://acme.sandbox.inventdb.com/api/indexing/wait' \
-H 'Authorization: Bearer $TOKEN'
Response 200
{
"ok": true,
"message": "All indexing operations completed"
}
Clears the rebuild-progress history table, resetting the "Last rebuild" timeline shown in the admin console after maintenance. This is bookkeeping only — it has no effect on live data or on the indexes themselves.
Request
curl -s -X POST 'https://acme.sandbox.inventdb.com/api/indexes/clear-history' \
-H 'Authorization: Bearer $TOKEN'
Response 200
{
"ok": true,
"message": "Rebuild history cleared"
}
Relationships
The foreign-key graph for a namespace. Each edge is a property-to-property link between two types (e.g. pms.leases.property_id → pms.properties.property_id) carrying a cardinality hint and an enforce flag for referential integrity. Read the graph, replace it (admin only), drop it, auto-detect candidate edges from column-name heuristics plus data sampling, or fetch the per-type property schema that drives the Console's relationship designer.
Returns the full relationship graph for a namespace as a single graph record. Each entry in edges links a source property to a target property, with a cardinality hint (many-to-one, one-to-many, …), an enforce flag for referential integrity, and an optional human label. Use it to render join diagrams or to seed an edit before a PUT. An empty graph (edges: []) is returned when nothing is configured yet.
Path & query parameters
Name
In
Type
Description
namespace
path
string
Namespace whose graph to read, e.g. pms.
Request
curl -s -X GET 'https://acme.sandbox.inventdb.com/api/relationships/pms' \
-H 'Authorization: Bearer $TOKEN'
Replaces the relationship graph for a namespace. Admin / superadmin only — the graph defines the data model itself (which types reference which, and on what columns), so a plain write grant is not enough. PUT semantics are wholesale: the supplied edges array fully replaces what was there, so GET first, edit the array, then send it back. The optional layout blob (node positions, zoom) is round-tripped verbatim.
Drops the relationship graph for a namespace. Requires admin permission on the namespace. The underlying edge records and the saved layout are removed, but the namespace's actual data (properties, leases, tenants, …) is left completely untouched — only the FK metadata goes away.
Auto-detects candidate relationships by combining column-name heuristics (*_id columns map to a matching type), data sampling (checks that the foreign-key values actually resolve in the target type), and an optional LLM assist for naming-mismatch links. Pass an optional types array to restrict the scan; omit it to scan every type in the namespace. The response is suggestions only — nothing is persisted. The user reviews them in the designer and PUTs the final set back via save_relationships.
Returns every non-system type in a namespace together with its recordCount and known properties[]. This drives the InventDB Console's relationship designer so the user can pick valid source and target columns (e.g. leases.property_id → properties.property_id). Property lists reflect what the schemaless engine has seen so far, so newer columns appear automatically as rows are written.
Path & query parameters
Name
In
Type
Description
namespace
path
string
Namespace whose type schema to list, e.g. pms.
Request
curl -s -X GET 'https://acme.sandbox.inventdb.com/api/relationships/pms/types-schema' \
-H 'Authorization: Bearer $TOKEN'
Event-driven workflows engine — workflow CRUD, the runs timeline, manual fire, run export, and lifecycle toggles (pause / resume / activate). A workflow pairs a trigger (cron, gmail, webhook, manual, …) with an ordered plan of steps (sql_query, render_report, llm_extract, send_email, notify_user, create_calendar_event, finish, …). Every workflow is owned by the caller and scoped by RLS. All endpoints require a Bearer token.
POST/api/workflowsBearerSOAR + Serverless
Create a new event-driven workflow owned by the caller. The body carries the display name, the trigger_kind + kind-specific trigger_spec, a short natural-language trigger_intent, and the ordered plan array of steps. New workflows land in pending_approval=true / active=false — call /activate (or the pause/resume toggles) to let the dispatcher fire them. sandbox defaults to true, so a fresh workflow never produces externally-visible side effects until you deliberately turn sandbox off.
Request body fields
Name
In
Type
Description
name
body
string
Display name (non-empty).
trigger_kind
body
string
cron | gmail | webhook | manual | …
trigger_spec
body
object
Kind-specific config, e.g. { "expr": "0 9 * * *", "tz": "Asia/Calcutta" } for cron.
trigger_intent
body
string
Short natural-language description of what should happen.
plan
body
array
Ordered WorkflowStep objects. Each needs idx, label, narration, kind and kind-specific fields (a notify_user step needs title + body; a sql_query step needs sql).
tools_allowed
body
array
Allowlist for LLM tool calls inside the run (empty = none).
budget
body
object
Optional ceiling, e.g. { "max_tool_calls": 25, "max_input_tokens": 50000 }.
sandbox
body
boolean
Defaults true; when true the run makes no externally-visible side effects (emails go to inbox staging only).
Request
curl -s -X POST 'https://acme.sandbox.inventdb.com/api/workflows' \
-H 'Authorization: Bearer $TOKEN' \
-H 'content-type: application/json' \
-d '{
"name": "Overdue Rent Alert",
"trigger_kind": "cron",
"trigger_spec": { "expr": "0 8 * * *", "tz": "Asia/Calcutta" },
"trigger_intent": "Every morning, find rent transactions and notify the operator.",
"plan": [
{ "idx": 1, "label": "Find rent activity",
"narration": "Pulls recent rent income rows for the portfolio.",
"kind": "sql_query", "save_as": "rent",
"sql": "SELECT property_id, amount FROM pms.transactions WHERE type = '\''Income'\'' AND account_category = '\''Rent'\'' LIMIT 50" },
{ "idx": 2, "label": "Notify operator",
"narration": "Posts an in-app notification with the rent summary.",
"kind": "notify_user", "title": "Rent summary ready",
"body": "Rent activity summary is ready to review." }
],
"tools_allowed": [],
"sandbox": true
}'
{
"name": "Overdue Rent Alert",
"trigger_kind": "cron",
"trigger_spec": { "expr": "0 8 * * *", "tz": "Asia/Calcutta" },
"trigger_intent": "Every morning, find rent transactions and notify the operator.",
"plan": [
{
"idx": 1,
"label": "Find rent activity",
"narration": "Pulls recent rent income rows for the portfolio.",
"kind": "sql_query",
"save_as": "rent",
"sql": "SELECT property_id, amount FROM pms.transactions WHERE type = 'Income' AND account_category = 'Rent' LIMIT 50"
},
{
"idx": 2,
"label": "Notify operator",
"narration": "Posts an in-app notification with the rent summary.",
"kind": "notify_user",
"title": "Rent summary ready",
"body": "Rent activity summary is ready to review."
}
],
"tools_allowed": [],
"sandbox": true
}
Response 200
{
"ok": true,
"data": {
"_id": "1f34ff78-55a0-40a8-9a55-3fb62d7e4bd2",
"name": "Overdue Rent Alert",
"owner_user_id": "a9b4e239-27ff-4f38-949b-38b332b3f8ed",
"trigger_kind": "cron",
"trigger_spec": { "expr": "0 8 * * *", "tz": "Asia/Calcutta" },
"trigger_intent": "Every morning, find rent transactions and notify the operator.",
"plan": [
{ "idx": 1, "label": "Find rent activity", "narration": "Pulls recent rent income rows for the portfolio.", "kind": "sql_query", "save_as": "rent", "sql": "SELECT property_id, amount FROM pms.transactions WHERE type = 'Income' AND account_category = 'Rent' LIMIT 50" },
{ "idx": 2, "label": "Notify operator", "narration": "Posts an in-app notification with the rent summary.", "kind": "notify_user", "title": "Rent summary ready", "body": "Rent activity summary is ready to review." }
],
"pending_approval": true,
"tools_allowed": [],
"budget": { "max_tool_calls": 25, "max_input_tokens": 50000, "max_runtime_secs": 1800, "max_parked_secs": 1209600 },
"sandbox": true,
"active": false,
"version": 1,
"created_at": "2026-07-13T11:12:24.314637900+00:00",
"updated_at": "2026-07-13T11:12:24.314637900+00:00",
"next_run_at": "2026-07-14T02:30:00+00:00",
"_createdBy": "a9b4e239-27ff-4f38-949b-38b332b3f8ed"
}
}
GET/api/workflowsBearerSOAR + Serverless
List every workflow owned by the caller, newest activity first. Each row includes the trigger kind, natural-language intent, lifecycle flags (active, pending_approval), and dispatch timestamps. Pass ?include_deleted=true to also surface soft-deleted rows for audit or undo flows.
{
"ok": true,
"data": {
"workflows": [
{
"_id": "3d754a89-3b42-462f-969e-80b7ece7d880",
"name": "Daily Owner Statements — 9 AM email to each owner",
"trigger_kind": "cron",
"trigger_intent": "Every morning at 9:00 AM (Asia/Calcutta), render the \"Owner Statement\" report for each owner and email each owner their own statement.",
"active": true,
"pending_approval": false,
"deleted_at": null,
"created_at": "2026-07-11T12:40:47.156715100+00:00",
"updated_at": "2026-07-13T03:30:18.793315+00:00",
"last_dispatched_at": "2026-07-13T03:30:18.793281500+00:00"
},
{
"_id": "1d315f38-db91-4daf-8055-02b56b92de14",
"name": "Lease Renewal Reminder (60-day, with approval)",
"trigger_kind": "cron",
"trigger_intent": "Every morning, find active leases expiring within 60 days, draft a renewal-reminder email per tenant, and park for approval.",
"active": false,
"pending_approval": true,
"deleted_at": null,
"created_at": "2026-07-09T15:17:35.036894400+00:00",
"updated_at": "2026-07-09T15:17:35.036894400+00:00",
"last_dispatched_at": null
}
]
}
}
GET/api/workflows/{id}BearerSOAR + Serverless
Read a single workflow's full definition — the complete plan, trigger_spec, budget, lifecycle flags, and the natural-language message_context that built it. Use this to inspect or clone a workflow before editing it with PUT.
{
"ok": true,
"data": {
"_id": "138a46dd-6ba9-4505-8ae5-ba9b4c4d09d1",
"name": "Daily Owner Portfolio Summary email",
"owner_user_id": "a9b4e239-27ff-4f38-949b-38b332b3f8ed",
"trigger_kind": "cron",
"trigger_spec": { "expr": "0 9 * * *", "tz": "Asia/Calcutta" },
"trigger_intent": "Every morning at 9:00 AM (Asia/Calcutta), render the \"Owner Portfolio Summary\" report for owner O-1002 and email it.",
"plan": [
{ "idx": 1, "label": "Render Owner Portfolio Summary", "narration": "Renders the saved report template live against pms data for owner O-1002.", "save_as": "report", "kind": "render_report", "template_id": "tpl_095c0b7a07a2", "params": { "owner_id": "O-1002" } },
{ "idx": 2, "label": "Email the report to me", "narration": "Emails the rendered portfolio summary HTML as the morning digest.", "kind": "send_email", "to": "developer.3@inventdb.com", "subject": "Owner Portfolio Summary — ${today}", "body": "${report.html}" },
{ "idx": 3, "label": "Done", "narration": "Marks the run complete once the email has been dispatched.", "kind": "finish", "summary": "Rendered the report and emailed it." }
],
"pending_approval": false,
"tools_allowed": [],
"budget": { "max_tool_calls": 25, "max_input_tokens": 50000, "max_runtime_secs": 1800, "max_parked_secs": 1209600 },
"sandbox": false,
"active": true,
"version": 1,
"created_at": "2026-07-11T06:35:02.843768600+00:00",
"updated_at": "2026-07-13T03:30:18.681641700+00:00",
"last_dispatched_at": "2026-07-13T03:30:18.664288600+00:00",
"next_run_at": "2026-07-14T03:30:00+00:00",
"_createdBy": "a9b4e239-27ff-4f38-949b-38b332b3f8ed"
}
}
PUT/api/workflows/{id}BearerSOAR + Serverless
Update a workflow's metadata or plan. All fields are optional — send only what changed. When plan is included it is re-validated and any errors come back as 400 with an issues array describing each problem; non-plan edits (like a rename) skip validation to avoid unnecessary SQL probes. Each successful update bumps version.
Soft-delete a workflow. Past runs and their event history are preserved (they still show up under /runs and export), and the row can be surfaced again with ?include_deleted=true — but the workflow stops firing on new events. Use this instead of a hard delete so audit trails survive.
Activate a workflow — clears pending_approval and sets active=true. Idempotent for already-active rows. The optional body lets the AI canvas persist a sandbox value in the same click that approves the workflow; omit the body entirely to leave the persisted sandbox flag untouched.
Path & query parameters
Name
In
Type
Description
id
path
string
Workflow _id (uuid).
sandbox
body
boolean | null
Optional. When set, overrides the persisted sandbox flag before flipping active on. Omit to preserve the current value.
Pause a workflow — sets active=false. New trigger events queue but are not dispatched until you resume; any in-flight runs keep going to completion. No request body.
Path & query parameters
Name
In
Type
Description
id
path
string
Workflow _id (uuid).
Request
curl -s -X POST 'https://acme.sandbox.inventdb.com/api/workflows/1f34ff78-55a0-40a8-9a55-3fb62d7e4bd2/pause' \
-H 'Authorization: Bearer $TOKEN'
Resume a paused workflow — sets active=true again. Backlog events that arrived while it was paused are not replayed; they are marked with an ignored_reason. Only events that fire after resume will dispatch. No request body.
Path & query parameters
Name
In
Type
Description
id
path
string
Workflow _id (uuid).
Request
curl -s -X POST 'https://acme.sandbox.inventdb.com/api/workflows/1f34ff78-55a0-40a8-9a55-3fb62d7e4bd2/resume' \
-H 'Authorization: Bearer $TOKEN'
Manually fire a workflow once. This appends a synthetic manual event carrying the supplied sample_payload; the router picks it up on its next tick and creates a run. Set sandbox_override: true to force this single run to be non-side-effecting even if the workflow itself has sandbox off — this is exactly how the canvas "Test" button works.
Path & query parameters
Name
In
Type
Description
id
path
string
Workflow _id (uuid).
sample_payload
body
object
Optional payload injected as the synthetic manual event's data.
sandbox_override
body
boolean
Optional. Force this run to be non-side-effecting regardless of the workflow's own sandbox flag.
{
"ok": true,
"data": {
"event_id": "cc5097c6-269c-4b59-8f9d-3766f8e3d2d8",
"workflow_id": "1f34ff78-55a0-40a8-9a55-3fb62d7e4bd2",
"status": "pending",
"note": "Event queued. Dispatch happens once the router picks it up on its next tick."
}
}
List all runs of one workflow, newest first. Each entry is a run summary — status, start/end timestamps, sandbox flag, and any top-level error — without the per-step timeline. Fetch a single run's /runs/{id} to drill into its steps.
List every run across all workflows the caller owns, newest first. This is the global runs feed that powers the "recent activity" dashboard — one flat array of run summaries spanning all of your workflows.
Read a single run together with its full step timeline. Returns { run, steps } where steps is ordered by idx and includes each step's role (model_in, tool_call, tool_result), the tool_name, its tool_args, the tool_result, and timing. Use it to inspect exactly what a workflow did on a given run.
Dump a run, its steps, the original trigger event, and any notifications it produced — a single self-contained bundle for audit, debugging, or support hand-off. The run embeds a workflow_snapshot (the exact plan as it ran), and the versioned schema field (e.g. inventdb.workflow.run.v1) is the stable contract for consumers of the export.
Per-record file attachments: upload (multipart), list, fetch metadata, raw download, delete, and full-text / semantic / combined search over extracted text and embeddings. Storage is native — chunks, extracted text, and embeddings live in the _attachment* system types (_attachments, _attachment_text, _attachment_embeddings). Every attachment is owned by an existing record, addressed by that record's system _id.
Upload a file attachment against an existing record. The request is a multipart form; the file part carries the raw bytes. On upload the engine stores chunks, extracts text (PDF / DOCX / TXT / images via OCR), and — if the embedding model is loaded — generates semantic embeddings so the file becomes content-searchable. Small text files finish inline; larger files return Pending and the background worker advances processing_state to Ready.
Path & query parameters
Name
In
Type
Description
namespace
path
string
Namespace, e.g. pms
type_name
path
string
Type name, e.g. properties
record_id
path
string
Owning record's system _id (uuid), e.g. fe289741-574c-4311-9733-ad6be7e3ceb0
List every attachment owned by a single record. Returns metadata, tags, folder_path, and per-file processing_state / extraction_status — but not the bytes. Use this to render an attachment explorer for one property, lease, or work order, then fetch bytes via the /download sub-route.
Fetch a single attachment's metadata, tags, and extraction status. Bytes are not included — use the /download sub-route for the raw file. Handy for polling processing_state after a deferred upload until it reaches Ready.
Path & query parameters
Name
In
Type
Description
namespace
path
string
Namespace, e.g. pms
type_name
path
string
Type name, e.g. properties
record_id
path
string
Owning record's system _id
attachment_id
path
string
Attachment id, e.g. att_3a422f35-4abd-41af-86e3-55b29ca8c474
Download the current version of an attachment as raw bytes. The response sets Content-Type to the stored MIME type and Content-Disposition: attachment so browsers trigger a save dialog. Returns 404 if the attachment does not exist.
Delete an attachment — all versions plus stored bytes, extracted text, and embeddings. This is a hard delete with no soft-delete or undo. After this call the file no longer appears in list or search results.
Search attachments across a type. search_type selects the mode: keyword (filename / description / tags via LIKE), fulltext (extracted text via LIKE), semantic (vector similarity via the MEANING() function — requires embeddings), or combined (default; weighted blend of all three). Optional filters, mime_types, tags, threshold, and per-mode weights narrow and rank results.
Self-service user endpoints. Distinct from /api/users/* (admin) and /api/auth/* (auth state). The caller acts only on their own user row and only on the fields these endpoints expose — no role, activation, or password changes here.
PUT/api/me/emailBearerSOAR + Serverless
Updates the email address on the calling user's own row — nothing else. This exists separately from the admin PUT /api/users/{userId} because scheduled-report delivery fails when a regular user's _system.users.email is blank, yet a non-admin cannot use the admin endpoint. The settings page posts here from its one-click "Use my Gmail address" button (shown when Gmail OAuth is connected and the stored email is empty). Scope is strictly the caller's own email field — no role or password mutation.
Path & query parameters
None. The target user is always the authenticated caller (derived from the Bearer token); there is no namespace, id, or query parameter.
Report-template CRUD, SQL-driven HTML rendering, and LLM-assisted template authoring under /api/report-templates.
POST/api/report-templatesBearerSOAR + Serverless
Persists a new SQL-driven HTML report template into _System.ReportTemplates. Body carries the complete html document (with <script type="server"> blocks), mode ("scheduled"|"interactive"), parameters, tags, and an optional per-template max_rows cap. version starts at 1 and createdBy is taken from the caller's JWT. Returns the stored document. No LLM involved.
Request
{
"name": "Monthly Rent Roll",
"description": "Active leases and market rent by property",
"category": "Operational",
"html": "<!DOCTYPE html><html><head><style>@page{size:A4;margin:14mm 12mm}</style></head><body><h1>Rent Roll</h1><table><thead><tr><th>Property</th><th>City</th><th>Market Rent</th></tr></thead><tbody><script type=\"server\">const r=query(\"SELECT property_id, city, market_rent FROM pms.properties WHERE status = :status\",{status:params.status});for(const row of r.rows){out.write('<tr><td>'+esc(row.property_id)+'</td><td>'+esc(row.city)+'</td><td>'+fmt.currency(Number(row.market_rent))+'</td></tr>');}</script></tbody></table></body></html>",
"mode": "scheduled",
"parameters": [
{
"name": "status",
"type": "string",
"label": "Status",
"required": true,
"default": "occupied"
}
],
"tags": [
"rent-roll",
"operational"
],
"max_rows": 5000
}
Returns a lightweight list of saved templates (SELECT _id, name, description, category, mode, version, createdBy … LIMIT 1000) from _System.ReportTemplates. The heavy html body is NOT included — use GET /{id} to fetch a full template. No LLM involved.
Fetches the full stored template document by id, including the complete html body, parameters, tags, and version. Returns 404 when the id does not exist. No LLM involved.
Shallow-merges the JSON body into the stored template (any field except _id, _createdAt, createdBy which are protected) and auto-increments version. Typically used to save html/parameters/name/tags edits. Returns 404 when the id is unknown. No LLM involved.
Loads the template and renders it server-side through the boa-backed report engine under the caller's RLS principal. Parameters are supplied via query string and coerced to the declared parameter types; the template's max_rows override is honoured. Charts render as inline SVG (email_safe_charts=false) for in-browser viewing. Rendering executes the template's SQL only — it does NOT invoke the LLM, so it works on the Serverless tier.
Parameters
Name
In
Type
Description
id
path
string
Template id to render.
status
query
string
Any declared template parameter, e.g. ?status=occupied (parameter names vary per template).
POST variant of the render endpoint: accepts a typed/nested JSON params object instead of query-string params, avoiding URL-encoding. email_safe_charts defaults to true (email/bulk-email use); the in-app viewer sends false to get SVG charts. Executes the template SQL under the caller's RLS principal — no LLM, works on Serverless.
Renders an arbitrary report-template html document supplied inline (not saved) through the same engine pipeline under the caller's RLS principal. Body is a RenderRequest: { html, params, mode?, limits?, email_safe_charts? }. Used by the AI Canvas / editor preview to render before saving. Returns 400 when html is empty, 422 when a server script crashes. Pure rendering — no LLM, works on Serverless.
Request
{
"html": "<!DOCTYPE html><html><body><script type=\"server\">const r=query(\"SELECT COUNT(*) AS value FROM pms.properties\");out.write('Total properties: '+fmt.number(r.rows[0].value));</script></body></html>",
"params": {},
"mode": "scheduled",
"email_safe_charts": false
}
Editor's inline data inspector: substitutes :name params into the given SQL (string values quoted/escaped), expands CURRENT_DATE, appends a LIMIT (default 500) for non-aggregate queries, and executes it. Returns the rows, row count, and execution time. Returns 400 when sql is missing or the query errors. Straight SQL execution — no LLM, works on Serverless.
Request
{
"sql": "SELECT property_id, city, state, market_rent, status FROM pms.properties WHERE status = :status",
"params": {
"status": "occupied"
},
"max_rows": 100
}
Renders a report from either an inline html body or a saved template_id, merging params/parameters into the render. Listed among the AI report routes and gated on the AI tier: on a Serverless-tier instance the whole report-templates nest requires AI to be enabled, so this returns 403 with the "AI features are not available on the Serverless Database tier." error. Requires html OR template_id (400 otherwise). 403 on the Serverless tier (this route calls the built-in LLM).
POST/api/report-templates/from-documentBearerSOAR only
Multipart upload (file + optional name/description). The built-in LLM (vision) reads the uploaded design (PDF/DOCX/XLSX/image) and authors a complete SQL-driven HTML report-template document bound to the customer's schema, returning { html, parameters, mode }. Invokes the built-in LLM — returns 403 on the Serverless Database tier. Also returns 400 when no file is sent, 422 on text-extract failure or non-JSON model output, 502 on LLM error. 403 on the Serverless tier (this route calls the built-in LLM).
Parameters
Name
In
Type
Description
file
query
file (multipart)
The design document to recreate (PDF, DOCX, XLSX, or image). Multipart form field, not a query param.
POST/api/report-templates/{id}/layout/streamBearerSOAR only
SSE endpoint. The user gives a natural-language layout instruction (optionally with pasted images/attachments); the built-in LLM returns a COMPLETE replacement html document, which is validate-rendered under RLS and, if it renders, persisted (version bumped, parameters auto-derived). Streams start/reasoning/html/saved/done (or error) events. Invokes the built-in LLM — returns 403 on the Serverless Database tier. 403 on the Serverless tier (this route calls the built-in LLM).
Parameters
Name
In
Type
Description
id
path
string
Template id being edited.
Request
{
"instruction": "Add a bar chart of total market rent grouped by city, and use a teal accent.",
"messages": [],
"conversationMode": false,
"modelFamily": "claude"
}
Response 200
event: start
data: {"template_id":"tpl_8f21ac","current_version":3,"instruction":"Add a bar chart..."}
event: reasoning
data: {"content":"Composing the report… (8s)"}
event: html
data: {"html":"<!DOCTYPE html>...</html>","bytes":21044}
event: saved
data: {"template_id":"tpl_8f21ac","version":4}
event: done
data: {}
Promotes a rendered ad-hoc report attachment (under _System.AIReports) into a saved template. Prefers the source-tagged sibling attachment (which keeps the live <script type="server"> bindings), auto-detects interactive vs scheduled mode from the html, auto-derives parameters from params.<name> accesses, inserts the new template, and returns { id, editorUrl }. Reads attachments + inserts a record — no LLM call, works on Serverless. Returns 404/400 when the source attachment is missing/empty/non-UTF-8.
Natural-language AI agent: streaming analyst chat, NL-to-SQL, data/type/recipe generation, plus non-LLM helpers (model/config introspection, chat file staging, transactional change-set apply, and Analyze-thread persistence).
POST/ai/chat/streamBearerSOAR only
Runs the v3 tool-calling agent loop and streams progress as Server-Sent Events (each event data is a JSON AgentStep: {type, content, ...} plus tool results, SQL steps, widgets, forms, charts, and a final done). This is an alias for /ai/chat/v3/stream; the Console app calls it directly and the Tenantry proxy forwards to /ai/chat/v3/stream, so both converge on the same backend. AI config is read live from the encrypted DbSettings record; the per-message model_family (or the customer's configured default) resolves the provider/gateway path. Invokes the built-in LLM. 403 on the Serverless tier (this route calls the built-in LLM).
Request
{
"messages": [
{
"role": "user",
"content": "Which owners have the highest total market_value across their properties?"
}
],
"conversationMode": true,
"modelFamily": "claude",
"theme": "light",
"timeZone": "America/New_York"
}
Response 200
data: {"type":"info","content":"Analyzing your question..."}
data: {"type":"sql","content":"Querying database...","sql":"SELECT o.owner_id, o.name, SUM(p.market_value) AS total_value FROM pms.properties p JOIN pms.owners o ON p.owner_id = o.owner_id GROUP BY o.owner_id, o.name ORDER BY total_value DESC LIMIT 5"}
data: {"type":"result","content":"Query returned 5 rows","rows":[{"owner_id":"O-1001","name":"Ridgeline Holdings","total_value":4820000}]}
data: {"type":"done","content":"","answer":"Ridgeline Holdings (O-1001) holds the highest total market value at $4.82M."}
POST/ai/chat/v2/streamBearerSOAR only
Legacy v2 agent loop that streams SSE AgentStep events. Uses the ToolRegistry two-tier loop with task management. AI config is read live from DbSettings; 400 if no provider/key is configured. Superseded by v3 (/ai/chat/stream) but kept for compatibility. Invokes the built-in LLM. 403 on the Serverless tier (this route calls the built-in LLM).
Request
{
"messages": [
{
"role": "user",
"content": "Show me all open work orders for property P-5001"
}
],
"theme": "light"
}
Response 200
data: {"type":"info","content":"Analyzing your question..."}
data: {"type":"result","content":"Query returned 3 rows","rows":[{"property_id":"P-5001","status":"open","description":"HVAC repair"}]}
data: {"type":"done","content":""}
POST/ai/chat/v3/streamBearerSOAR only
The canonical v3 tool-calling agent loop. Identical backend to /ai/chat/stream. Streams SSE AgentStep events; resolves the model via apply_model_family so each family routes to its own gateway path (Claude -> Anthropic /messages, GLM/Sparkle -> OpenAI /chat/completions). 400 if no provider is configured. Invokes the built-in LLM. 403 on the Serverless tier (this route calls the built-in LLM).
Request
{
"messages": [
{
"role": "user",
"content": "Vacate the tenant on lease L-7039 and start a new lease for the incoming tenant"
}
],
"modelFamily": "open"
}
Response 200
data: {"type":"info","content":"Analyzing your question..."}
data: {"type":"change_set","content":"Review the proposed changes","steps":[{"op":"update","typeName":"leases","recordId":"L-7039"}]}
data: {"type":"done","content":""}
POST/ai/chat/{tab_id}/respondBearerSOAR only
User's decision on a task that is in the awaiting_input state, keyed by the chat tab id. responseType is one of approve, deny, edit, cancel (also approve_all/answer). For edit/answer, value carries the edited SQL or answer text. Resumes (or cancels) the LLM-driven task and persists it. 403 if the caller is neither the task owner nor superadmin; 404 if no awaiting task exists for the tab. Sits behind the AI gate and resumes an LLM agent loop. 403 on the Serverless tier (this route calls the built-in LLM).
Parameters
Name
In
Type
Description
tab_id
path
string
Chat tab id whose awaiting_input task should be resumed
Request
{
"responseType": "edit",
"value": "SELECT * FROM pms.leases WHERE status = 'active' LIMIT 50"
}
Response 200
{
"status": "running",
"taskId": "task_9f2a"
}
POST/ai/generate-sqlBearerSOAR only
Turns a natural-language question into a SQL SELECT without running it. Tries fast tiers first (exact + template cache, then the NQC neural query compiler, then the optional PSI engine) and only calls the LLM (Tier 2, tool-calling) on a miss. inferenceSource in the response reports which tier answered (Cache / InventDB NQC / InventDB Inference / External Inference). Refinements pass base_sql (bypasses all fast tiers). context narrows the schema hint; model_family overrides the model. Because the LLM is the fallback path, this route is AI-gated (403 on serverless). 403 on the Serverless tier (this route calls the built-in LLM).
Request
{
"question": "list properties in Austin, TX with market_rent over 2000, most expensive first",
"context": {
"namespace": "pms",
"type": "properties"
},
"modelFamily": "claude"
}
Response 200
{
"sql": "SELECT property_id, city, state, market_rent, beds, baths FROM pms.properties WHERE city = 'Austin' AND state = 'TX' AND market_rent > 2000 ORDER BY market_rent DESC",
"inferenceSource": "External Inference"
}
POST/ai/sql-titleBearerSOAR only
Given a final SQL SELECT, returns a concise 3-7 word Title-Case label for a data-viewer grid, using the same permission-filtered schema context as the SQL generator. Results are cached per sql-hash (cached=true on a repeat hit). Best-effort: on LLM failure returns an empty title with 200 (the client falls back to its own heuristic). 400 if sql is empty. Invokes the built-in LLM on a cache miss. 403 on the Serverless tier (this route calls the built-in LLM).
Request
{
"sql": "SELECT o.name, COUNT(*) AS property_count FROM pms.properties p JOIN pms.owners o ON p.owner_id = o.owner_id GROUP BY o.name ORDER BY property_count DESC"
}
Response 200
{
"title": "Properties by Owner",
"cached": false
}
POST/ai/generate-typesBearerSOAR only
Uses the LLM to draft a JSON array of type definitions (namespace, typeName, fields with name/type/description and optional FK references, recordCount) from a natural-language domain description. Used by the simulation/data-seeding wizard. 400 if description is empty; 500 if the model fails to return a valid JSON array (raw text echoed back). Invokes the built-in LLM. 403 on the Serverless tier (this route calls the built-in LLM).
Request
{
"description": "A property management system with owners, properties, leases and tenants"
}
Streams LLM-generated realistic mock records for each supplied type definition as SSE AgentStep events. Processes parent (FK-target) types first so child records can reference real _id values; caps at 100K records/type and generates up to 50 template records per type via the model. humanReadableIds toggles CUST001-style ids vs UUIDs. Invokes the built-in LLM. 403 on the Serverless tier (this route calls the built-in LLM).
data: {"type":"info","content":"Generating simulation data for: property management owners"}
data: {"type":"info","content":"Generating 50 template records for pms.owners..."}
data: {"type":"done","content":""}
POST/ai/generate-recipeBearerSOAR only
Phase 1 of the simulation flow: derives a deterministic data-generation recipe from the supplied type definitions using Rust-side heuristics (field-name + field-type patterns and built-in word pools) and returns it plus a 10-record-per-type preview for user approval. Despite no longer calling the model, this route sits behind the AI gate and returns 403 on the Serverless tier. 400 if types is empty. 403 on the Serverless tier (this route calls the built-in LLM).
Phase 2 of the simulation flow: generates records from an approved recipe and bulk-inserts them into the database, streaming SSE progress (per-type preview, then generating events at every 1% boundary, then a final done_with_answer). FK linking is preserved by processing parent types first and reusing generated _id pools. Generation itself is deterministic (recipe-driven, no model call) but the route validates AI config and sits behind the AI gate (403 on serverless). 400 if the recipe is empty. 403 on the Serverless tier (this route calls the built-in LLM).
data: {"type":"info","content":"Starting simulation: 1 types, 2500 total records"}
data: {"type":"generating","typeName":"properties","inserted":2500,"total":2500}
data: {"type":"done","content":"Simulation complete. Generated and inserted records across 1 types."}
GET/ai/modelsBearerSOAR + Serverless
Returns the configured model first (marked active), followed by provider-appropriate alternatives. For the InventDB gateway the alternatives are catalog-driven from the enabled model registry ('Family - LLM (Gateway)'); for direct anthropic/openai providers a small static list is returned. No LLM invocation, so this stays open on every tier.
Returns whether AI is configured, a masked API key, the base URL, the model, and the resolved default model family (claude / glm / sparkle / sparkle-thinking) read live from DbSettings. Never exposes the raw key. No LLM invocation; open on every tier.
Multipart upload of one file into the per-session, disk-backed staging store. Returns a pending_id the client embeds in '[attached: ... — pending: <id>]' markers; the agent reads bytes for vision/text peeks and the canvas form re-attaches on Create. No DB writes, no OCR, no embeddings; files expire after 30 min and are capped at 25 MB (413 if larger). 400 if no file field is present. No LLM invocation; open on every tier.
Returns the raw bytes of a staged file (cache-first, disk-fallback so it survives a restart). Used by the canvas form to re-attach the file to a newly created record. 404 if the pending file is missing or expired; 403 if the caller is not the uploader (superadmin may always fetch). No LLM invocation; open on every tier.
Parameters
Name
In
Type
Description
id
path
string
The pending_id (pf_...) returned by /ai/uploads/stage
Response 200
<raw file bytes; Content-Type + Content-Disposition set from the staged file>
DELETE/ai/uploads/{id}BearerSOAR + Serverless
Removes a staged file from the store and disk (called by the canvas form after a successful attach or when the user dismisses the form). Always returns 200 with a removed flag. No LLM invocation; open on every tier.
Parameters
Name
In
Type
Description
id
path
string
The pending_id (pf_...) of the staged file to remove
Response 200
{
"ok": true,
"removed": true
}
POST/ai/change-set/applyBearerSOAR + Serverless
Runs an array of insert/update/delete steps inside a single InventDB transaction (all-or-nothing), then runs any attach steps post-commit (best-effort, outside the tx). This is the confirm-and-commit chokepoint for the AI canvas change-set card, so writes only land after explicit user consent. update merges partial fields over the current doc; record targets resolve by _id or by matchField business key. Returns per-step results and a transactionId. 400 if steps is empty or a data step fails (transaction rolled back); 409 on commit failure; 200 with ok:false if data committed but some attaches failed. No LLM invocation; open on every tier — an external agent authors the steps, this route just applies them.
Returns the caller's persisted Analyze/Workbench chat threads (newest first) from _system._SoarThreads, scoped by user_id. The server reads via a system principal (bypassing RLS) but enforces per-user scoping on user_id. No LLM invocation; open on every tier.
Creates or updates a single Analyze thread for the caller (the server stamps user_id from the bearer). The full thread payload (exchanges with artifacts + steps) is stored under the underscore-prefixed _exchanges blob field so a reload is a single round-trip and large payloads stay out of the index. 400 if id is missing; 500 on write failure. No LLM invocation; open on every tier.
Request
{
"id": "th_01",
"label": "Owner value analysis",
"created": "2026-06-20T14:03:00Z",
"exchanges": [
{
"question": "Top owners by market_value?",
"answer": "Ridgeline Holdings leads at $4.82M."
}
]
}
Response 200
{
"ok": true,
"id": "th_01"
}
DELETE/ai/threads/{id}BearerSOAR + Serverless
Deletes a single Analyze thread owned by the caller (ownership checked against user_id via the system principal). Always returns 200 with ok:true; a non-owned or missing id is a silent no-op. No LLM invocation; open on every tier.
Parameters
Name
In
Type
Description
id
path
string
Thread _id to delete (must be owned by the caller)
Response 200
{
"ok": true
}
LLM API (OpenAI-compatible) Mixed tier
OpenAI-compatible LLM API surface (/v1): chat completions proxied to the built-in model, model listing, and local MiniLM embeddings.
POST/v1/chat/completionsBearerSOAR only
Proxies an OpenAI-style chat request through the shared LlmClient (the same client the AI agent uses), which dispatches to the configured provider (Anthropic reshapes to /v1/messages; OpenAI / InventDB Gateway / llama-server keep the /v1/chat/completions shape). Requires the messages array; temperature defaults to 0.7. Because it invokes the built-in LLM it returns HTTP 403 on the Serverless Database tier. Returns an OpenAI chat.completion object (usage counters are zeroed). 403 on the Serverless tier (this route calls the built-in LLM).
Request
{
"messages": [
{
"role": "system",
"content": "You are a property-management assistant."
},
{
"role": "user",
"content": "Summarize the lease status for owner O-1001's properties."
}
],
"temperature": 0.7
}
Returns the configured external model in OpenAI list format. Reads model metadata from LlmRouter.external_config() and does NOT invoke the LLM, so it works on all tiers including Serverless.
Generates embeddings using the local all-MiniLM-L6-v2 runtime via LazyEmbeddingGenerator. Accepts a single string or an array of strings in the input field. This is the local embedding model (part of the serverless OCR+MiniLM carve-out), NOT the built-in chat/completion LLM, so it works on the Serverless tier. Returns 503 if the MiniLM model is not installed. Usage token counts are approximated by whitespace-split word count.
Request
{
"input": [
"Property P-5001 in Austin, TX with market_rent 2400",
"Owner O-1001 contact info"
]
}
Autonomous agent task management: list, inspect, cancel, and delete persisted long-running agent tasks (no LLM invoked; works on every tier).
GET/agent/tasksBearerSOAR + Serverless
Returns all persisted agent tasks owned by the authenticated user (scoped by claims.sub). Each task is a resumable, auditable record of a promoted 'full task mode' agent run — its state, steps, files created, iteration count, and token/time totals. Reads persisted records only; invokes no LLM, so it works on the Serverless Database tier.
Response 200
{
"tasks": [
{
"id": "3f2a9c14-7b0e-4d2a-9c1f-8e6b5a1d0042",
"chatTabId": "direct",
"chatMessageSeq": 0,
"owner": "developer.3@inventdb.com",
"ownerRole": "admin",
"title": "Analyze vacant units and market rent by city",
"goal": "Give me a full analysis of vacant properties and their market rent across cities",
"state": "Done",
"steps": [],
"filesCreated": [],
"variables": {},
"maxIterations": 50,
"iterationCount": 8,
"timeoutSeconds": 300,
"confirmationPolicy": "Always",
"createdAt": "2026-07-13T09:12:04Z",
"updatedAt": "2026-07-13T09:13:41Z",
"completedAt": "2026-07-13T09:13:41Z",
"totalLlmTokens": 18422,
"totalExecutionTimeMs": 96540
}
]
}
GET/agent/tasks/{id}BearerSOAR + Serverless
Returns the full AgentTask record for the given task id, including its complete step audit trail, task-scoped variables, and any files created. Access is restricted to the task owner or an admin/superadmin (403 otherwise); an unknown id returns 404. Reads a persisted record only; no LLM is invoked, so it works on the Serverless Database tier.
Parameters
Name
In
Type
Description
id
path
string
The task UUID (from the list endpoint's `id` field).
Response 200
{
"id": "3f2a9c14-7b0e-4d2a-9c1f-8e6b5a1d0042",
"chatTabId": "direct",
"chatMessageSeq": 0,
"owner": "developer.3@inventdb.com",
"ownerRole": "admin",
"title": "Analyze vacant units and market rent by city",
"goal": "Give me a full analysis of vacant properties and their market rent across cities",
"state": "Done",
"steps": [
{
"stepNumber": 1,
"toolName": "sql_query",
"input": {
"sql": "SELECT city, AVG(market_rent) FROM pms.properties WHERE status = 'vacant' GROUP BY city"
}
}
],
"filesCreated": [],
"variables": {},
"maxIterations": 50,
"iterationCount": 8,
"timeoutSeconds": 300,
"confirmationPolicy": "Always",
"createdAt": "2026-07-13T09:12:04Z",
"updatedAt": "2026-07-13T09:13:41Z",
"completedAt": "2026-07-13T09:13:41Z",
"totalLlmTokens": 18422,
"totalExecutionTimeMs": 96540
}
Marks the task as Cancelled and persists the change, stopping any further agent iterations for it. Restricted to the task owner or a superadmin (403 otherwise); an unknown id returns 404. This only flips persisted task state — it invokes no LLM and works on the Serverless Database tier.
Permanently deletes the persisted agent task record. Restricted to the task owner or a superadmin (403 otherwise); an unknown id returns 404. Deletes a stored record only; no LLM is invoked, so it works on the Serverless Database tier.
Per-user Gmail OAuth connect plus send, bulk-send, list, and read endpoints backed by stored refresh tokens.
GET/api/gmail/statusBearerSOAR + Serverless
Returns whether the authenticated user has connected Gmail, and if so the connected email address and the Unix-seconds timestamp of when the connection was made. Reads the stored token record from _system.user_integrations keyed by gmail:{username}; never touches the built-in LLM.
Returns the Google OAuth client_id and the requested Gmail scopes (gmail.send + gmail.readonly) plus a configured flag indicating whether the server has both client_id and client_secret resolved (from DbSettings google_oauth, env fallback). The browser uses this to initialize Google Identity Services initCodeClient. No LLM involved.
Accepts the one-shot authorization code obtained by the browser via Google Identity Services (ux_mode popup, redirect_uri=postmessage), exchanges it at Google's token endpoint for an access + refresh token pair, fetches the connected Gmail address, and persists the tokens (encrypted at rest) in _system.user_integrations. Returns 503 if OAuth is not configured, 400 if the exchange fails or Google returns no refresh token. Pure OAuth connect flow; no built-in LLM call.
Best-effort revokes the stored refresh token at Google's revoke endpoint, then always deletes the local token record from _system.user_integrations for the current user. Idempotent: returns ok:true even if no tokens were stored. No LLM involved.
Response 200
{
"ok": true
}
POST/api/gmail/sendBearerSOAR + Serverless
Sends one email through the user's connected Gmail. The RFC-2822 message is built server-side with an RFC 2047 encoded-word Subject and a deterministic Message-ID (<wf-<nonce>@inventdb.local>) for reply-thread correlation. Optional attachments reference existing InventDB attachments by namespace + attachment_id and are fetched from NativeAttachmentStore and MIME-embedded. When INVENTDB_DEMO_SAFE_EMAIL is set, recipients are overridden. Auto-refreshes the access token first (401 on failure), 503 if OAuth unconfigured, 502 on Gmail send failure. This is a direct Gmail API send, not an LLM call.
Request
{
"to": "owner@acme-pm.com",
"cc": [],
"bcc": [],
"subject": "Past Due — Lease L-7011 at 42 Elm St",
"body_html": "<p>Hi Jane, rent for P-5001 (market_rent $2,150) is past due.</p>",
"attachments": [
{
"namespace": "pms",
"attachment_id": "att-9f2c",
"filename": "statement-P-5001.pdf",
"content_type": "application/pdf"
}
]
}
Accepts an emails array (each a fully substituted SendEmailInput) and dispatches them serially through the connected Gmail account to stay under Gmail's per-user send quota. Refreshes the access token once for the whole batch and returns a per-row success/failure result so the UI can surface cell-by-cell status. 400 if the array is empty, 503 if OAuth unconfigured, 401 on token refresh failure. Each send is a direct Gmail API call; no LLM involved (the frontend already rendered the bodies).
Request
{
"emails": [
{
"to": "owner1@acme-pm.com",
"subject": "Rent reminder — P-5001",
"body_html": "<p>P-5001 market_rent $2,150 due for owner O-1001.</p>"
},
{
"to": "owner2@acme-pm.com",
"subject": "Rent reminder — P-5002",
"body_html": "<p>P-5002 market_rent $1,875 due for owner O-1002.</p>"
}
]
}
Lists recent messages from the connected Gmail account within the last `days` window, optionally filtered by a Gmail search query (from:, to:, subject:, etc.). Each result carries decoded headers (RFC 2047 + mojibake-repaired), snippet, full decoded body (text/plain preferred, HTML stripped to plain), and correlation headers (rfc_message_id, in_reply_to, references). days is clamped 1-365, max clamped 1-50. Auto-refreshes token; 503 if OAuth unconfigured, 401 on refresh failure, 502 on Gmail list failure. Read-only Gmail API access; no LLM.
Parameters
Name
In
Type
Description
days
query
integer
Look-back window in days (default 7, clamped 1-365)
q
query
string
Optional Gmail search query appended to newer_than filter (e.g. from:owner@acme-pm.com)
max
query
integer
Max messages to fetch (default 20, clamped 1-50)
Response 200
[
{
"id": "18f3a2b9c1d4e5f6",
"thread_id": "18f3a2b9c1d4e5f6",
"from": "owner@acme-pm.com",
"to": "manager@acme-pm.com",
"subject": "Re: Past Due — Lease L-7011",
"date": "2026-06-20T14:03:00-07:00",
"snippet": "I can pay by Friday for P-5001...",
"body": "I can pay by Friday for P-5001. Please confirm the amount.",
"rfc_message_id": "<CAF123@mail.gmail.com>",
"in_reply_to": "<wf-1749600000123456789@inventdb.local>"
}
]
Fetches a single message by Gmail id (format=full), returning meta (headers, snippet, decoded body) plus separate body_text and body_html fields. Used by the expand action on the EmailSummaryCard. Auto-refreshes token; 503 if OAuth unconfigured, 401 on refresh failure, 502 on Gmail get failure. Read-only Gmail API access; no LLM.
Parameters
Name
In
Type
Description
id
path
string
Gmail internal message id
Response 200
{
"meta": {
"id": "18f3a2b9c1d4e5f6",
"thread_id": "18f3a2b9c1d4e5f6",
"from": "owner@acme-pm.com",
"to": "manager@acme-pm.com",
"subject": "Re: Past Due — Lease L-7011",
"date": "2026-06-20T14:03:00-07:00",
"snippet": "I can pay by Friday for P-5001...",
"body": "I can pay by Friday for P-5001. Please confirm the amount.",
"in_reply_to": "<wf-1749600000123456789@inventdb.local>"
},
"body_text": "I can pay by Friday for P-5001. Please confirm the amount.",
"body_html": "<div>I can pay by Friday for P-5001. Please confirm the amount.</div>"
}
Calendar Integration Any tier
Google Calendar integration — per-user OAuth connect plus list/create/update/delete events and free/busy; no built-in LLM involved.
GET/api/calendar/statusBearerSOAR + Serverless
Returns whether the authenticated user has a stored Google Calendar OAuth grant. When connected, includes the user's primary calendar email and the connect timestamp (unix seconds). Reads token record `_system.user_integrations` keyed by `gcal:{username}`. No LLM.
Returns the server-side Google OAuth client_id and requested Calendar scopes so the frontend can launch the consent popup. `configured` is false when no Google OAuth client is set (via DbSettings google_oauth or GOOGLE_OAUTH_*/GMAIL_OAUTH_* env). The OAuth client is shared with Gmail. No LLM.
Exchanges the OAuth `code` (from the postmessage popup flow) for tokens at Google, captures the primary calendar email, and persists a per-user CalendarTokens record keyed by `gcal:{username}`. Returns 503 when Google OAuth is not configured, and 400 when the exchange fails or Google returns no refresh_token (needs access_type=offline + prompt=consent). No LLM.
Best-effort revokes the stored refresh token at Google's revoke endpoint and deletes the local CalendarTokens record for the user. Always returns ok:true. No LLM.
Response 200
{
"ok": true
}
GET/api/calendar/calendarsBearerSOAR + Serverless
Refreshes the access token if needed, then lists the user's calendars (minAccessRole=writer, up to 50) via Google's calendarList API. Returns 503 if OAuth not configured, 401 if Calendar not connected / token refresh fails, 502 on upstream Google errors. No LLM.
Lists events for a calendar (defaults to `primary`) between timeMin and timeMax (RFC 3339), expanding recurrences (singleEvents=true) and ordering by start time. Optional free-text `q` filter and `max` cap (1..250, default 50). Returns 503 if OAuth not configured, 401 if not connected, 502 on Google errors. No LLM.
Creates an event on the target calendar (defaults to `primary`), supporting timed or all-day events, IANA time_zone, attendees (sendUpdates=all so Google emails invites), and optional Google Meet link (add_meet). Under demo-safe mode all attendee addresses are rewritten to the configured safe address. Returns 503 if OAuth not configured, 401 if not connected, 502 on Google errors. No LLM.
Partially updates an event by id on the target calendar (defaults to `primary`). Any of summary/description/location/attendees may be set; start and end must be supplied together (Google rejects only-one) and all_day toggles date vs dateTime shapes. sendUpdates=all notifies attendees. Returns 503 if OAuth not configured, 401 if not connected, 502 on Google errors. No LLM.
Deletes an event by id from the target calendar (defaults to `primary`); sendUpdates=all cancels the invite for attendees. A Google 410 Gone (already deleted) is treated as success. Returns 503 if OAuth not configured, 401 if not connected, 502 on other Google errors. No LLM.
Creates a list of pre-rendered events sequentially against the user's calendar (sequential to respect Google's per-user write throttling). Returns per-item results with saved/failed counts. Rejects an empty events array with 400. Returns 503 if OAuth not configured, 401 if not connected. Each event uses the same CreateEventInput shape as POST /events. No LLM.
Bring-your-own-Twilio SMS integration: per-user credential storage, number listing, single/bulk SMS send, message history, and a public signature-verified inbound webhook.
GET/api/twilio/statusBearerSOAR + Serverless
Returns whether the authenticated user has stored Twilio credentials, along with the connected Account SID, Twilio friendly name, default 'From' number, whether an auth token is present (needed for webhook signature verification), and the connection timestamp. When not connected, all fields are null/false. No LLM involved.
Persists the user's Twilio credentials (encrypt-stored in _system.user_integrations keyed by twilio:{username}). Requires account_sid (must start with 'AC' and be 34 chars) plus EITHER an auth_token OR an api_key_sid+api_key_secret pair. Credentials are validated live against GET /Accounts/{SID}.json before persisting; a 401 is returned if Twilio rejects them. A previously-configured default_from is preserved across re-saves. Returns the same shape as /status. Configures an external provider (Twilio), not the built-in LLM.
Deletes the current user's stored Twilio credentials from _system.user_integrations. Idempotent — always returns ok:true. No LLM involved.
Response 200
{
"ok": true
}
GET/api/twilio/numbersBearerSOAR + Serverless
Fetches up to 50 IncomingPhoneNumbers from the user's Twilio account (GET /Accounts/{SID}/IncomingPhoneNumbers.json), returning each number's SID, E.164 phone number, friendly name, and whether it is SMS-capable. Returns 401 if Twilio is not connected, 502 if the Twilio API call fails. No LLM involved.
Sets the default outbound 'From' number used by /send and /bulk-send when a message omits an explicit 'from'. Persists to the user's stored credentials. Returns 401 if Twilio is not connected. No LLM involved.
Request
{
"phone_number": "+18885550100"
}
Response 200
{
"ok": true,
"default_from": "+18885550100"
}
POST/api/twilio/sendBearerSOAR + Serverless
Sends one SMS via the user's Twilio account (POST /Accounts/{SID}/Messages.json). Body requires 'to' and 'body'; 'from' is optional and falls back to the stored default_from (error if neither is set). Returns the Twilio message SID, delivery status, resolved to/from numbers, and segment count. Returns 401 if not connected, 502 on Twilio API failure. Uses the external Twilio API, not the built-in LLM — works on serverless.
Request
{
"to": "+14155550188",
"from": "+18885550100",
"body": "Reminder: rent for P-5001 (Austin, TX) is due. Balance $2450."
}
Sends an array of SMS messages sequentially, each with its own to/body/optional from. Returns per-message results (ok flag, SID or error, segment count) plus aggregate sent/failed counts. Returns 400 if the messages array is empty, 401 if not connected. Individual message failures are captured in the results array rather than failing the whole request. External Twilio API, no built-in LLM — works on serverless.
Request
{
"messages": [
{
"to": "+14155550188",
"body": "Rent reminder for owner O-1001."
},
{
"to": "+14155550190",
"from": "+18885550100",
"body": "Work order update for P-5001."
}
]
}
Lists recent messages from the user's Twilio account (GET /Accounts/{SID}/Messages.json), filtered by a rolling day window and optional from/to numbers. Returns SID, direction, from/to, body, status, date_sent, segment count, and price/price_unit per message. Returns 401 if not connected, 502 on Twilio failure. No built-in LLM — works on serverless.
Parameters
Name
In
Type
Description
days
query
integer
Rolling window of days to look back (DateSent>=). Defaults to 7; minimum enforced as 1.
from
query
string
Optional filter — only messages sent from this E.164 number.
to
query
string
Optional filter — only messages sent to this E.164 number.
max
query
integer
Max rows to fetch (PageSize). Defaults to 50; clamped to 1..=100.
Public route (no JWT) that Twilio POSTs as application/x-www-form-urlencoded when one of the user's numbers receives an SMS. The user is identified via the AccountSid form field; the X-Twilio-Signature header is verified with HMAC-SHA1 over the full request URL plus sorted params keyed by the user's auth_token (honouring X-Forwarded-Proto/Host for reverse-proxy setups). On success a stripped record (account_sid, message_sid, from, to, body, num_segments, num_media, received_at, username) is persisted to _system.twilio_incoming as an audit/compliance log and an empty TwiML-equivalent 200 is returned. Missing AccountSid => 400; unknown account => 404; signature mismatch => 401. No built-in LLM involved.
Per-user opt-in toggle for the AI agent's hosted web-search tool (Anthropic web_search_20250305).
GET/api/websearch/statusBearerSOAR + Serverless
Returns whether the AI agent's hosted web-search tool is enabled for the authenticated user, plus whether they have acknowledged the data-leaves-tenant consent dialog and when. Reads a single per-user document from _system.user_integrations keyed by websearch:{username}; if none exists, returns enabled=false/consented=false. Pure settings read — does not invoke the built-in LLM, so it works on the Serverless tier.
Turns on the opt-in web-search integration for the authenticated user. Sets enabled=true on the per-user _system.user_integrations document (creating it if absent). Records the consent timestamp the first time it is enabled and preserves that timestamp across later disable/re-enable cycles so the consent dialog is not re-shown. This only flips a settings flag that the agent loop later reads to decide whether to append the hosted web_search_20250305 tool; the route itself does not call the built-in LLM, so it works on the Serverless tier.
Turns off the web-search integration for the authenticated user by setting enabled=false on the per-user _system.user_integrations document. The original consent timestamp is preserved so the user is not re-prompted if they re-enable later. Settings-write only — does not invoke the built-in LLM, so it works on the Serverless tier.
Request
{}
Response 200
{
"ok": true,
"enabled": false
}
AI Usage Metrics Any tier
Read-only AI usage/cost analytics, per-user/type/model breakdowns, quota management, and Chorus plan-cache savings — no LLM invoked, so it works on the Serverless tier (reports zero AI usage).
GET/api/ai-metrics/usageBearerSOAR + Serverless
Rolls up _system.AIUsage into a single period summary: request count, input/output/cached token totals, cache hit rate, average latency, and USD cost rollups (total/input/output). Reports mode 'local' or 'external' depending on whether a local LLM router is registered. Aggregation is done in Rust (GROUP BY model, no WHERE) to sidestep a known WHERE+SUM engine bug, so the period param is accepted but not yet filtered. Read-only reporting; invokes no LLM, works on serverless (reports zeros).
Parameters
Name
In
Type
Description
period
query
string
Lookback window token, e.g. 30d, 7d, 24h. Defaults to 30d. Currently echoed in the response but not applied to filtering.
Returns a per-day series (bucketed by the YYYY-MM-DD prefix of _createdAt) of request count, input/output/cached tokens, average latency, and total USD cost. Raw rows are fetched and aggregated in Rust because GROUP BY with scalar functions plus SUM hits a known engine bug. Read-only reporting; no LLM, works on serverless.
Parameters
Name
In
Type
Description
period
query
string
Lookback window token (30d/7d/24h). Defaults to 30d; echoed back but not applied to filtering.
Returns one row per model from _system.AIUsage (GROUP BY model): request count, input/output/cached token sums, total USD cost (rounded to 4 decimals) and average latency. Read-only reporting; no LLM, works on serverless.
Parameters
Name
In
Type
Description
period
query
string
Lookback window token; defaults to 30d, echoed but not applied to filtering.
Lightweight health probe reporting whether a local LLM is available and the resulting mode ('local' vs 'external'). Does not query any table and does not invoke the LLM; works on serverless.
Same summary shape as /usage but sourced from the gateway's central AIGateway.Usage ledger, scoped to the calling customer via WHERE clientId = <jwt.sub> (RLS-enforced). Rows are post-filtered by the period threshold in memory and cost is computed on-read from the pricing rate cache. Missing table / RLS-deny degrades to zeroed metrics rather than a 500. Read-only reporting; no LLM, works on serverless.
Parameters
Name
In
Type
Description
period
query
string
Window token: 24h/1d, 7d, 30d, 90d. Unrecognized tokens fall back to all-time. Defaults to 30d.
Daily series (bucketed by the YYYY-MM-DD prefix of the gateway's rfc3339 timestamp) from AIGateway.Usage, scoped to the calling customer via clientId and post-filtered by the period threshold. Cost computed on-read from the pricing cache. Missing table degrades to an empty series. Read-only reporting; no LLM, works on serverless.
Parameters
Name
In
Type
Description
period
query
string
Window token: 24h/1d, 7d, 30d, 90d. Defaults to 30d; unrecognized falls back to all-time.
Per-model breakdown that, despite the name, reads THIS instance's own _system.AIUsage ledger (AIGateway.Usage is not written on a SOAR/customer instance). Raw (provider,model) variants are folded into one friendly model name; each row carries request count, token sums, average latency, total USD cost, and a 4-lever breakdown (Input / Cache read / Cache write / Output with tokens, per-1M rate, and subtotal). Sorted highest-spend first. Read-only reporting; no LLM, works on serverless.
Parameters
Name
In
Type
Description
period
query
string
Window token: 24h/1d, 7d, 30d, 90d. When recognized it applies a WHERE timestamp >= threshold filter; otherwise all-time. Defaults to 30d.
Returns AI quota status from the quota subsystem. Admin/superadmin callers see full config (global + per-user limits), today's usage totals, and by-user / by-type breakdowns. Non-admins get a redacted view: global limit knobs and global totals are stripped, top-level quota-pct fields removed, byUser filtered to the caller's own row, and byType dropped. Read-only; no LLM, works on serverless.
Updates the global and per-user daily request/token limits and the enabled flag. Admin/superadmin only — returns 403 for any other role so a user with a domain write grant cannot raise their own AI limits. Returns the applied config. No LLM invoked; works on serverless.
Resets the current day's AI quota counter. Admin/superadmin only — returns 403 otherwise so a user cannot zero out their own usage to bypass the per-user cap. No LLM invoked; works on serverless.
Aggregates _system.AIUsage per database user in Rust: request count, input/output/cached tokens, total tokens (input+output) and average latency. Read-only reporting; no LLM, works on serverless.
Parameters
Name
In
Type
Description
period
query
string
Lookback window token; defaults to 30d, echoed but not applied to filtering.
Aggregates _system.AIUsage per usageType (e.g. chat, report, extract) in Rust: request count, input/output/cached tokens, total tokens and average latency. Read-only reporting; no LLM, works on serverless.
Parameters
Name
In
Type
Description
period
query
string
Lookback window token; defaults to 30d, echoed but not applied to filtering.
Detailed analytics for THIS instance from _system.AIUsage (SELECT * LIMIT 200000, filtered by timestamp prefix in Rust). Default mode returns period totals (requests, tokens, cache hit rate, avg latency, success rate, dollars), a daily series, and byModel / byOperation / byUser / byProvider buckets, plus the current-month AI $ allowance from the cmgmt account cache (null on standalone instances). With ?day=YYYY-MM-DD it returns that day's per-request rows (newest first). With ?view=events it returns a filterable, paged event feed. Read-only reporting; no LLM, works on serverless.
Parameters
Name
In
Type
Description
month
query
string
Month window YYYY-MM. Defaults to the current UTC month.
day
query
string
Day drill-down YYYY-MM-DD; returns that day's per-request rows newest-first instead of the aggregate.
view
query
string
Set to 'events' for the month-scoped filterable/paged per-request event feed.
model
query
string
events view: exact-match filter on friendly model name.
provider
query
string
events view: exact-match filter on friendly provider name.
user
query
string
events view: exact-match filter on database user.
op
query
string
events view: exact-match filter on usageType/operation.
page
query
integer
events view: zero-based page index. Defaults to 0.
size
query
integer
events view: page size, clamped 1..500. Defaults to 50.
Computes the Chorus (semantic plan cache) funnel and measured savings entirely from _system.ChorusMetrics + _system.AIUsage with no hardcoded rates. Returns hit/agent-turn counts and hit-rate, the outcome funnel, chorus wall-time and priced extraction actuals (endpoint=chorus-extract), and for each observed default-model family a measured 'what those hits would have cost' comparison (avg agent-turn ms/tokens/cost plus time/tokens/cost saved). ChorusMetrics is absent until the first Chorus decision, degrading to zeros. Read-only reporting; no LLM, works on serverless.
Persist a data-viewer card (its SQL + display config) as a reusable, listable Saved View, with deterministic custom-layout rendering and optional AI layout generation.
POST/api/saved-viewsBearerSOAR + Serverless
Persists a data-viewer card as a `_System.SavedViews` document: its authoritative `baseSql` plus display config (defaultMode, custom layout template link, attachment/search flags, column order, live browse filter, and the Ask-AI conversation that produced the SQL). `createdBy` is taken from the caller's JWT and `version` is forced to 1. Returns the stored document. Deterministic CRUD — no LLM — so it works on the Serverless tier.
Request
{
"name": "Active Vacant Properties",
"description": "Vacant units ordered by market rent",
"namespace": "pms",
"baseSql": "SELECT property_id, city, state, market_rent, status, beds, baths FROM pms.properties WHERE status = 'vacant' ORDER BY market_rent DESC",
"defaultMode": "table",
"attachmentsEnabled": false,
"searchAttachments": false,
"columns": [
"property_id",
"city",
"state",
"market_rent",
"status"
],
"search": "vacant",
"sort": {
"col": "market_rent",
"dir": "desc"
},
"tags": [
"properties",
"vacancy"
]
}
Response 201
{
"ok": true,
"data": {
"_id": "view_9f2a1c",
"name": "Active Vacant Properties",
"description": "Vacant units ordered by market rent",
"namespace": "pms",
"baseSql": "SELECT property_id, city, state, market_rent, status, beds, baths FROM pms.properties WHERE status = 'vacant' ORDER BY market_rent DESC",
"defaultMode": "table",
"customScope": "row",
"attachmentsEnabled": false,
"searchAttachments": false,
"columns": [
"property_id",
"city",
"state",
"market_rent",
"status"
],
"search": "vacant",
"sort": {
"col": "market_rent",
"dir": "desc"
},
"version": 1,
"createdBy": "u_1001",
"tags": [
"properties",
"vacancy"
]
}
}
GET/api/saved-viewsBearerSOAR + Serverless
Lists all saved views (summary columns only: _id, name, description, namespace, defaultMode, attachmentsEnabled, version, createdBy) ordered by name, capped at 1000. Deterministic read — no LLM — works on the Serverless tier.
Fetches one saved view's full document by id. Returns 404 when the id does not exist. Deterministic read — no LLM — works on the Serverless tier.
Parameters
Name
In
Type
Description
id
path
string
The saved view's _id (e.g. view_9f2a1c).
Response 200
{
"ok": true,
"data": {
"name": "Active Vacant Properties",
"description": "Vacant units ordered by market rent",
"namespace": "pms",
"baseSql": "SELECT property_id, city, state, market_rent, status, beds, baths FROM pms.properties WHERE status = 'vacant' ORDER BY market_rent DESC",
"defaultMode": "table",
"customScope": "row",
"attachmentsEnabled": false,
"searchAttachments": false,
"columns": [
"property_id",
"city"
],
"search": "vacant",
"sort": {
"col": "market_rent",
"dir": "desc"
},
"version": 1,
"createdBy": "a9b4e239-27ff-4f38-949b-38b332b3f8ed",
"tags": [
"properties",
"vacancy"
],
"_id": "5a1fcac6-7089-416a-aef3-57b7c73147ed",
"_createdAt": "2026-07-13T15:57:13.185793800+00:00",
"_updatedAt": "2026-07-13T15:57:13.185793800+00:00",
"_createdBy": "a9b4e239-27ff-4f38-949b-38b332b3f8ed"
}
}
PUT/api/saved-views/{id}BearerSOAR + Serverless
Shallow-merges the JSON body into the existing saved-view document (any subset of fields), ignoring the immutable `_id`, `_createdAt`, and `createdBy` keys, and auto-increments `version`. Returns 404 if the view is missing. Deterministic mutation — no LLM — works on the Serverless tier.
Renders a view's custom (non-table) card layout for a single page. Windows `baseSql` server-side via the engine parser (no client SQL surgery), loads the linked `_System.ReportTemplates` template, runs it over that page with `params.viewSql` set to the windowed SQL, and returns `{ html, total, page, pageSize }` where `total` is the real full row count for accurate paging. Pure report-engine rendering with no model in the path — works on the Serverless tier (an AI-authored template renders with no LLM).
Request
{
"templateId": "tpl_7c33",
"baseSql": "SELECT property_id, city, state, market_rent, status, beds, baths FROM pms.properties WHERE status = 'vacant' ORDER BY market_rent DESC",
"page": 0,
"pageSize": 25
}
POST/api/saved-views/generate-layoutBearerSOAR only
Invokes the built-in LLM to produce report-engine HTML for a view's custom (non-table) card layout. Fresh generation designs a card layout from the schema + sample records; when `currentHtml` is supplied it EDITS that design applying only `instruction` (with `history` as context). Attached `pendingIds` (from /ai/uploads/stage) are passed as vision inputs (images, e.g. a mockup) or inlined text. The HTML reads its rows from `query(params.viewSql)` and may embed a leading `<!--VIEWSQL: SELECT … -->` directive; the response returns `{ html, sql }` (sql falls back to baseSql). This route calls the built-in LLM, so it returns HTTP 403 on the Serverless Database tier. 403 on the Serverless tier (this route calls the built-in LLM).
Request
{
"baseSql": "SELECT property_id, city, state, market_rent, status, beds, baths, sqft FROM pms.properties",
"namespace": "pms",
"instruction": "Property cards showing photo, city, beds/baths and rent, highest sqft first",
"modelFamily": "claude"
}
Response 200
{
"html": "<style>…</style><script type=\"server\">const r = query(params.viewSql); for (const row of r.rows) { out.write(`<div class=\"card\" data-surface=\"flat\" data-record-id=\"${esc(String(row._id))}\">…${esc(row.city)}…${fmt.currency(row.market_rent)}…</div>`); }</script>",
"sql": "SELECT * FROM pms.properties ORDER BY sqft DESC"
}
Forms Any tier
Schema-driven data-entry form engine: analyze a type's schema, build/store HTML form templates, render forms with FK typeahead lookups, run SQL validation rules, and submit records (create/update).
Samples records from the given namespace/type (default 100 rows) to infer each property's data type, FK targets (fields ending in _id whose target type exists), FK display fields, cascade relationships (e.g. unit_id cascades from property_id), and enum-like fields (2-20 distinct values). Returns the inferred property list, the type's display field, and total record count. Used by an external AI agent to design a form template; the route itself runs no LLM.
Parameters
Name
In
Type
Description
namespace
path
string
Namespace (database) name, e.g. 'pms'
type_name
path
string
Type (table) name, e.g. 'properties'
sample_size
query
integer
Number of records to sample for schema inference (default 100)
Searches a target type for a searchable FK picker. Matches the query against the detected display field(s) and _id via LIKE, optionally constrained by a cascade filter (filter=field:value). Returns up to 'limit' items (default 20, capped 200), each with _id, a composed display string, and the full record. No LLM involved.
Parameters
Name
In
Type
Description
namespace
path
string
Namespace (database) name, e.g. 'pms'
type_name
path
string
Target type to search, e.g. 'owners'
q
query
string
Search text matched against display field(s) and _id
filter
query
string
Cascade filter in the form field:value, e.g. 'property_id:P-5001'
Inserts a new form template into _System.FormTemplates with the supplied name, target namespace/type, HTML template body (with {{field:*}}, {{lookup:*}}, {{validate:*}} placeholders), bindings, and style. Stamps status='active', version=1, and created_by from the caller's claims. The template body is typically authored by an external AI agent; this route runs no LLM. Returns 201 with the new record id.
Loads the template, resolves {{field}}, {{lookup}}, {{section}}, {{row}}, {{hidden}}, {{validate}} placeholders into inputs, and returns a self-contained HTML page (embedded CSS + FormEngine JS) for creating a new record. Content-Type text/html. No LLM.
Parameters
Name
In
Type
Description
id
path
string
Form template record id
Response 200
<!DOCTYPE html><html lang="en">... New Property form ...</html>
Same as render but loads the target record (namespace/type from the template) and pre-fills inputs and lookup chips for editing. Submit label becomes 'Save Changes'. Returns a self-contained HTML page. No LLM.
Parameters
Name
In
Type
Description
id
path
string
Form template record id
record_id
path
string
Id of the record to edit, e.g. 'P-5001'
Response 200
<!DOCTYPE html><html lang="en">... Editing properties record P-5001 ...</html>
POST/forms/validateBearerSOAR + Serverless
Substitutes :param placeholders in the supplied SQL with values from params (single-quote escaped), executes it against the database, and returns the resulting rows and count. Used by the form engine to enforce {{validate:*}} rules before submit. Executes SQL only; no LLM.
Request
{
"sql": "SELECT COUNT(*) AS c FROM pms.properties WHERE property_id = :property_id",
"params": {
"property_id": "P-5001"
}
}
Resolves the template's target namespace/type, stamps created_by and modified_by from the caller's claims, and inserts the submitted data as a new record. Returns 201 with the new id. No LLM.
Resolves the template's target namespace/type, stamps modified_by from the caller's claims, and updates the identified record with the submitted data. Returns 200 with the record id. No LLM.
Parameters
Name
In
Type
Description
id
path
string
Form template record id
record_id
path
string
Id of the record to update, e.g. 'P-5001'
Request
{
"market_rent": 2600,
"status": "occupied"
}
Response 200
{
"ok": true,
"id": "P-5001"
}
Transactions Any tier
Multi-statement ACID transaction lifecycle: begin, execute buffered CRUD/SQL operations, then commit or rollback.
POST/txBearerSOAR + Serverless
Opens a new server-side transaction and returns its generated transaction id. Subsequent execute/commit/rollback calls reference this id. No LLM involved.
Durably commits all buffered operations for the given transaction id. Returns 200 on success or 400 with an error message if the commit fails (e.g. conflict or unknown/expired txId). No LLM involved.
Parameters
Name
In
Type
Description
txId
path
string
Transaction id returned by POST /tx
Response 200
{
"ok": true
}
POST/tx/{txId}/rollbackBearerSOAR + Serverless
Discards all buffered operations for the given transaction id and releases it. Always returns 200 ok (rollback is idempotent/best-effort). No LLM involved.
Parameters
Name
In
Type
Description
txId
path
string
Transaction id returned by POST /tx
Response 200
{
"ok": true
}
POST/tx/{txId}/executeBearerSOAR + Serverless
Runs a single operation within the open transaction. The request body is tagged by an 'operation' discriminator: insert, update, delete, get, or query. insert/update run referential-integrity validation (returns 409 on RI violation); delete runs RI-for-delete validation (409 on violation). update/delete/get return 404 when the target document does not exist. query runs SQL within the transaction and returns the result rows array. Response carries ExecuteResponse { ok, data, id, error }; success uses HTTP 201 for insert and 200 for update/delete/get/query. No LLM involved — plain buffered CRUD/SQL.
Instance-native account card: who the caller is plus this instance's company, plan tier, and live AI-dollar allowance in one call.
GET/api/account/summaryBearerSOAR + Serverless
Returns, in a single call, the calling user's identity plus the company, plan tier, and live AI-dollar allowance for THIS instance so the SOAR profile card and the Console settings page can show company/tier/credits without deep-linking back to the customer portal. The 'user' block is resolved from the caller's own _system.users row (self-introspection pinned to _id = JWT subject under a system principal), falling back to claims-only data for service-account subjects with no row. The 'customer' and 'allowance' blocks come from the cmgmt_account poller cache (HMAC-signed hourly pull from cmgmt); both serialize as null on a STANDALONE instance with no cmgmt configured, and the frontends degrade to user-only. NOT AI-gated: serverless instances still surface user + company + plan (the allowance just stays null/empty there since serverless has no built-in LLM budget). Auth-protected by the global AuthMiddleware (Bearer JWT).
Admin CRUD for users, per-user/role permissions (RBAC grants + row-level filters), and named/app-scoped roles.
GET/api/usersBearerSOAR + Serverless
List all users from _system.users. Admin only. Returns a flat JSON array of user objects directly (C#-API compatible, not wrapped). Supports optional activeOnly and search (username/email substring, case-insensitive) query filters.
Parameters
Name
In
Type
Description
activeOnly
query
boolean
When true, only users with is_active=true are returned.
search
query
string
Case-insensitive substring match on username or email.
Create a new user in _system.users. Admin only. Hashes the password, generates a UUID _id, defaults role to 'reader'. 409 if the username already exists; 400 if username is empty or >64 chars. Returns the created user wrapped in {ok,user}.
Fetch one user by _id, or by username as a fallback (the Console passes the username). Admin only. Returns {ok,user}; 404 when neither _id nor username matches.
Update a user's email, role, and/or password (any subset). Admin only. Password is re-hashed if supplied. Returns the updated user in {ok,user}; 404 if not found.
Change the user's global (JWT primary) role. Admin only. Valid roles: reader, writer, analyst, admin, superadmin. Only a superadmin may grant the superadmin role (403 otherwise); invalid role => 400. Returns {ok,user}.
Set app_roles[<app>]=<role> on a user (dynamic-roles design). Admin only. Validates that (app, role) exists in _system.roles; '_global' is rejected as an app (400). Returns {ok,user}; 404 if the user is not found.
Parameters
Name
In
Type
Description
userId
path
string
User _id.
app
path
string
App id whose role catalog the role belongs to (e.g. inventdb-tenantry).
Check whether the CURRENT user has a given access level on a resource. Admin/superadmin short-circuit to has_permission=true. Delegates to the same rbac helpers the enforcement middleware uses (direct grants + role grants, case-insensitive, access-level hierarchy) so the UI never shows buttons that 403 on click. resource is either 'ns' or 'ns.type'.
Parameters
Name
In
Type
Description
resource
query
string
Namespace ('pms') or fully-qualified type ('pms.properties').
level
query
string
Access level to test: read|write|delete|admin (case-insensitive).
Return the flat array of direct permission grants for a user (Archivus-compatible shape). Admin only. Accepts username or _id in the path; storage is keyed by resolved _id. Enriches each grant with grantedByUsername (batched _id->username lookup). Returns [] when the user has no grants.
Grant a direct permission to a user. Admin only. accessLevel must be read|write|admin (400 otherwise); target user must exist (404, except the 'superadmin' pseudo-user). Optional rowFilter (v1 DSL) and rowFilterSql (v2 SQL) scope the grant to a row subset. Returns 201 with the created permission.
Revoke a single grant from a user by permission _id. Admin only. 404 if the user has no permissions doc or the permissionId is not present. Returns 204 No Content on success.
Parameters
Name
In
Type
Description
username
path
string
Username or _id of the subject user.
permissionId
path
string
The _id of the grant to revoke.
Response 204
GET/api/rolesBearerSOAR + Serverless
List all role records from _system.roles (legacy bundle-named + app-scoped). Admin only. Returns {ok:true,data:[Role]}.
Create a legacy bundle-named role (_id = name; users opt in via roles[]). Admin only. Validates the name (1-64 chars, [A-Za-z0-9_-:], not a reserved name), every grant, and any rowFilter. 409 if the name already exists or is bundle-owned. Returns {ok:true,data:Role}.
Request
{
"name": "pms:owner",
"description": "Owner sees only their own properties",
"grants": [
{
"scope": "type",
"resource": "pms.properties",
"accessLevel": "read",
"rowFilter": "owner_id = :current_user"
}
]
}
Fetch one role by bare name (e.g. 'analyst', resolves the seeded role__global_<name> doc) or by fully-qualified internal _id. Admin only. Returns {ok:true,data:Role}; 404 if not found.
Delete a user-owned legacy role. Admin only. Refuses built-in roles (403) and bundle-owned roles (409). By default 409s if any users still carry the role in roles[] (lists them); pass ?force=true to auto-detach from all users first. Returns {ok:true}.
Parameters
Name
In
Type
Description
name
path
string
Role _id/name to delete.
force
query
boolean
When true, detach the role from every user first, then delete.
Attach one role to many users in a single admin call (idempotent). Provide exactly one of userIds (explicit _id list) or whereSql (a WHERE-clause body run as SELECT _id FROM _system.users WHERE <whereSql> under a system principal). 404 if the role does not exist; 400 if neither/both selectors given. Returns counts of attached/skipped plus per-user errors.
Attach a single legacy role to one user (adds to roles[], idempotent). Admin only. Accepts username or _id in the path. 404 if the role or user is not found. Returns {ok:true,data:{username,roles}}.
Remove a single legacy role from a user's roles[] array. Admin only. Accepts username or _id in the path; no-op if the user or role is absent. Returns {ok:true}.
Parameters
Name
In
Type
Description
username
path
string
Username or _id of the target user.
role
path
string
Role name to detach.
Response 200
{
"ok": true
}
Vectors (per-property) Any tier
Admin-only management of per-property and per-segment (universal HNSW) vector embeddings: inspect, (re)generate, backfill, and delete MiniLM embeddings.
Returns every property that has a vector (distinct-value) embedding index for the given namespace/type, plus per-property vector count, source property, embedding dimension (384 for all-MiniLM-L6-v2), on-disk file size, and last rebuild time. Also returns the type's total record count. Admin/superadmin only (403 otherwise). Vector embeddings use the local MiniLM model, not the built-in chat LLM, so this works on the Serverless tier.
Samples one document from the type and returns every non-system string property (skips names starting with '_', ending in 'Id', or equal to 'id') as a candidate for vectorization, flagging which ones already have an embedding index and their current embedding count. Also returns the total record count. Admin/superadmin only (403 otherwise). Returns 404 if the type does not exist. No built-in LLM involved.
Builds the distinct-value MiniLM embedding cache + HNSW index for a single property and streams progress as Server-Sent Events. Append-only (incremental) by default; pass ?force=true to wipe and rebuild from scratch. Accepts an optional ?token query param so an EventSource (which cannot set Authorization headers) can authenticate. Each SSE 'message' event carries a VectorRegenerationProgress JSON payload (status regenerating/completed/failed, totalRecords=distinct count, processedRecords=cached count, progressPercentage, timestamps, elapsedMs); a final 'done' event closes the stream. Admin/superadmin only (a non-admin caller receives a failed progress event, not an HTTP 403). Uses the local MiniLM embedder, not the built-in chat LLM.
Parameters
Name
In
Type
Description
namespace
path
string
Namespace (database) name, e.g. 'pms'.
type
path
string
Type (table) name, e.g. 'properties'.
property
path
string
Property to embed, e.g. 'city'.
token
query
string
Optional bearer token for EventSource auth (used in place of the Authorization header).
force
query
boolean
If true, wipe the existing cache and rebuild from scratch. Default false (incremental append-only build).
Returns the last-known VectorRegenerationProgress for a property's embedding build from the in-memory progress tracker; if no build has been tracked it returns an 'idle' snapshot. Used to poll batch regenerations that don't stream SSE. Always HTTP 200 (a non-admin caller gets status 'error' with error_message 'Admin access required' in the body, not an HTTP 403). No built-in LLM involved.
Parameters
Name
In
Type
Description
namespace
path
string
Namespace (database) name, e.g. 'pms'.
type
path
string
Type (table) name, e.g. 'properties'.
property
path
string
Property whose build progress is queried, e.g. 'city'.
Deletes the distinct-value embedding cache file for a single property. Returns ok=true with vectorsDeleted=1 when a cache existed, ok=true with vectorsDeleted=0 when none existed, and 500 on I/O failure. Admin/superadmin only (403 otherwise). No built-in LLM involved.
Parameters
Name
In
Type
Description
namespace
path
string
Namespace (database) name, e.g. 'pms'.
type
path
string
Type (table) name, e.g. 'properties'.
property
path
string
Property whose embedding cache to delete, e.g. 'city'.
Queues incremental (append-only) embedding rebuilds for a list of properties, spawning a background build per property (skips any already regenerating). Returns immediately with the list of queued properties; poll the per-property /progress endpoint to track completion. Returns 400 if the properties list is empty. Admin/superadmin only (403 otherwise). Uses the local MiniLM embedder, not the built-in chat LLM.
Marks every sealed segment of the given type vectors_pending and runs the backfill synchronously, rebuilding all per-segment HNSW vector indexes for that type. Returns the namespace/type, segments processed, and elapsed time; 500 if the rebuild task fails. Admin/superadmin only (403 otherwise). Uses the local MiniLM embedder, not the built-in chat LLM.
Superadmin/admin configuration: built-in LLM provider/key/model, unbounded-read row cap, Google OAuth client, and Chorus plan-cache administration.
GET/api/admin/ai-configBearerSOAR only
Returns the configured built-in LLM provider, effective and default base URL/model, whether an API key is stored (never the key itself) and where it resolves from (db/env/none), the sample-data toggle, the high-level model family, and Chorus/Sparkle settings. Admin or superadmin required. Configures the built-in LLM, so it is meaningless (403) on the Serverless Database tier. 403 on the Serverless tier (this route calls the built-in LLM).
Saves the built-in LLM provider, API key, base URL, model, sample-data toggle, and Chorus/Sparkle settings. All fields are optional; an omitted field is left unchanged, an empty string clears (for provider/base_url/model/api_key it reverts to provider default or clears the key). Provider/key changes require a server restart to take effect for the running agent loop (restart_required:true). Admin or superadmin required. Configures the built-in LLM, so it 403s on the Serverless Database tier. 403 on the Serverless tier (this route calls the built-in LLM).
PUT/api/admin/ai-config/model-familyBearerSOAR only
Flips the customer-level default model family, preserving the gateway client key and host. 'claude' -> Anthropic adapter (Opus 4.8); 'glm' (or deprecated alias 'open') -> OpenAI adapter (OpenRouter GLM 5.2 + Qwen3-VL); 'sparkle'/'sparkle-thinking' -> Sparkle. Only provider/base_url/model change. Takes effect on the next AI call (no restart). Admin or superadmin required. Configures the built-in LLM, so it 403s on the Serverless Database tier. 403 on the Serverless tier (this route calls the built-in LLM).
Returns the upstream model catalog for the Settings model picker. Only 'openrouter' returns a non-empty list (fetched live and cached 5 minutes, with pricing normalized to $/Mtok); 'openai'/'anthropic' return an empty array so the UI falls back to a free-text field. Admin or superadmin required. This is built-in-LLM configuration, so it 403s on the Serverless Database tier. 403 on the Serverless tier (this route calls the built-in LLM).
Parameters
Name
In
Type
Description
provider
query
string
Provider whose catalog to return (e.g. openrouter). Defaults to the configured provider.
Returns the unbounded-read row cap for this instance: the stored cap, the effective cap actually enforced by /sql (env MAX_QUERY_ROWS overrides the stored value), and whether an env override is masking the setting. This is a DATABASE feature, not AI-gated, so it works on the Serverless Database tier. Admin or superadmin required.
Sets the unbounded-read row cap (1..10,000,000) that bounds a single unpaginated SELECT via /sql, MCP, or the API; paginated reads (?page&pageSize) are unaffected. Live on the next read (no restart). Not AI-gated, so it works on the Serverless Database tier (cmgmt pushes the cap to serverless instances). Admin or superadmin required.
Returns the effective Google OAuth client_id (safe to surface), whether a client secret is stored (never returned), the source of the effective values (db/env/none), and whether the OAuth flow is fully configured. Env vars (GOOGLE_OAUTH_CLIENT_ID/_SECRET, legacy GMAIL_OAUTH_*) are a fallback until a DB value is saved. Not AI-gated (OAuth connect works without the built-in LLM), so it works on the Serverless Database tier. Admin or superadmin required.
Persists a fresh Google OAuth client_id/client_secret pair into the encrypted settings record; the OAuth flow picks it up on the next call. Each field is optional: omit to leave unchanged, empty string to clear the DB value and fall back to env, non-empty to overwrite. Returns the effective config. Not AI-gated, so it works on the Serverless Database tier. Admin or superadmin required.
Returns every verified Chorus (semantic plan cache) template with per-shape usage metrics (hits, misses observed on the same shape, avg hit latency, last use) plus a per-namespace rollup with hit rate for the tenant view. Metrics are read/aggregated from _system.ChorusMetrics. Inspecting the cache does not invoke the built-in LLM, so it works on the Serverless Database tier. Admin or superadmin required.
Clears the whole Chorus plan cache, or every template of one tenant namespace when ?namespace is given. Deletion is always safe: the next matching message simply misses to the agent and can re-admit through the replay gate. Does not invoke the built-in LLM, so it works on the Serverless Database tier. Admin or superadmin required.
Parameters
Name
In
Type
Description
namespace
query
string
Optional tenant namespace filter; omit to clear the entire cache.
Surgically removes a single Chorus plan-cache template by id from _system.ChorusPlanCache. Returns whether the template existed. Does not invoke the built-in LLM, so it works on the Serverless Database tier. Admin or superadmin required.
Parameters
Name
In
Type
Description
id
path
string
The _id of the ChorusPlanCache template to delete.
Response 200
{
"ok": true,
"deleted": true
}
POST/api/admin/chorus/dry-runBearerSOAR only
Shows how Chorus reads a question: runs extraction + canonicalization only (one small extractor LLM call; no agent, nothing served or admitted, its own usage bucket). Powers the Songbook contrast/regression view. Because it makes a built-in extractor LLM call, it returns 403 on the Serverless Database tier. Admin or superadmin required. 403 on the Serverless tier (this route calls the built-in LLM).
Request
{
"message": "show vacant properties in Austin over $2000 rent",
"namespace": "pms"
}
