How it works
Organizations, git sync, and how publishing reaches your readers.
Organization
An organization is the tenancy boundary. APIs, schemas, rulesets, sites, SDKs, CLIs, and API keys all live inside one organization.
Resources
Resource | Role |
|---|---|
API | An OpenAPI document and its published versions |
Schema | Shared JSON Schema documents |
Ruleset | Spectral rules that can reject bad uploads |
Site | Hosted docs: guides + API / SDK / CLI embeds |
SDK / CLI | Generated clients built from one or more APIs |
Git as source of truth
Keep OpenAPI files and docs Markdown in git when you want reviewable changes:
Connect your GitHub or GitLab repo on the resource’s Integrations page
Set the path (file for OpenAPI, directory for docs)
Push to the tracked branch; webhook or manual sync imports content
Successful site imports with
sections:rebuild navigation and publish a version
You can still author in the console or via the REST/MCP APIs when you do not use a customer remote.
Publish model
edit (git | console | API | MCP)
│
▼
validate + store version
│
▼
publish → public hosts
Readers see published content at:
{slug}.pinnate.app(and custom domains)Registry hosts for machine-readable OpenAPI
Sites vs registry
Registry | Site | |
|---|---|---|
Audience | Machines and tooling | Humans |
Content | OpenAPI / schema / ruleset documents | Markdown + embeds |
Config | Per-resource git path |
|
Both can live in the same monorepo at different paths. See Project structure.