Operate
APIs and SQL access
Programmatic access to a Konstrukt tenant — the REST API and its OAuth client-credentials authentication, the Kex query endpoint, and the external SQL views with point-in-time queries.
A Konstrukt tenant can be read and written by other systems through three machine interfaces: the REST API, the Kex endpoint of that API (run a Kex script, get JSON back), and external SQL views for BI and data-warehouse tools. AI agents use a fourth interface, the MCP server, described in AI agents and MCP. Inbound file imports are covered in Data integration.
| Interface | Direction | Protocol | Typical consumer |
|---|---|---|---|
| REST API | Read and write | HTTPS, JSON, OAuth 2.0 | Integration services, scripts |
Kex endpoints (/api/v1/kex…) |
Validate, read and write Kex scripts (results as JSON) | HTTPS, OAuth 2.0 | Applications that need model-aware queries |
Import endpoint (/api/v1/import/{key}) |
Write | HTTPS, OAuth 2.0 | See Data integration |
| External SQL views | Read | T-SQL over TCP 1433 | BI tools, data warehouses |
MCP server (/api/mcp) |
Read and write | Model Context Protocol | AI agents |
REST API#
Each tenant serves its API on its own host: https://{tenant}.konstrukt.app/api/....
The endpoint reference is generated from the running service and is always current. Every tenant serves it at /api/documentation/index.html, for example https://acme.konstrukt.app/api/documentation/index.html. This page does not duplicate it.
| Resource | Path |
|---|---|
| Interactive reference (Swagger UI) | /api/documentation/index.html |
| OpenAPI 3.0 specification | /api/v1/openapi.json (no sign-in required) |
| OAuth 2.0 server metadata | /.well-known/oauth-authorization-server |
All operations are under /api/v1. There is currently one API version.
Authentication#
The API uses OAuth 2.0. The token endpoint supports two grant types:
| Grant | Used by |
|---|---|
client_credentials |
Integrations and scripts, with an API key |
authorization_code (with PKCE) |
Interactive clients that sign in through the browser, such as MCP clients |
For integrations:
- Create an API key in the tenant under Integration → API keys (API-nycklar). Only administrators can create keys. The key is created for a chosen user and carries that user's permissions. The Key ID and API key are shown once, when the key is created. Store them then, because an existing key cannot be displayed again. Keys are valid for one year by default.
- Request an access token.
| Property | Value |
|---|---|
| Endpoint | POST https://{tenant}.konstrukt.app/api/v1/token |
| Content type | application/x-www-form-urlencoded |
grant_type |
client_credentials |
client_id |
Key ID |
client_secret |
API key |
curl -X POST https://{tenant}.konstrukt.app/api/v1/token \
-d "grant_type=client_credentials" \
-d "client_id={key-id}" \
-d "client_secret={api-key}"
- Call the API with the returned
access_tokenas a bearer token:
Authorization: Bearer {access_token}
A minimal Python client:
import requests
BASE_URL = "https://{tenant}.konstrukt.app"
token = requests.post(f"{BASE_URL}/api/v1/token", data={
"grant_type": "client_credentials",
"client_id": "{key-id}",
"client_secret": "{api-key}",
}).json()["access_token"]
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
# Call any endpoint listed in /api/documentation/index.html with these headers.
An access token from client_credentials is valid for about six hours. The specification defines no refresh grant, so when a token expires, request a new one with the same credentials. Interactive clients that sign in with authorization_code, such as MCP clients, can choose a longer token lifetime, up to 30 days.
The API has no rate limits, and no rate-limit headers are returned. Batch work rather than sending many small calls, since every write triggers dependent calculations.
Kex endpoints#
The Kex endpoints run a Kex script against the tenant and return the result as JSON. They give external systems the same query semantics as calculations and apps: implicit joins over shared dimensions, plan and reference selection (from plan, from reference), and point-in-time reads (from history).
| Method and path | Body | Returns |
|---|---|---|
POST /api/v1/kex/script/validate |
{ "Script": "…" } |
Validation result |
POST /api/v1/kex/script/read |
{ "Script": "…" } |
{ "resultSets": [ { "name", "rows" } ] } |
POST /api/v1/kex/script/write |
{ "Script": "…" } |
Result sets, including insert, update and delete counts for each write |
GET /api/v1/kex?script=… |
— | A flat array of rows |
POST /api/v1/kex/script/read
{ "Script": "Total = sum(Amount), Department where Month >= \"202401\" from plan 3" }
A script can return several result sets, one per evaluate or bare expression.
Writes go to the default plan
The Kex endpoints take no plan parameter. A script runs in the tenant's default plan: from plan changes where data is read from, not where a write goes. To work in another plan, start the script with use plan. Test write scripts with /validate first.
Import endpoint#
/api/v1/import/{key} imports a file using an import configuration. It is one of three transports for the same configuration; see Data integration.
External SQL views#
For BI tools and data warehouses, Konstrukt exposes read-only external views in the externalViews schema of the tenant's SQL database.
Connecting#
Create an SQL integration account (SQL-integration) under Integration → Accounts (Konton):
| Setting | Value |
|---|---|
| Host | sql.konstrukt.app |
| Port | 1433 |
| User | Account-specific user ID |
| Password | Generated when the account is created |
| Network | Connections only from IP addresses on the account's allow-list |
The views are queried with T-SQL.
Enable export#
A dimension or value type only gets a view when Enable export (Aktivera export) is ticked for it. The switch is in the object's Integration side panel (Integration → Exportera), together with a ready-made statement with a copy button and a link to the SQL integration settings (Gå till SQL-integration):
select * from externalViews.d_Department where PlanId = 3
View catalogue#
| View | Content |
|---|---|
externalViews.Plan |
All plans: PlanId, Name, IsActive, IsDefault |
externalViews.Reference |
All references usable for value type data: ReferencedId, PlanId, Name, Description |
externalViews.vt_{ValueType} |
Plan data of one value type |
externalViews.vtr_{ValueType} |
Reference data of one value type (adds ReferenceId) |
externalViews.d_{Dimension} |
Dimension values of one dimension with their properties |
externalViews.Metadata |
Lists available views — for troubleshooting only; content may change |
By default the value type and dimension views contain data from all active plans, with a union of the dimensions (or properties) used across those plans. Konstrukt can configure the views per plan — for example only the default plan, a range of plans, or including archived plans.
Value type views#
externalViews.vt_{ValueType} has one column per dimension plus:
| Column | Meaning |
|---|---|
PlanId |
Plan of the row |
ValueTypeId |
Value type ID |
DecimalValue |
Value for numeric value types |
StringValue |
Value for text value types (instead of DecimalValue) |
DateValue |
Value for date/time value types, in UTC |
CalculationId |
ID of the calculation that wrote the row; empty for non-calculated rows |
EditTime |
Last time the value changed |
EditState |
Type of the last change (below) |
EditState |
Meaning |
|---|---|
0 |
Suggested — created in the admin interface or imported through an integration |
10 |
Set by a user in an app |
30 |
Set by a calculation |
PlanId ValueTypeId Year Month DecimalValue
3 Amount 2024 10 99500.00
3 Amount 2024 11 99500.00
4 Amount 2025 1 100250.00
Dimension views#
externalViews.d_{Dimension} has PlanId, DimensionId, Code, Name, EditTime, and two columns per property: {Property}_Code and {Property}_Name.
PlanId DimensionId Code Name Region_Code Region_Name
3 Department 100 Sales N North
3 Department 200 Marketing S South
Point-in-time queries#
The views are temporal: the state of the data at any earlier moment can be queried with for system_time as of (UTC).
-- Amount as it stood on 1 June 2025, 00:00 UTC
select * from externalViews.vt_Amount for system_time as of '2025-06-01 00:00:00'
Point-in-time references do not appear in the vtr_ views — they store a moment, not data. Query the vt_ view with for system_time as of at the reference's timestamp instead. See References and history.
Compatibility and other views#
- Older databases expose an earlier version of the views in the
dboschema with the prefixvw_external_. Differences:PlanLineIdis removed from value type views,DimValueId/Idfrom dimension views, and property names are always included. - Additional views (for example apps, app statuses or access groups) can be created for specific needs. They are not guaranteed to be as stable as the views listed above.
Sensitive value types are visible in SQL views
The SQL integration account is one account per tenant and sees all data. Values of sensitive value types (isSensitive) are not hidden in the vt_ views. See Security.
Choosing an interface#
| Need | Use |
|---|---|
| Nightly load of actuals from an ERP | Import configuration + storage, SFTP or KDI (Data integration) |
| Immediate feedback on each import | /api/v1/import/{key} |
| BI dashboards on plan data, including history | External SQL views |
| An application that needs aggregated, model-aware answers | Kex endpoint |
| Building or changing the model itself | MCP server (AI agents and MCP) or the admin GUI |
For agents
MCP clients do not need the REST API: execute_read_script runs the same Kex as /api/v1/kex, and the import tools cover the import endpoint. Use the REST API only when generating code for a customer's own integration. Always point to https://{tenant}.konstrukt.app/api/documentation/index.html for endpoint details instead of guessing request shapes.