# Where to Find CommonGrants Documentation and OpenAPI Specs

> Easily find CommonGrants documentation and OpenAPI specs in the hhs/simpler-grants-protocol repository or on commongrants.org. Get the information you need quickly.

- Repository: [U.S. Department of Health & Human Services/simpler-grants-protocol](https://github.com/hhs/simpler-grants-protocol)
- Tags: api-reference
- Published: 2026-03-03

---

**The CommonGrants documentation and OpenAPI specifications are available both in the `hhs/simpler-grants-protocol` repository and on the public website at commongrants.org.**

The CommonGrants protocol provides standardized grant data exchange formats and API specifications. Whether you are implementing a grants management system or building a client application, you need access to the human-readable documentation and the machine-readable OpenAPI specifications. This guide maps out every location where these resources live, from the public website to the exact source files in the repository.

## CommonGrants Documentation Locations

### Human-Readable Protocol Documentation

The authoritative protocol specification lives in the repository's documentation source and is rendered on the public site.

- **Repository path**: [`website/src/content/docs/protocol/specification/v0_1_0.md`](https://github.com/hhs/simpler-grants-protocol/blob/main/website/src/content/docs/protocol/specification/v0_1_0.md)
- **Public URL**: https://commongrants.org/protocol/specification

This file contains the human-readable description of routes, status codes, and data models that define the CommonGrants protocol.

### Getting Started Guides

For developers looking to compile TypeSpec definitions into OpenAPI documents, the quick-start guide provides step-by-step instructions.

- **Repository path**: `website/src/content/docs/getting-started.mdx`
- **Public URL**: https://commongrants.org/getting-started

This guide explains how to use the CommonGrants CLI to compile TypeSpec definitions and generate OpenAPI specifications locally.

## OpenAPI Specification Files

### Published OpenAPI YAML Files

The canonical OpenAPI 3.0 documents are versioned and stored as static YAML files in the repository. These files are the source of truth for API implementations.

- **Repository paths**:
  - [`website/public/openapi/openapi.0.1.0.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/website/public/openapi/openapi.0.1.0.yaml)
  - [`website/public/openapi/openapi.0.2.0.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/website/public/openapi/openapi.0.2.0.yaml)
  - [`website/public/openapi/openapi.0.3.0.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/website/public/openapi/openapi.0.3.0.yaml)

- **Public URLs** (replace version number as needed):
  - https://commongrants.org/public/openapi/openapi.0.1.0.yaml

These YAML files fully describe the CommonGrants API endpoints, request/response schemas, and authentication requirements.

### Interactive API Documentation

For browsing the OpenAPI specs interactively, the website hosts a Swagger UI interface.

- **Repository path**: `website/src/pages/protocol/api-docs.astro`
- **Public URL**: https://commongrants.org/protocol/api-docs

This Astro page renders the static OpenAPI YAML files using Swagger UI, allowing developers to explore endpoints and download client SDKs directly from the browser.

## Source Files and TypeSpec Definitions

### Core TypeSpec Library

The authoritative source of truth for the protocol is written in TypeSpec, a domain-specific language for API definition. These files generate the OpenAPI specifications.

- **Repository path**: `lib/core/*.tsp` (e.g., `lib/core/common_grants.tsp`)

These TypeSpec files define the routes, models, and status extensions that are compiled into the OpenAPI YAML files found in `website/public/openapi/`.

### CLI Compilation Tools

To regenerate the OpenAPI specs from TypeSpec source, use the CommonGrants CLI.

- **Repository path**: `lib/cli/`

The CLI package `@common-grants/cli` provides the `cg compile` command, which reads [`tspconfig.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/tspconfig.yaml) (found in [`templates/quickstart/tspconfig.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/templates/quickstart/tspconfig.yaml)) and emits OpenAPI 3.0 documents.

## How to Access CommonGrants Documentation Programmatically

You can fetch the OpenAPI specifications directly via HTTP for use in automated tooling or client generation.

### Fetch the OpenAPI Spec with Node.js

```javascript
// Retrieve the latest OpenAPI document from the public site
const url = 'https://commongrants.org/public/openapi/openapi.0.3.0.yaml';
fetch(url)
  .then(res => {
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return res.text();
  })
  .then(yaml => {
    console.log('OpenAPI spec loaded successfully');
    // Feed the YAML to a Swagger parser or client generator
  })
  .catch(err => console.error('Failed to load spec:', err));

```

Replace `0.3.0` with your target version number to access specific releases.

### Generate the OpenAPI Spec Locally

```bash

# Install the CommonGrants CLI globally

npm install -g @common-grants/cli

# Compile TypeSpec to OpenAPI (requires tspconfig.yaml in your project)

cg compile --emit @typespec/openapi3 --output ./openapi.yaml

```

This command generates an [`openapi.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/openapi.yaml) file matching the specifications found in `website/public/openapi/`.

### Validate the Spec with Swagger Parser

```javascript
const SwaggerParser = require('@apidevtools/swagger-parser');

SwaggerParser.validate('https://commongrants.org/public/openapi/openapi.0.3.0.yaml')
  .then(api => {
    console.log('OpenAPI spec is valid:', api.info.title);
  })
  .catch(err => console.error('Validation error:', err));

```

## Summary

- **Public website**: Visit commongrants.org for human-readable docs at `/getting-started` and interactive API docs at `/protocol/api-docs`.
- **Raw OpenAPI files**: Download versioned YAML specs from [`website/public/openapi/openapi.0.x.x.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/website/public/openapi/openapi.0.x.x.yaml) or via public URLs.
- **Source of truth**: TypeSpec definitions in `lib/core/*.tsp` generate the OpenAPI specs using the CLI in `lib/cli/`.
- **Repository docs**: Markdown specifications live in `website/src/content/docs/protocol/specification/` and `website/src/content/docs/getting-started.mdx`.

## Frequently Asked Questions

### Where is the CommonGrants OpenAPI spec hosted publicly?

The CommonGrants OpenAPI specifications are hosted at `https://commongrants.org/public/openapi/openapi.0.x.x.yaml`, where you replace `0.x.x` with the desired version number (e.g., `0.3.0`). These files are also rendered interactively at `https://commongrants.org/protocol/api-docs` using Swagger UI.

### How do I generate the OpenAPI spec from TypeSpec source?

Install the `@common-grants/cli` package and run `cg compile --emit @typespec/openapi3 --output ./openapi.yaml` from a directory containing a [`tspconfig.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/tspconfig.yaml) file. This compiles the TypeSpec source files found in `lib/core/` into a valid OpenAPI 3.0 document matching the published specifications.

### What version of the OpenAPI specification does CommonGrants use?

CommonGrants publishes OpenAPI **3.0** documents. The repository maintains versioned specifications (e.g., `0.1.0`, `0.2.0`, `0.3.0`) in `website/public/openapi/`, with each YAML file conforming to the OpenAPI 3.0 standard for API description and client generation.

### Can I view the CommonGrants documentation offline?

Yes, all documentation source files are available directly in the repository under `website/src/content/docs/`. You can read the Markdown and MDX files (such as `getting-started.mdx` and [`protocol/specification/v0_1_0.md`](https://github.com/hhs/simpler-grants-protocol/blob/main/protocol/specification/v0_1_0.md)) locally without building the site, or run the Astro development server to browse the full documentation offline.