Developers/API Reference/OpenAPI Export & Developer Tools
OpenAPI Export & Developer Tools
Export a machine-readable OpenAPI 3.0.3 document for your schemas, try endpoints in the playground, and hand the spec to a frontend generator. The console's developer tools, and the four things the spec tells a code generator that it would otherwise get wrong.
What the console gives you
Once your schemas are uploaded, the console exposes a set of developer tools built from those same schemas. They are generated, not written — add a schema and every tool below reflects it on the next refresh.
| Tool | Where | What it is for |
|---|---|---|
| API Documentation | API Docs | Every endpoint your schemas produce, grouped by schema type, with request and response shapes and copyable SDK examples |
| OpenAPI export | API Docs → Export OpenAPI | A downloadable OpenAPI 3.0.3 document covering all your schemas — JSON, YAML, or copied to the clipboard |
| PDF export | API Docs → Export PDF | The same reference as a document you can send to someone who is not going to log in |
| Playground | Playground | Issue real authenticated requests against your own data and read the actual response |
| SDK Guide | SDK Docs | The verified client patterns for Python and JavaScript |
| SDK generation | SDKs | Build a client package baked with your domain's current schemas |
| Test data generation | Data → Generate Test Data | Populate a schema with records so the endpoints have something to return |
ℹ️ These are tools for building against the API
They read your schemas and your data; they are not a separate product surface your end users see. Everything they show is available over the REST API directly — the console is the convenient path, not the only one.
⚠️ Not present in the on-premise admin edition
The on-premise admin edition ships without the developer tools — no playground, no SDK generation, no test-data generation. The API documentation and the OpenAPI export are unaffected. If you are planning a workflow around the playground and you are deploying on-premise, confirm your edition first.
Exporting an OpenAPI document
Open API Docs and use Export OpenAPI. Three outputs are offered:
- •Download as JSON — the conventional format for tooling.
- •Download as YAML — the conventional format for humans and for checking into a repository.
- •Copy to clipboard — the whole document as JSON, for pasting into a tool that takes a spec inline.
ℹ️ The export always covers every schema
Whichever tab you are looking at, the export includes all of your schemas across every group — application, connector, service and system. Filtering the page filters the page, not the document. This is deliberate: a spec that silently omitted half your endpoints because of a UI filter would be worse than no spec.
The document is generated at the moment you export it, from the schemas your domain has right now. It is a snapshot, not a live URL — there is no hosted spec endpoint to point a tool at, so re-export after you change your schemas.
⚠️ There is no served spec URL
Supero does not publish your specification at a stable address. Anything that expects to fetch a spec over HTTP — a CI step that regenerates a client, a documentation host that polls a URL — needs you to export the file and put it somewhere yourself.
What is in the document
The export is OpenAPI 3.0.3 and contains what you would expect: an info block naming your domain, a servers entry pointing at the API, tags grouping operations by schema, a paths object, and a components object holding the schema definitions and the security schemes.
Paths cover the CRUD operations each schema produces, the domain-scoped data routes, and the platform endpoints. Object types are addressed as namespace:name — for example capm:lease — and not by a pluralised display name, which is the first thing a generator tends to get wrong if it is inventing routes rather than reading them.
| Security scheme | How it is sent | Where the credential comes from |
|---|---|---|
| bearerAuth | Authorization: Bearer <JWT> | POST /api/v1/auth/login — the token is at auth.access_token in the nested response, not at the top level |
| apiKeyAuth | Authorization: Bearer ak_... | POST /api/v1/domains/{domain}/api-key |
ℹ️ Both credentials travel as a bearer token
An API key is sent in the Authorization header exactly like a JWT, not in an X-API-Key header. Generators that see two security schemes sometimes emit two different request builders; you only need one. See Authentication for how each credential is scoped.
The Supero extensions, and why they matter
OpenAPI describes shapes. It has no way to say "this endpoint accepts a parameter you did not send and ignores the one you did", and it cannot express a creation rule that spans several fields. Three vendor extensions carry the parts of the contract the standard cannot, and they are the difference between a generated client that works and one that appears to work.
| Extension | What it carries |
|---|---|
| x-supero-filtering | That GET list endpoints accept no per-field filters, which operators POST /query does accept, and a worked request example |
| x-supero-parenting | That every create must be parented, the three ways to express the parent, and the expected depth for each parent type |
| x-supero-schemas | The full schema definition behind each type, beyond the request and response shapes |
🚨 The filtering rule is the one that bites
GET list endpoints recognise only pagination and scoping parameters. Any other query parameter — ?status=active — is discarded without an error, and the call returns HTTP 200 with an unfiltered page of results. Nothing fails; you simply get every row. Filtering is done with POST /query. A generated frontend that builds list screens with query-string filters will look correct, return 200, and show the wrong data, so this is worth checking by hand in anything a generator produces. See Querying & Pagination.
🚨 Every create must be parented
A create call must supply fq_name, or parent_uuid plus name, or parent_context plus name. Omitting all three returns 400. An fq_name of the wrong depth is not rejected — it is dropped and rebuilt. A generator reading only the request schema will emit create forms that 400 on submit until you supply the parent. See CRUD Endpoints.
💡 Read the extensions yourself even if your tool ignores them
Most code generators and most LLM-based frontend builders consume paths and components and skip x- extensions entirely. Open the exported file, read those three blocks, and treat them as the review checklist for whatever the generator hands back.
Handing the spec to a frontend generator
A path people ask about: design your schemas in Supero, let the platform stand up the governed backend, export the OpenAPI document, and hand it to a frontend generator — Lovable, v0, Bolt, or a coding agent in your editor — to build the UI against it. The spec is real and generators consume it happily. Read the two constraints below before you plan around it, because they decide the shape of what you build.
ℹ️ Cross-origin requests are allowed
The API answers cross-origin requests from any origin, so a page served from a generator's preview domain can call it directly. Note that the SDKs are a different matter: the JavaScript SDK is a server-side client, "meant for backends, scripts, and serverless functions rather than direct browser bundles", so a browser frontend calls the REST endpoints itself rather than importing the SDK.
🚨 There is no browser-safe place to keep the session
This, rather than connectivity, is the real constraint on a single-page application. A session is an access token lasting hours plus a refresh token lasting days, and the guidance is to keep credentials in a secrets manager or environment variables — which a page cannot do. There is no httpOnly cookie mode and no browser-oriented sign-in flow. A generator will put both tokens in local storage, which turns any cross-site scripting bug into an account takeover that outlives the session. If the data is worth protecting, terminate the session on a server you control and let the page talk to that.
ℹ️ Serving from your own origin remains the pattern Supero itself uses
A generated app serves its UI and proxies /api to the API from its own host, and a deploy into your own AWS or GCP does the same. That proxy is also the natural place to hold a refresh token. It is thin, but it is a server — so "no backend at all" is not the accurate claim for a production application, even though the API will happily answer the browser directly while you are building.
- 1
Model your data
Upload your schemas, or describe the app and let Supero generate them. Every endpoint in the spec comes from a schema, so the spec is only as complete as your model.
- 2
Seed something to look at
Generate test data for the main types. A generator that receives an empty API invents placeholder content, and you will not be able to tell which screens are wired and which are decoration.
- 3
Decide where it will be served
Settle the origin and the proxy before generating anything. This decision determines whether the result can call the API at all, and it is expensive to retrofit.
- 4
Export the spec
API Docs → Export OpenAPI → JSON. Keep the file; you will re-export it whenever the schema changes.
- 5
Hand it over, with the corrections
Give the generator the spec, the base URL, and the list below. It will not read the x- extensions, so anything in them has to be said in the prompt.
- 6
Review against the list below
Every item is a failure that returns a success status. None of them look broken in a demo.
- 7
Re-export on every schema change
The spec is a snapshot, not a served URL. A frontend generated against an old spec keeps calling fields that no longer exist.
| What a generator assumes | What actually happens | Where it is documented |
|---|---|---|
| Filters as query parameters: GET ?status=active | Silently dropped. HTTP 200 with every row. Filtering is POST /query | Querying & Pagination |
| Records have an id field | record.id is undefined. The identifier is record.uuid, and timestamps are created_at | API Overview |
| A create response is the record | Create returns the uuid; the body is not guaranteed to carry back every field. Re-read the record | CRUD Endpoints |
| Create needs only the field values | Every create must be parented — fq_name, or parent_uuid + name, or parent_context + name. Otherwise 400 | CRUD Endpoints |
| name is a display label | name is mandatory, URL-safe and unique within its parent — distinct from a title or display field | Schema Reference |
| A field in the spec is writable by everyone | Fields a role may not write are stripped from the payload and the rest of the write succeeds — 200, and the value did not change | Access Policies |
| response.ok means it worked | Batch operations and service calls return 200 with per-record or per-call failures in the body | Errors & Status Codes |
⚠️ Authentication is yours to wire
The spec tells a generator how to send a credential. It does not obtain one. You need a real login flow against POST /api/v1/auth/login, somewhere safe to keep the token, and a refresh path — and the token is scoped to a domain, project and tenant, which decides what the entire application can see. Treat whatever a generator produces for auth as a sketch, and review it against Authentication before real users touch it.
⚠️ Signing a user up does not place them in a tenant
Creating a tenant requires an administrative permission, so a self-serve "create your workspace" flow cannot run on the credential of the user who is signing up — it needs a server-side call. Leaving new users unplaced is worse than it sounds: membership of a tenant named default-tenant grants project-wide access to every tenant in the project regardless of role. See Building Multi-Tenant Apps.
⚠️ A generated frontend is not a security boundary
Roles, tenant scoping and field-level policy are enforced by the platform on every request, so a generated UI cannot grant access the caller does not have. It can, however, present controls that always fail, or omit ones the user is entitled to. Do not treat what the UI shows as the definition of what is permitted — the policy is, and it is enforced regardless of what the frontend renders. See Access Policies.
ℹ️ Other paths to the same place
Generating the frontend elsewhere is one of several routes. Supero can also generate the customer-facing UI and the admin console for you, or you can drive the whole build from your editor over MCP. Ways to Build compares them.
The playground
The playground issues real authenticated requests against your own domain and shows the actual response. It is the fastest way to settle a question the reference cannot: whether a filter is being applied, what a nested response really looks like, or which error code a malformed create returns.
⚠️ It writes to real data
There is no sandbox mode. A create in the playground creates a record, and a delete deletes one. Use a project or tenant you are willing to dirty, and generate test data rather than experimenting against records that matter.
💡 Use it to confirm the filtering behaviour
Send a GET list call with an invented query parameter and watch it return 200 with a full page. Seeing that once is more convincing than reading about it, and it is the behaviour most likely to survive into a generated frontend unnoticed.
SDK reference and generation
If you are writing the client yourself rather than generating it, the SDK Guide carries the verified patterns for Python and JavaScript, and SDK generation builds a package baked with your domain's current schemas so record fields are documented in the package rather than discovered at runtime.
Only Python and JavaScript are built. A request for another language is accepted and falls back rather than failing loudly, so check what you actually received. See Custom / Per-Domain SDK.
ℹ️ Generated package, not static typing
The generated client documents your fields; it does not give you compile-time or editor-time checking of them. A misspelled type name is still a runtime failure. See Python SDK.
Next steps
The contract
API Overview & Conventions
One base URL, two route families, two auth schemes, one response envelope. Read it
The trap in the spec
Querying & Pagination
Why list filtering is a POST, and what the query operators are. Read it
Before real users
Going to Production
The seeded credentials, permissive defaults and demo affordances a generated app ships with. Read it
Compare the routes
Ways to Build
Generating the frontend elsewhere, against App Studio, MCP, the CLI and the raw API. Read it
On this page