Core concepts
Workspaces and projects
A workspace is the billing and membership boundary. It owns projects, subscribers, API usage, and the plan that sets your rate limits.
A project is a single content source, fixed to one content type at creation:
| Content type | Produces |
|---|---|
blog | Posts with tags, series, cover images, read time |
docs | A navigable page tree driven by docs.json |
changelog | Dated entries, optionally version-tagged |
Almost every API call is scoped to a project ID. A key belongs to exactly one project and can never reach another's data — that boundary is enforced server-side, not by the caller's parameters.
How content is resolved
Published MDX lives in your repo under the project's configured path. When you read through the API, the platform fetches from GitHub and caches the result. Two things invalidate that cache:
- a push webhook from GitHub, and
- a write through the API or dashboard.
So a post created via POST /api/v1/blog/posts is readable immediately, not on the next
cache expiry.
Slugs are not file paths
Navigation slugs are declared independently of where files sit on disk. For docs, that
mapping lives in docs.json. Rename a slug and the framework issues a 301 from the old
URL, so links you've already published keep working.
What's public and what isn't
This distinction drives the whole auth model:
| Data | Public? |
|---|---|
| Published blog posts, docs pages, changelog entries | Yes — readable with no key |
| Comment threads and reaction counts | Yes |
| Newsletter signup (creating a pending subscriber) | Yes — anonymous by necessity |
| Subscriber lists and emails | No — requires a scoped key |
| Creating or updating content | No — requires a secret key |
Read endpoints being public is deliberate: they serve content that's already published on the open internet. Adding a key to a read request doesn't unlock more data — it scopes the request to that key's project and applies that key's rate limit.
Subscriber data is the opposite: there is no public fallback, because an email address someone gave you is not published content.
Drafts and scheduling
Frontmatter carries a status of published, draft, or scheduled. Only published
content is served by the read endpoints — drafts are visible in the dashboard and in
your repo, never through the public API.
Consumption patterns
There are two ways to put Inkform content on a site, and they aren't exclusive:
Render the files directly. Your site imports @inkform/framework and reads the MDX
from its own repo at build time. No API calls, no key, no runtime dependency on the
platform. This is what the docs and blog example apps do.
Fetch over the API. Your site calls /api/v1/* at build or request time. Useful
when the content lives in a different repo from the site, when several sites share one
content source, or when a non-JavaScript stack is consuming it.