Pinnate Docs

GitHubApp

Quickstart

Publish an OpenAPI document and a docs site in a few minutes.

Create an API in the registry, upload an OpenAPI document, and publish a docs site with a Markdown guide and a live API reference.

Prerequisites

  • A Pinnate account and organization

  • An OpenAPI 3.x document (YAML or JSON)

  • Optional: a git repo for docs-as-code

1. Create an organization

Sign in at app.pinnate.dev and create or select an organization. APIs, sites, SDKs, and API keys all belong to an organization.

2. Register an API

APIs → New — set a name and slug (for example payments).

Upload your OpenAPI document in the console, or via the API:

POST /v1/apis
Authorization: Bearer sk_…
Content-Type: application/json

{ "name": "Payments", "slug": "payments" }

POST /v1/apis/{api}/spec
Authorization: Bearer sk_…
Content-Type: application/json

{ "document": "openapi: 3.1.0\ninfo:\n  title: Payments\n  version: 1.0.0\npaths: {}\n" }

Pinnate validates the document, optionally lints with a Spectral ruleset, and stores a version. Publish when you are ready for the public registry and embeds.

3. Create a docs site

Sites → New — title and slug. The site is available at {slug}.pinnate.app (and later on a custom domain).

Console path

Add:

  • A Guide section for Markdown pages

  • An API embed pointed at payments

Create a docs folder:

docs/
├── site.yaml
└── introduction.md

site.yaml:

title: Payments Docs
visibility: public
theme:
  accent_color: '#0F766E'
  layout: centered
exclude:
  - README.md
sections:
  - name: Guide
    slug: guide
    path: .
  - name: API
    slug: api
    api: payments

introduction.md:

---
title: Introduction
description: Welcome to the Payments API.
slug: introduction
position: 1
---

# Introduction

Welcome to the Payments API.

Connect the repo on Site → Integrations, set the path to docs, and sync. See Project structure and Site git sync.

4. Add more guide pages

Add Markdown under the guide path. Subfolders become sidebar groups; nested files get path-based URLs such as /sites/configuration/site-settings.

Control order with frontmatter position (or an explicit pages: list in site.yaml).

5. Publish

Publishing promotes the imported or edited snapshot to the public host. Git sync that runs through the importer publishes as part of a successful sync. Console edits need an explicit publish when you use draft workflows.

6. (Optional) Generate an SDK

SDKs → New — attach your API, pick language targets, run a build, and connect GitHub/GitLab to open a PR with the generated package. Embed SDK docs under a site section with sdk: your-sdk-slug.

What’s next