> ## Documentation Index
> Fetch the complete documentation index at: https://betterdatainc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# How We Document APIs

> Workflow for maintaining API documentation using code-first manifest

# How We Document APIs

This document explains our code-first approach to API documentation. We maintain a single source of truth (the API manifest) and auto-generate Mintlify reference tables from it.

## Overview

Our API documentation workflow follows these principles:

1. **Code-first**: The manifest in `packages/api-spec/src/manifest.ts` is the source of truth
2. **Auto-generated**: Reference tables are generated from the manifest
3. **Scope-safe**: Guardrails ensure no SuperAdmin endpoints leak into tenant docs
4. **Lightweight**: Regex-based scanning, no runtime code changes

## Workflow

### Step 1: Scan Routes

Discover all API routes in the codebase:

```bash theme={null}
pnpm api:scan
```

This scans `apps/scm/app/api/**/route.ts` files and generates:

* `packages/.generated/api-routes.json` - Complete route inventory
* `packages/.generated/manifest-stubs.ts` - Suggested manifest entries

**What it does:**

* Finds all route handlers
* Detects HTTP methods (GET, POST, etc.)
* Identifies authentication patterns
* Extracts Zod schema names
* Classifies routes as tenant-facing vs internal-only

### Step 2: Generate Stubs

Create manifest stub suggestions:

```bash theme={null}
pnpm api:stubs
```

This reads the scan results and generates:

* `packages/.generated/api-manifest.stubs.ts` - Ready-to-copy manifest entries

**What it does:**

* Converts paths to stable IDs
* Infers tags from path prefixes
* Detects auth types
* Sets default stability (beta for safety)
* Marks internal-only routes

### Step 3: Refine Manifest

Copy relevant stubs to `packages/api-spec/src/manifest.ts` and:

1. **Fill in summaries**: Replace "TODO: Add summary" with clear descriptions
2. **Add descriptions**: Provide detailed endpoint documentation
3. **Add examples**: Include request/response examples
4. **Set permissions**: Document required permissions
5. **Adjust stability**: Mark stable endpoints as `stable` (default is `beta`)
6. **Add query params**: Document query parameters
7. **Add path params**: Document dynamic route segments

**Example:**

```typescript theme={null}
{
  id: 'forecast.events.create',
  method: 'POST',
  path: '/api/forecast/events',
  summary: 'Create an external event',
  description: 'Create a new external event (promotion, holiday, etc.) to drive forecast adjustments',
  tags: ['forecasting'],
  audience: 'tenant',
  auth: 'session',
  stability: 'stable',
  permissions: ['forecast.write'],
  requestSchema: 'CreateEventSchema',
  queryParams: [
    { name: 'from', type: 'string', required: false, description: 'Start date (ISO string)' },
    { name: 'to', type: 'string', required: false, description: 'End date (ISO string)' },
  ],
  examples: [
    {
      title: 'Create promotion event',
      request: {
        body: {
          name: 'Summer Sale 2024',
          type: 'PROMOTION',
          startsAt: '2024-06-01T00:00:00Z',
          endsAt: '2024-06-30T23:59:59Z',
        },
      },
      response: {
        status: 201,
        body: {
          id: 'event_789',
          name: 'Summer Sale 2024',
        },
      },
    },
  ],
}
```

### Step 4: Validate

Check the manifest against guardrails:

```bash theme={null}
pnpm api:validate
```

**Validations:**

* ✅ No SuperAdmin paths or references
* ✅ All tenant routes have proper auth
* ✅ All IDs are unique
* ✅ All paths start with `/api/`
* ✅ All routes have summaries and tags

### Step 5: Generate Docs

Update Mintlify reference tables:

```bash theme={null}
pnpm api:docs
```

This updates the delimited blocks in:

* `docs-site/api-reference/forecasting.mdx`
* `docs-site/api-reference/inventory.mdx`
* `docs-site/api-reference/alerts.mdx`
* `docs-site/api-reference/transfers.mdx`
* `docs-site/api-reference/catalog.mdx`

**What it does:**

* Groups routes by tag
* Sorts by path, then method
* Generates markdown tables
* Includes permissions when available
* Marks beta endpoints with ⚠️
* Only updates delimited blocks (preserves other content)

## CI Guard

Before committing, run the CI guard:

```bash theme={null}
pnpm api:guard
```

**Checks:**

* ✅ Manifest doesn't contain excluded paths (SuperAdmin)
* ✅ Generated docs blocks are present in all target files
* ✅ Docs blocks are properly formatted

This should be run in CI to prevent regressions.

## Scope Rules

### ✅ Include

* Tenant-facing APIs in `apps/scm/app/api/**`
* APIs consumed by external integrators
* Tenant-admin configuration APIs (`/api/admin/*`)

### ❌ Exclude

* SuperAdmin endpoints (`apps/admin/**`)
* Tenant provisioning APIs
* Entitlement assignment APIs
* Billing admin operations
* Internal cron endpoints (unless tenant-configurable)

### ⚠️ When in Doubt

Mark ambiguous endpoints as `internalOnly: true` until confirmed tenant-facing.

## File Structure

```
packages/api-spec/
├── src/
│   ├── types.ts          # Type definitions
│   ├── manifest.ts       # API route specifications (source of truth)
│   └── index.ts          # Package exports
├── scripts/
│   ├── scan-routes.ts    # Route scanner
│   ├── build-manifest.ts # Manifest stub generator
│   ├── validate-manifest.ts # Manifest validator
│   ├── generate-mintlify.ts # Docs generator
│   └── ci-guard.ts       # CI guard
└── package.json

packages/.generated/
├── api-routes.json       # Scan results
├── manifest-stubs.ts     # Generated stubs
└── api-manifest.stubs.ts # Refined stubs

docs-site/api-reference/
├── forecasting.mdx       # Contains generated table block
├── inventory.mdx         # Contains generated table block
├── alerts.mdx            # Contains generated table block
├── transfers.mdx         # Contains generated table block
└── catalog.mdx           # Contains generated table block
```

## Delimited Blocks

Generated tables are wrapped in delimited blocks:

```markdown theme={null}
{/* BEGIN:API_TABLE tag=forecasting */}
{/* this block is generated; do not edit by hand */}
| Method | Path | Summary | Auth | Stability | Permissions |
| ...    | ...  | ...     | ...  | ...       | ...         |
{/* END:API_TABLE tag=forecasting */}
```

**Important:**

* Do NOT edit content between these markers
* The generator will overwrite it
* All other content in the file is preserved

## Best Practices

1. **Keep it lightweight**: Use regex-based scanning, don't refactor runtime code
2. **Prefer correctness**: Mark ambiguous endpoints as `internalOnly: true`
3. **Scope safety first**: Better to exclude than include SuperAdmin endpoints
4. **Update regularly**: Run `api:scan` when adding new routes
5. **Validate before commit**: Run `api:validate` and `api:guard`

## Troubleshooting

### "Route not in docs"

1. Check if route is in manifest: `packages/api-spec/src/manifest.ts`
2. Verify route has correct tags matching target file
3. Run `pnpm api:docs` to regenerate tables
4. Check if route is marked `internalOnly: true`

### "CI guard failing"

1. Check for SuperAdmin paths: `pnpm api:validate`
2. Verify docs blocks exist: Check target files for delimited blocks
3. Regenerate docs: `pnpm api:docs`

### "Missing permissions column"

Permissions column is only shown when routes have `permissions` defined in manifest. Add permissions to routes that need them.

## Related Pages

* [API Overview](/api-reference/overview)
* [API Authentication](/api-reference/authentication)
* [Forecasting API](/api-reference/forecasting)
* [Inventory API](/api-reference/inventory)
* [Transfers API](/api-reference/transfers)
* [Alerts API](/api-reference/alerts)
* [Catalog API](/api-reference/catalog)