OpenAPI

Minima describes itself with OpenAPI. There are three documents, because there are two APIs and the Admin API has a beta tier.

All three are served from https://api.minima.ltd, so a full URL looks like https://api.minima.ltd/api/v1/org_abc123/openapi.json. The documents themselves need no API key.

You can also read any of them rendered, without generating anything, in the dashboard under Help -> API Reference.

Which one do you want

If you are building a website or app that displays your content, you want the Public API document. It describes the read-only, site-scoped surface that pub_ keys unlock — around 25 operations, safe to call from a browser.

If you are building an integration that creates or updates content, you want the Admin API document. It describes the organization-scoped surface that priv_ keys unlock — around 43 operations covering the full read and write model.

The Public and Admin APIs are not two views of the same thing. They are different surfaces under different paths, with different keys and different permissions. See Authentication for the split.

Stable and beta

Every Admin operation is tagged stable or beta.

openapi.json carries only the stable ones. Build against it and your client will not change under you.

openapi.beta.json is a superset — the same stable operations plus around 24 more that are still settling. Beta operations may change without notice. When one stabilises it keeps its URL and appears in openapi.json, so nothing you have already written needs to move.

Why the URLs include your organization

Minima models your content as a knowledge graph, and the shape of that graph is yours — your entity types, your properties, your relationships. The organization-scoped documents are built from your live schema, so generated types describe your actual data rather than a generic Record<string, unknown>.

A generic Public API document is also served at https://api.minima.ltd/api/v1/openapi.public.json without an organization. It describes the same endpoints, but without your entity types. Reach for it only when you need to look at the shape of the API before you have an organization to point at.

Authentication in generated clients

All three documents declare a single security scheme, an API key in the x-api-key header, and apply it to every operation. Any generator that understands OpenAPI security will produce a client with a place to put your key.

Generating a client

There are good generators for most languages. For TypeScript:

• OpenAPI TypeScript
• Hey API
• APIful

A typical setup points the generator at your organization-scoped document and commits the output:

npx openapi-typescript \
  https://api.minima.ltd/api/v1/org_abc123/openapi.public.json \
  -o ./src/lib/minima.d.ts

Regenerate when you change your entity types, the same way you would after a database schema change.

See Examples for working front ends built this way.