API Overview
The Mosterd Platform turns a data model — the classes, value types, relations, formulas, and scripts defined in a git repository — into a working REST API. The model is what you author; the API is what the server generates and serves from it.
This section documents that generated API: the endpoints, their URL structure, authentication, and how the platform's value data types are represented in JSON. It is the reference for anyone integrating with a running tenant — a front-end, an external system, or an AI agent — rather than for building the model itself.
Base URL and tenant segment
Every data-facing endpoint is scoped to a single tenant. The tenant identifier is the first path segment after the API branch:
/{branch}/{tenant}/...
The tenant identifier is always a UUID. For example, GET /data/2f9c6e1a-7b34-4d58-9c21-0a5e8f1b2c3d/companies lists the companies in that tenant.
Document the canonical base host (https://...), and confirm how the tenant segment is resolved and validated. Cover multi-tenant vs. single-tenant hosting if relevant.
API branches
The API is divided into branches, each rooted at a top-level path segment:
| Branch | Root path | Purpose |
|---|---|---|
| Data | /data/{tenant} | Reading and writing objects — the primary CRUD, query, and file API generated from the data model. |
| Metadata | /metadata/{tenant} | Dashboards, layouts, and resolved type metadata that describe how objects should be presented. |
| System | /system/{tenant} | System-namespace types: user profiles, API keys, secret values, and system settings. |
| Tenants | /tenants | Tenant lifecycle and version-control source configuration. Not tenant-scoped. |
| Scripts | /scripts/{tenant} | Invoking scripts exposed as endpoints. |
| Sources | /sources/{tenant} | Invoking source endpoints. |
| Reports | /reports/{token} | Downloading generated report documents by token. |
| Binaries | /binaries, /assets | Uploading and downloading files and static assets. |
Decide which of the smaller branches (Scripts, Sources, Reports, Binaries, Accounts, Signup) warrant their own pages versus being folded into a related branch. For now, only Data, Metadata, System, and Tenants have dedicated pages.
Common conventions
- Authentication — every request is authenticated. See Authentication.
- JSON representation — request and response bodies encode value data types in a consistent way. See JSON Representation.
- Paging — list endpoints accept Spring-style
page,size, andsortquery parameters and return aDataObjectPage. See Querying objects.
Document cross-cutting concerns once confirmed: error response shape, HTTP status conventions, content negotiation, and any rate limiting.