---
title: "OpenAPI"
description: "The three OpenAPI documents Minima publishes, which one you want, and how to generate a client from it"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.minima.ltd/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAPI

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

| Document | URL | Covers |
|---|---|---|
| Public API | `/api/v1/{orgId}/openapi.public.json` | The site-facing read API you build a front end against |
| Admin API | `/api/v1/{orgId}/openapi.json` | The stable Admin API — everything you can read and write |
| Admin API (beta) | `/api/v1/{orgId}/openapi.beta.json` | Every stable operation, plus those still settling |

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](/developers/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.

> **Note**
>
> There is no separate beta document for the Public API. That surface is stable in full.

## 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](https://openapi-ts.dev/)
- [Hey API](https://heyapi.dev/)
- [APIful](https://apiful.land/)

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

```bash
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](/developers/examples) for working front ends built this way.

Source: https://docs.minima.ltd/developers/openapi/index.mdx