# Outworx Docs — Full Content Dump

> Long-form companion to /llms.txt. Every guide and changelog
> entry from docs.outworx.io, inlined as markdown so an AI agent
> has one fetch for the project's full content context.

Site: https://docs.outworx.io
Generated at: 2026-09-30T10:58:20.899Z

Outworx Docs is a hosted API documentation platform. Upload
OpenAPI 3.x, Swagger 2.0, or GraphQL SDL specs and get an
interactive docs site, a free hosted mock server, AI chat, an
MCP server per project, a webhooks playground, drop-in SDK
generation (TypeScript + Python), spec diff with a GitHub PR
action, per-version uptime monitoring with public status pages,
Postman-style saved requests + environments, an embeddable
Try-It widget, and a Mintlify-style docs page builder
(custom header + per-endpoint markdown + white-label option)
for paid plans. Free for 2 projects, Pro $9/mo, Business $19/mo
— flat pricing, no per-seat.

---
# Guides

Each guide is reproduced in full below. Canonical URLs given for
deep links. Sorted newest-first.

---
## Outworx REST API — Manage Projects from CI

URL: https://docs.outworx.io/guides/rest-api
Category: Integration
Published: 2026-05-09
Reading time: 7 min

> Drive every Outworx Docs action from a script: create projects, push spec versions, promote a default. Personal access tokens, copy-paste curl, and the full OpenAPI spec.
Every action you can take in the Outworx dashboard — creating projects, pushing new spec versions, promoting a default, soft-deactivating an old version — is also reachable from a `curl` one-liner. This guide walks through authentication, the request/response shape, the flows that matter most for CI pipelines, and where to find the OpenAPI spec.

## Why use the API

The dashboard is for humans. The REST API is for everything else: pre-merge spec validation in CI, scripted onboarding for a new microservice, internal tooling that mirrors a project tree from GitHub into Outworx, or anything else where clicking through a UI would be a chore.

Two surfaces cover roughly the same ground but with different boundaries:

- **Per-project upload tokens** (the older `otwx_` token from Settings → API access) — scoped to spec upload on one project. Best when CI only needs to push a spec.
- **Personal access tokens** (this guide) — account-scoped, do anything you can do via the dashboard, work across all your projects with one token. Best for everything else.

## Generate a personal access token

1. Open [Settings](https://docs.outworx.io/settings) in the dashboard.
2. Find the **API tokens** card.
3. Click **New token**, name it (`ci-pipeline`, `local-dev`, etc.), optionally set an expiry.
4. Copy the plaintext that appears — *we don't store it and we won't show it again*. The dashboard list afterwards only shows the prefix (`otwx_pat_…`) so you can recognise tokens at a glance, plus revoke them if a token leaks.

Tokens act as the user who created them. A token belonging to a Pro-plan user has Pro limits; downgrade the user and the token's allowance drops with it.

## The shape of every request

```bash
curl -H "Authorization: Bearer otwx_pat_..." \
  https://docs.outworx.io/api/v1/projects
```

That's it. JSON in, JSON out. There's no separate API host — `docs.outworx.io/api/v1/*` is the canonical surface so you don't need a second DNS record.

### Success envelopes

Single-resource endpoints return the resource directly:

```json
{
  "id": "f1b7697f-...",
  "name": "Payments API",
  "slug": "payments-api",
  "...": "..."
}
```

List endpoints wrap data in `{ data, pagination }`:

```json
{
  "data": [ /* projects */ ],
  "pagination": { "total": 47, "limit": 50, "offset": 0 }
}
```

### Error envelope

Every error response uses the same shape:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "`name` is required.",
    "details": { "...": "..." }
  }
}
```

`code` is the stable machine-readable identifier — pattern-match on it. `message` is human-readable and may change. The full list of codes (`MISSING_TOKEN`, `INVALID_TOKEN`, `TOKEN_EXPIRED`, `NOT_FOUND`, `VALIDATION_ERROR`, `CONFLICT`, `PAYLOAD_TOO_LARGE`, `RATE_LIMITED`, `PLAN_LIMIT`, `UNSUPPORTED_FORMAT`) lives in the OpenAPI spec.

We don't differentiate "doesn't exist" from "not yours" — both return `404 NOT_FOUND`. A 403 there would leak slug existence to anyone with a token.

## Common flows

### Create a project + push a spec from a fresh CI job

```bash
# 1. Create the project. Slug auto-generates from name when omitted.
curl -X POST -H "Authorization: Bearer $OUTWORX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Payments API","description":"Public Payments API"}' \
  https://docs.outworx.io/api/v1/projects

# 2. Push the OpenAPI spec as the first version. Body IS the spec —
#    NOT a JSON envelope. The first active version is auto-marked
#    as the default.
curl -X POST -H "Authorization: Bearer $OUTWORX_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary '@openapi.json' \
  'https://docs.outworx.io/api/v1/projects/payments-api/versions?label=v1'
```

That's the whole bootstrap. Two calls, no dashboard.

### Promote a new version on every release

The single-default invariant is enforced server-side: setting `is_default: true` on a non-default version automatically demotes whatever was the default before. You don't need two PATCH calls.

```bash
# Push v2 alongside v1, leaving v1 as the default visitors see.
curl -X POST -H "Authorization: Bearer $OUTWORX_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary '@openapi.json' \
  'https://docs.outworx.io/api/v1/projects/payments-api/versions?label=v2'

# Run your QA. When ready, flip the default in one call.
curl -X PATCH -H "Authorization: Bearer $OUTWORX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_default":true}' \
  https://docs.outworx.io/api/v1/projects/payments-api/versions/v2
```

If you instead try to **demote the default directly** (`is_default: false` on the current default), the API rejects it with `400 VALIDATION_ERROR` — the project would have no default, and the docs page would 404 for visitors. Promote a replacement; we'll demote the old one for you.

`DELETE` on the default is also blocked with `409 CONFLICT` for the same reason. Promote first, delete second.

### Soft-deactivate a version without deleting it

`is_active: false` hides the version from the docs page but keeps the row, the spec content, and the analytics intact. Useful for pulling back a release that broke something without losing the audit trail.

```bash
curl -X PATCH -H "Authorization: Bearer $OUTWORX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_active":false}' \
  https://docs.outworx.io/api/v1/projects/payments-api/versions/v2
```

Reactivate by sending `{"is_active":true}`.

### PR preview deploys

Push a spec with `?preview=true` and the new version is treated as PR-scoped: filtered out of the public version picker, kept out of the sitemap, marked `noindex`, and given a 14-day TTL. Reviewers click a link from the PR comment and see live docs for the proposed change without it bleeding into your release version history.

Previews are **Pro+** (free plans get `402 PLAN_LIMIT`) with their own per-plan cap (`maxPreviewsPerProject`: 5 on Pro, 20 on Business). They don't count against your regular `maxVersions` cap.

```bash
# CI on PR open / push:
curl -X POST -H "Authorization: Bearer $OUTWORX_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary '@openapi.json' \
  "https://docs.outworx.io/api/v1/projects/$SLUG/versions?label=pr-${PR_NUMBER}&preview=true&pr=${PR_NUMBER}&commit=${COMMIT_SHA}&branch=${BRANCH_NAME}"
```

The response includes the version row with `is_preview: true` and a `preview` object holding the PR number, commit SHA, branch, and `expires_at`. The preview is reachable at:

```
https://{slug}.docs.outworx.io/preview/{PR_NUMBER}/
```

(or your custom domain). Re-pushing the same label as new commits land on the PR **updates** the existing row (200 OK) instead of returning 409 — designed for CI to push on every commit. The TTL rolls forward each time, so an active PR keeps its preview indefinitely.

#### GitHub Action

```yaml
name: Outworx — PR preview docs

on:
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]
  pull_request_target:
    types: [closed]

jobs:
  push-preview:
    if: github.event.action != 'closed'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Push preview spec
        env:
          OUTWORX_TOKEN: ${{ secrets.OUTWORX_TOKEN }}
          SLUG: my-project
          PR: ${{ github.event.pull_request.number }}
          SHA: ${{ github.event.pull_request.head.sha }}
          BRANCH: ${{ github.event.pull_request.head.ref }}
        run: |
          RESP=$(curl -sS --fail-with-body -X POST \
            -H "Authorization: Bearer $OUTWORX_TOKEN" \
            -H 'Content-Type: application/json' \
            --data-binary '@openapi.json' \
            "https://docs.outworx.io/api/v1/projects/$SLUG/versions?label=pr-$PR&preview=true&pr=$PR&commit=$SHA&branch=$BRANCH")
          echo "PREVIEW_URL=https://$SLUG.docs.outworx.io/preview/$PR/" >> $GITHUB_ENV
      - name: Sticky PR comment
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          header: outworx-preview
          message: |
            📘 **Docs preview**: ${{ env.PREVIEW_URL }}
            Updated on every push. Auto-cleaned 14 days after the PR closes.

  cleanup-preview:
    if: github.event.action == 'closed'
    runs-on: ubuntu-latest
    steps:
      - name: Delete preview version
        env:
          OUTWORX_TOKEN: ${{ secrets.OUTWORX_TOKEN }}
          SLUG: my-project
          PR: ${{ github.event.pull_request.number }}
        run: |
          curl -sS -X DELETE \
            -H "Authorization: Bearer $OUTWORX_TOKEN" \
            "https://docs.outworx.io/api/v1/projects/$SLUG/versions/pr-$PR" || true
```

Two safety nets, in order of preference:

1. **Explicit DELETE on PR close** — the `cleanup-preview` job above. Runs as soon as the PR closes (merged or not).
2. **14-day TTL via cron** — if the close webhook never fires (CI crashed, repo was deleted, etc), the prune cron sweeps stale previews. The `expires_at` field is rolled forward on every preview re-push, so an active PR keeps its preview for as long as it sees activity.

The dashboard hides preview rows from the version picker on the public docs page. To list them programmatically (for your own preview-management tooling), pass `?include_previews=true` to the GET endpoint:

```bash
curl -H "Authorization: Bearer $OUTWORX_TOKEN" \
  "https://docs.outworx.io/api/v1/projects/$SLUG/versions?include_previews=true"
```

### Make a project public + assign a custom domain

```bash
curl -X PATCH -H "Authorization: Bearer $OUTWORX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_public":true,"custom_domain":"docs.example.com"}' \
  https://docs.outworx.io/api/v1/projects/payments-api
```

Custom domain setting is gated on the **Business** plan — Free and Pro tiers get `402 PLAN_LIMIT` when they try to set one. Clearing a domain (passing `null`) is allowed on every plan, mirroring what the subscription-sync would do automatically on a Business → Pro downgrade.

Setting `custom_domain` over the API does **not** auto-verify — verification still goes through the dashboard's DNS check + Vercel registration step. The API exposes the field for setup parity (so you can prepare a migration without clicking) but the verification handshake stays a dashboard step.

## Plan limits

Every endpoint enforces the owning user's plan limits. Hit one and you get `402 PLAN_LIMIT` with a message that points at exactly which limit you tripped:

- Max projects per account
- Max active versions per project (Free: 1, Pro: 3, Business: unlimited)

The body looks like:

```json
{
  "error": {
    "code": "PLAN_LIMIT",
    "message": "Your Free plan allows 1 active version per project."
  }
}
```

## The spec

The full OpenAPI 3.1 spec is at:

```
https://docs.outworx.io/api/v1/openapi.json
```

That's the source of truth — every example here, every schema, every error code. Drop the URL into Postman / Insomnia / Stoplight to get an importable collection. Drop it into [openapi-typescript](https://github.com/openapi-ts/openapi-typescript) to generate a typed client. Or if you want a full rendered reference page, point an Outworx Docs project at it (yes, you can host the docs for the Outworx API through Outworx; we do).

## Status & rate limits

Every authenticated request bumps the token's `last_used_at` so dormant tokens stand out in the dashboard list. We emit standard rate-limit headers when applicable; expect `429 RATE_LIMITED` if you blast through a burst — the body's `message` includes the retry-after hint.

For automation that needs to run continuously, the comfortable budget is a few requests per second per token. If you need more, contact us before you start hammering — we'd rather raise a limit than have you discover it the hard way.

## Roles + permissions (Business)

The API enforces RBAC for accounts on the **Business** plan. On Pro / Free every collaborator gets equal access (the behaviour you had before this feature shipped); a token still acts as the user it belongs to, but every endpoint treats every active collaborator as an Editor regardless of stored role.

| Permission | Owner | Editor | Viewer |
|---|---|---|---|
| Read project + versions | ✅ | ✅ | ✅ |
| Push / promote / soft-deactivate versions | ✅ | ✅ | — |
| Update project settings (name, public, base URL, custom domain) | ✅ | ✅ | — |
| Mock-server overrides + chaos config | ✅ | ✅ | — |
| Delete a version | ✅ | ✅ | — |
| Delete the project | ✅ | — | — |
| Manage collaborators + roles | ✅ | — | — |
| Stripe billing + plan changes | ✅ | — | — |

**Project hide via per-project override.** On Business, an owner can set a per-project role override of `none` for a specific collaborator. That collaborator's PAT — and dashboard — gets `404 NOT_FOUND` for that project, even though they otherwise have account-wide access. Useful for acquisition-related projects, NDA-scoped specs, or zero-trust setups.

**Insufficient role response:**

```json
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Your role (viewer) doesn't have the \"version:write\" permission. Ask the project owner to grant a higher role."
  }
}
```

Pattern-match on `code: "FORBIDDEN"`; the `message` names the role and the missing permission. Returns `403`.

**Hidden project response:** `404 NOT_FOUND`. We deliberately don't differentiate "the project doesn't exist" from "you can't see this project" — a 403 there would let any token probe slug existence by guessing.

## Audit log (Business)

Every project mutation made on a Business account — whether from the dashboard or from a PAT — is recorded in the audit log with the actor's user_id, the action code, the timestamp, and a stable JSON metadata blob. API actions additionally stamp:
- `metadata.source = "api"` (vs `"dashboard"`)
- `metadata.token_id = "<uuid>"` — the PAT row that performed the action

If a token leaks, a forensic search by `metadata.token_id = '<uuid>'` surfaces every action that token took, regardless of which user or project. The list of action codes is in the OpenAPI spec; common ones: `PROJECT_CREATED`, `VERSION_CREATED`, `VERSION_PROMOTED_DEFAULT`, `PREVIEW_CREATED`, `COLLABORATOR_INVITED`, `COLLABORATOR_ROLE_CHANGED`, `TOKEN_CREATED`.

Free / Pro accounts skip the audit-log write entirely — the column exists, but recording it would be paying for rows nobody can read.

## What's not in v1

- **Mock server config** — overrides, chaos, auth enforcement: dashboard-only for now.
- **Theme tokens** — color palette + theme-mode lock: dashboard-only.
- **Collaborators** — invite / revoke: dashboard-only.
- **Webhooks (inbound + outbound)** — spec drift notifications, inbox config: dashboard-only.

These are queued for v2. Priority loosely tracks customer pull — if you need one of them programmatically, [tell us](mailto:info@outworx.io) and we'll likely move it up.


---

## Outworx CLI — push specs from anywhere

URL: https://docs.outworx.io/guides/cli
Category: Integration
Published: 2026-05-09
Reading time: 6 min

> Publish OpenAPI / Swagger / GraphQL specs to Outworx Docs from your laptop or any CI provider. One command, zero install graph, scriptable exit codes.
If your hosted docs lag behind your spec, the difference between "annoying" and "blocked at 2am" usually comes down to whether the publish step is one command or fifteen lines of `curl`. The Outworx CLI is the one-command path.

```bash
npx @outworx/cli push openapi.yaml --project payments-api
```

That's the whole thing. The CLI works on your laptop, in CI on any provider (GitHub Actions, GitLab, CircleCI, Buildkite, Jenkins…), and inside a pre-commit hook. This guide covers install, auth, configuration, and the flows worth wiring up.

## Install

The CLI runs on Node.js 18.17+ and ships as an npm package.

```bash
# One-shot via npx — recommended for CI, no global state
npx @outworx/cli push ...

# Or globally
npm install -g @outworx/cli
outworx push ...
```

There's no Docker image, no Python wrapper, no system service to install. It's a 30KB npm package that wraps the public REST API — so anything you'd expect from the `curl` examples is one CLI flag away, with better error messages.

## Authentication

Two token shapes — pick whichever matches your scope:

| Token | Prefix | Scope | Best for |
| --- | --- | --- | --- |
| Personal access token | `otwx_pat_*` | Account-wide; acts as the user who minted it | Multi-project CI, shared org secrets, preview deploys |
| Project upload token | `otwx_*` | Single project, spec upload only | Per-repo CI on one project, contractor pushes |

Mint either in [Settings](https://docs.outworx.io/settings). The dashboard shows the plaintext **once** — copy it, store it as a secret, and never check it into a repo.

Pass the token via `--token`, but `OUTWORX_TOKEN` env var is preferred — flags end up in shell history and process listings, env vars don't:

```bash
export OUTWORX_TOKEN=otwx_pat_...
outworx push openapi.yaml --project payments-api
```

In GitHub Actions:

```yaml
env:
  OUTWORX_TOKEN: ${{ secrets.OUTWORX_TOKEN }}
```

## The `push` command

The CLI has one command today: `push`. (More are tracked but pushing specs is the 95% workflow.)

### Push to the default version

```bash
outworx push openapi.yaml --project payments-api
```

This updates your project's current default version in place. After the push, your hosted docs reflect the new spec within seconds.

### Push to a specific version

```bash
outworx push openapi.yaml --project payments-api --version v2-beta
```

If the version doesn't exist, it's created. Useful for cutting a `v2` alongside an existing `v1` without retiring the old one.

### Preview push (PR-only deploys)

Preview pushes publish to `/preview/<pr>`, get filtered out of the public picker, never become the default, and auto-expire 14 days after the PR closes:

```bash
outworx push openapi.yaml \
  --project payments-api \
  --preview \
  --pr "$GITHUB_PR_NUMBER" \
  --commit "$GITHUB_SHA" \
  --branch "$GITHUB_HEAD_REF"
```

Preview pushes require a PAT (`otwx_pat_*`) — project upload tokens don't carry the `version:write` scope. The CLI rejects with a clear error if you try.

## Configuration file

For repos where every push goes to the same project, drop a config file at the repo root so you don't repeat `--project` and `--base-url` on every invocation:

```json
// outworx.json
{
  "project": "payments-api",
  "version": "v1",
  "baseUrl": "https://docs.outworx.io"
}
```

`.outworxrc.json` works too if you prefer dot-files. The CLI walks up from `cwd` to find the first match, so a config in your repo root applies anywhere underneath it.

Precedence (highest wins): CLI flag → env var → config file → built-in default.

## Environment variables

| Var | Equivalent flag |
| --- | --- |
| `OUTWORX_TOKEN` | `--token` |
| `OUTWORX_PROJECT` | `--project` |
| `OUTWORX_BASE_URL` | `--base-url` |

`OUTWORX_TOKEN` is the only one most users set. The others exist for the rare case where you don't want a config file but also don't want long flag-soup commands.

## Exit codes

The CLI returns standard, scriptable exit codes:

| Code | Meaning | What to do |
| --- | --- | --- |
| `0` | Success | Continue. |
| `1` | User error — bad flag, missing file, 4xx response | Fix the input. Don't retry. |
| `2` | Network or transient API error (5xx, ECONNREFUSED) | Re-run the workflow. |
| `3` | Internal error | [Open an issue](https://github.com/abdallaemadeldin/upload-spec-action/issues) with `DEBUG=1` output. |

Pattern-match on these in your CI's retry policy. GitHub Actions, for instance:

```yaml
- uses: abdallaemadeldin/upload-spec-action@v1
  with: { token: ${{ secrets.OUTWORX_TOKEN }}, project: foo, spec: ./openapi.yaml }
- name: Notify slack on user error
  if: failure() && steps.previous.outcome == 'failure'
  run: ...
```

## Full flag reference

```text
outworx push <spec-file> [options]

  --project <slug>          Project slug. Required (or OUTWORX_PROJECT env, or in outworx.json).
  --version <label>         Version label. Defaults to the project's default version.
  --token <token>           PAT or upload token. Required (or OUTWORX_TOKEN env).
  --base-url <url>          API base URL. Defaults to https://docs.outworx.io.
  --preview                 Push as a PR preview (PAT-only, expires in 14 days).
  --pr <number>             Preview-only — PR number for the banner.
  --commit <sha>            Preview-only — commit SHA for the banner.
  --branch <name>           Preview-only — branch name for the banner.

  --help, -h                Show help.
  --version, -v             Show CLI version.
```

## When to use the CLI vs the GitHub Action vs curl

- **GitHub Action** ([guide](/guides/auto-sync-github-actions)) — three lines of YAML. The right answer for any GitHub-hosted repo. The action wraps this CLI under the hood, so feature parity is automatic.
- **CLI** — laptop pushes (debugging, one-off republishes after a `git revert`), non-GitHub CI (CircleCI, GitLab, Buildkite), pre-commit hooks. The CLI is also the answer when you need to script around the publish step (e.g. push to a preview, run smoke tests, then promote).
- **curl** — the escape hatch when neither works. The dashboard's upload card has a pre-filled curl snippet, and the public REST API is the canonical reference if you ever need to wire Outworx into a custom tool.

## What gets audited

Every successful `push` writes a `SPEC_UPLOADED` row to the [audit log](/guides/audit-log) with the spec format, source (`api`), endpoint count, and the token id that performed the push. If a token leaks, you can find every action it ever took with one `metadata->>token_id = '<uuid>'` filter.

## Troubleshooting

**"Spec file not found"** — the path is relative to your current working directory. In GitHub Actions, the spec path is relative to the repo root after `actions/checkout`. Run `ls` in the workflow to verify.

**"Project slug is required"** — pass `--project`, set `OUTWORX_PROJECT`, or drop an `outworx.json` in your repo root.

**"Couldn't parse YAML at line N"** — the parser saw something it couldn't read. Validate locally first: `npx @redocly/cli lint openapi.yaml` is the fastest sanity check.

**"Preview pushes require a personal access token"** — you tried to use a project upload token (`otwx_*`) with `--preview`. Mint a PAT (`otwx_pat_*`) in [Settings → API tokens](https://docs.outworx.io/settings) and use that instead.

**"Network error talking to https://docs.outworx.io"** — exit code 2, transient. Re-run. If it persists, check [status.outworx.io](https://status.outworx.io).

## See also

- [GitHub Actions sync guide](/guides/auto-sync-github-actions) — the action that wraps this CLI.
- [REST API reference](/api) — every endpoint the CLI calls.
- [Audit log guide](/guides/audit-log) — where your push events end up.


---

## Audit log, SOC2 evidence + SIEM webhook

URL: https://docs.outworx.io/guides/audit-log
Category: Compliance
Published: 2026-05-09
Reading time: 8 min

> Every mutation across your projects is recorded. Filter, export to CSV, pipe to Datadog or Splunk via signed webhook, and pick a retention window that matches your compliance program.
Every action you take in Outworx Docs that mutates state — pushing a spec version, changing a collaborator's role, rotating an API token, flipping a project from private to public — gets a row in the audit log. SOC2 auditors expect that. Compliance teams ask for that. And the moment something goes sideways ("who set the production docs to private last Tuesday?") you'll be glad it's there.

This guide covers what we record, where to find it, how to pipe it into your SIEM, and how the SOC2 evidence dump path works.

## What's recorded

Every mutation that goes through the dashboard, the v1 REST API, or a system path (cron jobs, webhook deliveries, plan-limit enforcement) generates one audit log row. The action codes are stable, UPPER_SNAKE strings — pattern-match on them in your log pipeline without parsing the human-readable label.

| Category | Codes |
| --- | --- |
| Projects | `PROJECT_CREATED`, `PROJECT_UPDATED`, `PROJECT_DELETED`, `PROJECT_VISIBILITY_CHANGED`, `PROJECT_CUSTOM_DOMAIN_CHANGED` |
| Branding & theme | `BRANDING_UPDATED`, `THEME_UPDATED`, `CUSTOMIZATION_UPDATED`, `ENDPOINT_CUSTOMIZATION_UPDATED`, `ENDPOINT_CUSTOMIZATION_DELETED` |
| Versions | `VERSION_CREATED`, `VERSION_UPDATED`, `VERSION_DELETED`, `VERSION_PROMOTED_DEFAULT`, `VERSION_DEACTIVATED`, `VERSION_REACTIVATED`, `VERSION_BASE_URL_CHANGED` |
| Specs | `SPEC_UPLOADED`, `SPEC_EDITED`, `SPEC_DELETED`, `SPEC_SYNCED`, `SPEC_URL_CHANGED` |
| Previews | `PREVIEW_CREATED`, `PREVIEW_DELETED` |
| Collaborators | `COLLABORATOR_INVITED`, `COLLABORATOR_REMOVED`, `COLLABORATOR_ROLE_CHANGED` |
| API access | `TOKEN_CREATED`, `TOKEN_REVOKED`, `UPLOAD_TOKEN_GENERATED`, `UPLOAD_TOKEN_ROTATED`, `UPLOAD_TOKEN_REVOKED` |

Each row carries:

- **`actor_user_id`** — who performed the action (NULL for system events).
- **`action`** — one of the codes above.
- **`target_type`** + **`target_id`** — the resource that was touched.
- **`project_id`** — set on every project-scoped event so per-project queries are one indexed scan.
- **`metadata`** — JSONB with the field-level details. Always includes `source` (`dashboard` / `api` / `system`), and includes `token_id` when the action came from a personal access token. The forensic search "find every action this leaked token ever performed" is one filter: `metadata->>token_id = '<uuid>'`.
- **`created_at`** — server timestamp.

The audit log is a Business-plan feature. Free / Pro accounts skip the writes entirely — there's no viewer for them and we'd rather not pay for unread rows.

## Reading the log in the dashboard

The fastest way to inspect activity is the dashboard:

- **`/settings`** has a "Recent activity" card with the last 5 events at a glance.
- **`/settings/activity`** is the full viewer with filters: date range (UTC day boundaries), actor, project, and action category. Filters live in URL params, so deep-linking to a specific window for an auditor is just sending them a URL.

Each row shows a one-line description that summarises the metadata in plain English ("`bob@acme.com: editor → viewer (project override)`", "`Changed: Name, Visibility, Accent color`"). Click "Details" on any row to see the raw metadata JSON.

## CSV export for SOC2 evidence

When an auditor asks for "the full activity log for Q1", you do not want to be screen-scraping. Click **Export CSV** on `/settings/activity` and the same filter window downloads as a 14-column RFC-4180 CSV:

```
"timestamp","action","action_label","actor_id","actor_email","actor_name","source","token_id","project_id","project_slug","project_name","target_type","target_id","metadata"
```

- Project + actor uuids are resolved to slug + email so the CSV reads cleanly without joins.
- The `metadata` column carries the full JSON blob for every row — auditors can drill in without losing the structured data.
- Filename includes the date window: `outworx-audit_from-2026-01-01_to-2026-04-01.csv`.
- The endpoint sets `Cache-Control: private, no-store` — these dumps must not sit in any proxy or CDN cache.

The CSV path is also exposed at `/api/audit/export.csv?since=YYYY-MM-DD&until=YYYY-MM-DD&actor=<uuid|system|all>` for scripted pulls. Authenticated as the owner via session cookie; if you need a token-authed dump for a CI evidence pipeline, drop us a line — that's tracked.

## Real-time pipe to your SIEM

Settings → **Audit log delivery & retention** → set a **Webhook URL** to start streaming events as they happen. We POST one JSON body per row:

```http
POST https://your-receiver.example.com/audit
Content-Type: application/json
X-Outworx-Event: PROJECT_UPDATED
X-Outworx-Delivery: 8c7f...e1a3
X-Outworx-Signature: sha256=ab12...cd9f
User-Agent: Outworx-Audit-Webhook/1

{ "id": "8c7f...e1a3",
  "account_user_id": "...",
  "actor_user_id": "...",
  "action": "PROJECT_UPDATED",
  "target_type": "project",
  "target_id": "p_...",
  "project_id": "p_...",
  "metadata": { "source": "dashboard", "fields": ["name", "is_public"] },
  "created_at": "2026-05-09T20:23:14.000Z"
}
```

Verify the signature in your receiver:

```ts
import { createHmac, timingSafeEqual } from "crypto";

function verify(rawBody: string, header: string | undefined, secret: string) {
  if (!header?.startsWith("sha256=")) return false;
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const provided = header.slice("sha256=".length);
  if (provided.length !== expected.length) return false;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
}
```

Use the **raw body bytes** for HMAC — don't re-serialize JSON before checking. The `X-Outworx-Delivery` header carries the audit event uuid, so receivers that occasionally see retries can dedupe by it.

Delivery is best-effort: a 5xx or network failure is logged on our side but does not block the underlying mutation, and we don't queue retries. If you need durability, the receiver should write to its own queue immediately and ack with a 200 — same pattern as Stripe webhooks.

## Retention

Rows live in the `audit_log` table for the **retention window** you set (Settings → **Audit log delivery & retention**). Default is **730 days** (2 years), which covers the standard SOC2 Type II evidence window. Allowed range: 30 days to 10 years.

A daily prune job at 03:23 UTC deletes rows past the cutoff. If you need rows older than the prune cutoff, the canonical store is your SIEM via the webhook above — that's why webhook delivery is independent of retention. Rows ship in real time, so your receiver has a copy regardless of how short the dashboard retention is.

## Permissions for collaborators

Only the **account owner** can read the audit log. Collaborators — even Editors — never see Settings, so they don't see the activity feed. This is by design: the audit log is forensic evidence and shouldn't be visible to the actors whose actions it records.

If you need a delegated "compliance auditor" role, talk to us — that's tracked but not yet shipped.

## What audit-log rows are NOT

A few things to set expectations:

- **Reads aren't audited.** Opening the docs page, hitting `GET /api/v1/projects`, or running a `/chat` query doesn't generate a row. The audit log is a mutation log; if you need read-side analytics, the Project Analytics tab is the surface for that.
- **Mock-server traffic isn't in the audit log.** Mock-server requests are captured separately on the Mock tab — that table is for debugging your integrations, not for SOC2 evidence.
- **Webhook deliveries to YOUR webhooks aren't audited.** If you're using Outworx's webhook tester / proxy, the event captures are in `/webhooks`, not the audit log.

## See also

- [Personal access tokens guide](/guides/rest-api) — how to mint a PAT, and how `metadata.token_id` flows from there to the audit log.
- [REST API reference](/api) — every action that has a v1 endpoint generates the same audit row a dashboard click would.
- [SOC2 trust page](/security) — broader controls beyond the audit log.


---

## PR preview deploys — every pull request gets its own docs URL

URL: https://docs.outworx.io/guides/pr-previews
Category: Integration
Published: 2026-05-09
Reading time: 7 min

> Push specs from CI with `--preview` and Outworx spins up a throwaway version with a banner showing PR / branch / commit. 14-day rolling TTL, hidden from public version listings, three lines of GitHub Action.
Reviewing API changes used to mean checking out the branch, regenerating the docs, hosting them somewhere, and praying nobody else opens a different PR before yours merges. PR preview deploys collapse that into a single workflow line: push the spec from CI with `--preview`, your reviewer clicks a link, the preview expires when the PR closes.

```bash
outworx push openapi.yaml \
  --project payments-api \
  --preview \
  --pr 247 \
  --commit $GITHUB_SHA \
  --branch $GITHUB_HEAD_REF
```

That's the whole flow. The result is a hosted preview at `/<slug>/preview/<pr>` with an amber **PREVIEW** banner showing the PR number, branch, and commit SHA — so reviewers can't accidentally cite a preview URL as the live docs. This guide covers when to use it, how to wire it into GitHub Actions, the lifecycle semantics, and the gotchas.

## What a preview deploy actually is

A preview is a regular `project_versions` row with `is_preview = true` plus three pieces of PR metadata: the PR number, the commit SHA, and the branch name. Outworx treats it differently than your release versions in five specific ways:

- **Hidden from listings.** `GET /api/v1/projects/<slug>/versions` excludes preview rows by default. Pass `?include_previews=true` for admin tooling. The public docs version dropdown also hides them — your customers see your shipped versions, your reviewers see the PR's version.
- **Never the default.** Even if you push a preview as the only version, it won't get promoted. The single-default invariant only applies to non-preview versions.
- **Separate plan cap.** Preview versions count against `maxPreviewsPerProject` (5 on Pro, 20 on Business), not the regular `maxVersions` cap. Previews can't crowd out release versions.
- **14-day rolling TTL.** Each push pushes the expiry forward by 14 days. A slow review keeps its preview; an abandoned PR auto-cleans up. Pruning runs in `pg_cron` at 03:23 UTC.
- **Re-pushes update the same row.** Push the same preview label again on a later commit and the existing row updates (TTL rolls forward, embeddings + cached MCP types invalidate). No 409, no drift previews piling up.

## Wiring it into GitHub Actions

The smallest functional workflow:

```yaml
name: Docs preview
on:
  pull_request:
    paths:
      - 'openapi.yaml'

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: abdallaemadeldin/upload-spec-action@v1
        with:
          token: ${{ secrets.OUTWORX_TOKEN }}
          project: payments-api
          spec: openapi.yaml
          preview: true
          pr: ${{ github.event.pull_request.number }}
          commit: ${{ github.event.pull_request.head.sha }}
          branch: ${{ github.event.pull_request.head.ref }}
```

Three things matter here:

1. **`paths` filter** keeps the workflow from re-running when unrelated files change. Without it, every commit on the PR republishes — fine, but wasteful.
2. **`preview: true`** is the toggle. Without it, the action does a regular release-version push.
3. **The token must be a personal access token (`otwx_pat_*`).** Project upload tokens (`otwx_*`) don't support preview semantics — the CLI rejects the combo upfront with a clear error message.

If you also want a comment on the PR linking to the preview URL, add a follow-up step:

```yaml
- name: Comment with preview URL
  uses: actions/github-script@v7
  with:
    script: |
      const url = `https://docs.outworx.io/payments-api/preview/${context.issue.number}`;
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: `📚 Docs preview: ${url}`,
      });
```

## Other CI providers

The CLI works anywhere Node 20+ runs. The flag shape is identical; only the env var lookup changes:

```bash
# GitLab CI
outworx push openapi.yaml --project payments-api --preview \
  --pr "$CI_MERGE_REQUEST_IID" \
  --commit "$CI_COMMIT_SHA" \
  --branch "$CI_COMMIT_REF_NAME"

# CircleCI
outworx push openapi.yaml --project payments-api --preview \
  --pr "$CIRCLE_PULL_REQUEST" \
  --commit "$CIRCLE_SHA1" \
  --branch "$CIRCLE_BRANCH"

# Buildkite
outworx push openapi.yaml --project payments-api --preview \
  --pr "$BUILDKITE_PULL_REQUEST" \
  --commit "$BUILDKITE_COMMIT" \
  --branch "$BUILDKITE_BRANCH"
```

## Plan limits

The preview cap is a separate dial from regular versions. Pro projects can hold up to 5 active previews; Business up to 20. CI re-pushing the SAME preview label updates the existing row, so the cap only fires when CI tries to open a NEW preview while at the limit. If you hit it, close a stale PR (or delete its preview row from the dashboard) and re-run.

The 14-day TTL is rolling, not absolute — every push pushes the expiry forward. So a long-running PR keeps its preview as long as commits keep landing. Once the PR closes (merge or cancel) and no further pushes come in, the preview expires on its own and the prune cron sweeps it.

## What happens at merge

Merging the PR doesn't automatically promote the preview. The preview keeps its preview status — you push a regular release version (without `--preview`) on the merge commit if you want it to become the default:

```yaml
on:
  push:
    branches: [main]
    paths:
      - 'openapi.yaml'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: abdallaemadeldin/upload-spec-action@v1
        with:
          token: ${{ secrets.OUTWORX_TOKEN }}
          project: payments-api
          spec: openapi.yaml
          # No preview flag → regular release push
```

This split is intentional. A merged PR isn't the same as a release — the merge commit might land alongside other unrelated work, the docs version might lag the code release by a day, etc. Keeping the release push as a separate workflow file gives you that control.

## Gotchas

- **Branch name length.** GitHub branches max out around 244 chars; the preview metadata caps a hair higher (256). Truncate or skip the `--branch` flag for unusual setups.
- **Commit SHA format.** The CLI accepts 7-64 hex chars. GitHub's `$GITHUB_SHA` is the full 40-char SHA. CI variables that give you a short SHA (`$CIRCLE_SHA1` is full, `$BITBUCKET_COMMIT` is short) both work.
- **Preview URL in the banner.** The banner links back to the GitHub PR thread when the metadata is present. If you skip the `--branch` or `--commit` flags, the banner still renders but the link target is the docs preview itself.
- **Embeddings + MCP types.** Each push invalidates the version's embedding index and any cached generated TypeScript types. If you have an MCP client connected to the preview version, it'll fetch fresh types on the next call.
- **Audit log entry.** Every preview push writes a `PREVIEW_CREATED` row to the audit log on Business plans, with the PR / commit / branch in `metadata`. Useful for forensic traces ("which CI run pushed this preview?") via the `metadata.token_id` field.

## When to reach for it vs alternatives

PR previews are the right tool when reviewers need to **see the rendered docs**, not just the spec diff. If your team's review flow is "look at the YAML changes, approve" you can probably get by with [Spec Diff](/tools/spec-diff) alone — it posts a sticky comment classifying every change as breaking / additive / cosmetic.

PR previews are most valuable when:

- You ship customer-facing API docs and want product / support / partners to review the rendered output
- Your changes touch markdown overrides or per-endpoint customizations (those don't show up in a spec diff)
- You want a stable URL to share with an enterprise prospect mid-review

You can run both in parallel. The combination — diff comment + clickable preview URL — is what most production-grade API teams ship.

Now wire it up.


---

## Migrate from Apidog in 20 Minutes

URL: https://docs.outworx.io/guides/migrate-from-apidog
Category: Migration
Published: 2026-05-03
Reading time: 9 min

> Drop Apidog's per-seat pricing and desktop client. 20-minute migration onto Outworx Docs ($9–19/mo flat) with mocks, custom domain, and SEO-safe redirects.
If you've been on **Apidog** for a while and the per-seat invoice has started to look like an enterprise CRM bill — this guide gets you off it and onto Outworx Docs in about twenty minutes. We'll cover exporting your spec, recreating your collections, migrating mocks, dropping the desktop client, and the redirects that protect your SEO during the cutover.

Apidog bundles design + mocking + docs + testing into a single desktop app. That's a great pitch on day one. By month six, the per-seat model means a five-person team is paying $45+/mo before adding a single hosted mock, the desktop app's nag-screens get tiresome, and you're stuck with a workflow that requires a heavy install on every machine. If that sounds familiar, keep reading.

## Step 1 — Export your spec from Apidog (3 minutes)

Apidog stores everything as proprietary project files internally, but exports cleanly to OpenAPI 3.x.

1. Open your Apidog project (desktop or web)
2. **Project settings** → **Export**
3. Choose **OpenAPI 3.0 / 3.1** (the JSON form is most portable)
4. Untick "include test cases" — those don't migrate; they're Apidog-specific
5. Save the file

You get a `.json` file. If you have multiple environments configured in Apidog, the export bundles their `servers:` block automatically. Confirm the active environment is the one you want as the default in production — Outworx will use the first server from that list as the default Try It target.

If your Apidog project uses **shared schemas** (the `Components` panel), they all come through under `components/schemas` correctly. If you've used Apidog's "data models" feature with cross-project references, flatten those to one project before exporting — cross-project `$ref` doesn't survive the round-trip.

## Step 2 — Upload to Outworx Docs (1 minute)

1. Sign up at [docs.outworx.io](https://docs.outworx.io) — free tier, no credit card.
2. Click **New Project**, name it after your API, pick a slug. This becomes your default URL: `yourslug.docs.outworx.io`.
3. **API Spec** tab → **Upload** → drag in the JSON.

Your docs go live immediately. Every endpoint, every parameter, every example. The Try It playground works against your real API the moment it's uploaded — the same way Apidog's "Run" tab worked, but in the browser, with no desktop install and no per-seat tax.

## Step 3 — Recreate your environments (2 minutes)

Apidog environments map to Outworx **base URL overrides**. For each environment in your Apidog project:

- **Settings → Base URL** in Outworx accepts a single override per project, or per-version if you've set up multiple versions
- The default base URL comes from the spec's `servers[]` entry
- Per-version overrides let you ship `v1` against the staging server and `v2` against production while developers test the migration

This is intentionally simpler than Apidog's environment switcher — most teams found Apidog's per-environment override matrix harder to reason about than per-version base URLs. If you really do need three+ environments per version, the pattern is one Outworx project per environment, all reading from the same source spec via auto-sync (Step 5).

## Step 4 — Migrate your mocks (5 minutes)

This is the part that always sounds scary and turns out to be straightforward.

**Apidog's "Cloud Mock"** maps almost 1:1 to Outworx's hosted mock URL. Both ship a path-based mock the moment a spec is uploaded. The differences:

| Apidog Cloud Mock | Outworx Mock Server |
| --- | --- |
| Paid plan only | **Free on every plan** (10k req/mo on Free) |
| Static example responses | Schema-walked + faker-extended responses |
| Intelligent mock (paid add-on) | Dynamic templating built-in (`{{$uuid}}`, `{{request.body.X}}`, faker) |
| Shared per workspace | Per-project URL, per-version routing |
| Stateful overrides via "Smart Mock" | **Stateful overrides** with deep-partial body matching, dynamic templating, priority |
| No chaos / latency simulation | **Chaos mode** (latency band + error rate) for retry-code testing |

**To migrate the mocks themselves:**

1. The base mock URL on Outworx is `docs.outworx.io/mock/<your-slug>/...` — same path shape Apidog used.
2. Update your frontend / test code to point at the new host. Most teams put this behind an env var (`process.env.NEXT_PUBLIC_MOCK_BASE`) so the swap is one config change.
3. If you had Apidog "Smart Mock" rules — pin them as Outworx **stateful overrides** in the dashboard. Match by method + path + optional query / headers / partial JSON body. The override editor is a side-by-side panel; you'll spend ~30 seconds per rule.
4. If you used Apidog's "Match Conditions" for response variants — that's the Outworx `Prefer: example=<name>` header pattern. Cleaner than Apidog's conditions panel because it lives in the request itself, not in mock-server config.

If you have ten or more mocks to migrate, use the **Mock Override Import** in Outworx — paste a JSON bundle in the format described in the [Mock Servers guide](/guides/mock-servers#step-9-import-export-override-bundles) (`{ version: 1, exportedAt, overrides: [...] }`) and the rules get inserted one-by-one with merge or replace strategies. A small adapter script to convert Apidog's export format is usually under 30 lines of `jq`.

## Step 5 — Auto-sync from your spec source (2 minutes)

Apidog stores the spec as a project file inside its app. Outworx supports **auto-sync from a public URL**. If your spec lives in:

- A public GitHub repo (`https://raw.githubusercontent.com/.../openapi.json`)
- An S3 / R2 bucket
- A CDN URL emitted by your CI

…paste it into **Settings → Auto-sync** and pick a cadence (hourly, daily, weekly). Outworx re-fetches and re-parses on schedule; your hosted docs always match what's live.

For private specs, push from your CI on every merge to main. The companion guide [Auto-sync OpenAPI Docs from GitHub Actions](/guides/auto-sync-github-actions) has a copy-paste workflow.

## Step 6 — Migrate your custom domain (5 minutes)

If your Apidog docs lived at `docs.yourcompany.com`, keep them there.

**On Outworx Docs** (Business plan, $19/mo flat — vs Apidog's per-seat Team plan):

1. **Settings → Custom domain** → enter `docs.yourcompany.com`
2. Copy the CNAME target

**On your DNS provider:**

1. Edit (don't delete) the existing CNAME pointing at Apidog
2. Change it to point at Outworx's target
3. Cloudflare specifically: set proxy to **DNS only** (grey cloud). Outworx provisions its own Let's Encrypt cert; Cloudflare's orange-cloud proxy double-encrypts and breaks things.

Wait 1–5 minutes for propagation. Outworx polls and auto-issues SSL the moment the CNAME resolves. Green "Verified" badge appears in the dashboard.

## Step 7 — Keep your SEO with proper redirects (3 minutes)

Apidog's hosted docs paths typically look like `/api-doc/<workspace>/<endpoint-id>`. Outworx paths look like `/endpoints/<operationId>`. Google has indexed the old shape; if endpoint pages 404 after the switch, your hard-earned rankings disappear.

Two safe paths:

**Option A — keep Apidog alive for 30 days.** Run both in parallel. Add a Cloudflare Page Rule (or equivalent) redirecting old paths to new:

```
docs-old.yourcompany.com/api-doc/* → docs.yourcompany.com/endpoints/$1
```

After Google reindexes (~30 days), cancel the Apidog subscription.

**Option B — accept a temporary dip.** Skip redirects. Rankings recover in 4–8 weeks once Google sees Outworx serving canonical content. Cheaper, slightly more painful.

Most teams use Option A. The 30-day overlap is the cost of a clean migration; saving the seat fees usually covers the parallel month easily.

## What you gain by leaving Apidog

- **Flat pricing.** $9 Pro for 10 projects + 3 collaborator seats. $19 Business for unlimited + 10 seats. No per-seat tax. A 10-engineer team pays $19/mo total instead of $90+/mo per seat.
- **Browser-only.** No desktop app to install on every machine, no auto-update prompts, no "open the desktop app to access this feature" friction. Open a tab, paste a spec URL, share the docs.
- **Free hosted mock server on every plan.** Apidog gates Cloud Mock behind paid plans. Outworx's mock server is on Free, with stateful overrides, dynamic templating, and chaos mode all included.
- **Per-project MCP server.** Plug your API directly into Claude Desktop, Cursor, Cline, or Continue. Apidog has no equivalent — its AI features are stuck inside the desktop client.
- **Real GraphQL execution.** Outworx's mock server executes GraphQL queries against your SDL — selection-set aware, with realistic samples. Apidog's GraphQL support is REST-shaped and doesn't run real queries.
- **Pricing honesty.** $9 / $19. No "Contact Sales" enterprise gating, no annual-only discount tier.

## What you give up

To be honest about it — Apidog has a few features Outworx does not:

- **Postman-style request collections** with full env-var management. Outworx's Try It is per-endpoint; if you need a multi-step "run this collection in order" UX, keep a Postman collection for those flows.
- **Built-in load testing.** Apidog has a basic load tester. Outworx's chaos mode is a per-request latency / error simulator, not a load generator. Use k6 or Artillery if load testing is mission-critical.
- **API design / linting GUI.** Apidog has a visual editor for the spec itself. Outworx treats the spec as source of truth and assumes you edit it in code. If you do all your spec editing in a GUI, this is a workflow change.

For most teams these aren't dealbreakers — they're using Apidog 90% for hosted docs + mocks, and the missing 10% is well-served by best-of-breed tools.

## After the migration

Wire up auto-sync so the docs stay in lockstep with your repo. Either:

- Paste your spec URL into the project settings — we fetch on hourly / daily / weekly cadence
- Or push from CI: see [Auto-sync API Docs from GitHub Actions](/guides/auto-sync-github-actions)

Then connect your AI assistant via MCP: [Connect Claude Desktop to Your API Docs via MCP](/guides/connect-claude-desktop-mcp).

That's the full migration. Most teams finish in under thirty minutes. Save yourself the per-seat tax and the desktop install.

[Start your migration →](https://docs.outworx.io)


---

## Migrate from Swagger UI to Hosted Docs

URL: https://docs.outworx.io/guides/migrate-from-swagger-ui
Category: Migration
Published: 2026-05-03
Reading time: 7 min

> Stop self-hosting Swagger UI. 10-minute migration onto Outworx Docs with a real Try It playground, free mock server, AI chat, and zero infrastructure.
If you've been running **Swagger UI** as your hosted API documentation — congrats, you saved $99/mo by not paying ReadMe. But you also paid for it in time: maintaining a server, updating the build pipeline, dealing with the dated default theme, and watching developers complain that the "Try it out" button only sort-of works for anything beyond a `GET`. This guide gets you off that and onto Outworx Docs in about ten minutes — same hosted-URL price as Swagger UI ($0), with a real Try It playground, a free mock server, AI features, and zero infrastructure to maintain.

We'll cover: getting your spec into Outworx, redirecting your old Swagger UI URLs, decommissioning the server it runs on, and the things Swagger UI doesn't do that you'll want to use immediately.

## Why teams leave Swagger UI

Three reasons in roughly this order:

- **Server maintenance.** Swagger UI is a static site, but the static site lives somewhere — Nginx config, a Vercel deploy, an S3 bucket with CloudFront, a Docker container behind your load balancer. Every team has to choose, deploy, monitor, and update it. The total time-to-maintain is non-zero.
- **Dated default theme.** Swagger UI's signature green-and-white design is functional but instantly recognizable as "we used the open-source default." For teams that care about the visual quality of their developer experience, custom CSS overrides are an ongoing tax.
- **Try-it-out is barebones.** The built-in playground sends a request, but headers / auth / examples are limited compared to what modern devs expect from Postman or Insomnia. Most teams that ship Swagger UI quietly tell developers "use Postman for actual testing."

If any of those are real friction at your team, this migration takes ten minutes and removes them.

## Step 1 — Locate your spec (1 minute)

Swagger UI doesn't store your spec — it just renders one. Your spec lives somewhere else: a file in your repo, a URL emitted by your backend, or an artifact built by CI.

Find the canonical source. Common patterns:

- **A static `swagger.json` in your repo** — `docs/swagger.json` or similar
- **A live endpoint** — `https://api.yourcompany.com/openapi.json` (FastAPI, NestJS Swagger module, Express + swagger-jsdoc)
- **A CI artifact** — built from server-code annotations, uploaded to S3 / CDN

You'll need either the file or the URL for Step 2. If you're not sure, look at how Swagger UI is currently configured — its `SwaggerUIBundle({ url: '...' })` config tells you exactly where it's reading from.

## Step 2 — Upload to Outworx Docs (1 minute)

1. Sign up at [docs.outworx.io](https://docs.outworx.io) — free tier, no credit card.
2. Click **New Project**, name it after your API, pick a slug. This becomes your default URL: `yourslug.docs.outworx.io`.
3. **API Spec** tab → either drag in the file, or paste the URL.

Your docs go live immediately. Every endpoint, every parameter, every example. The Try It playground works against your real API the moment it's uploaded — and unlike Swagger UI's built-in version, it handles auth headers (Bearer / API key / Basic / OAuth2) cleanly, persists them across endpoints, and supports real request bodies for POST / PUT / PATCH.

## Step 3 — Wire auto-sync (2 minutes)

Swagger UI required you to redeploy or refresh the build to pick up spec changes. Outworx auto-syncs.

If your spec lives at a public URL:

1. **Settings → Auto-sync** → paste the URL
2. Pick a cadence: hourly, daily, or weekly

Outworx re-fetches and re-parses on schedule. Your hosted docs always match what's live in production. No redeploy, no CI hook, no manual upload.

If your spec is generated from server code and there's no public URL — push it from CI. The companion guide [Auto-sync OpenAPI Docs from GitHub Actions](/guides/auto-sync-github-actions) has a copy-paste workflow.

## Step 4 — Migrate your custom domain, if any (5 minutes)

If your Swagger UI lived at `docs.yourcompany.com`, keep it there.

**On Outworx Docs** (Business plan, $19/mo for custom domain — vs free Swagger UI but with the server cost behind it):

1. **Settings → Custom domain** → enter `docs.yourcompany.com`
2. Copy the CNAME target

**On your DNS provider:**

1. Edit (don't delete) the existing CNAME / A record pointing at your Swagger UI host
2. Change it to point at Outworx's CNAME target
3. Cloudflare specifically: set proxy to **DNS only** (grey cloud). Outworx provisions its own Let's Encrypt cert; Cloudflare's orange-cloud proxy double-encrypts and breaks things.

Wait 1–5 minutes for propagation. Outworx polls and auto-issues SSL the moment the CNAME resolves. Green "Verified" badge appears in the dashboard.

If you don't need a custom domain — your docs live at `yourslug.docs.outworx.io` and you're done. Free tier covers this.

## Step 5 — Keep your SEO with proper redirects (3 minutes)

Swagger UI uses URL fragments for navigation: `docs.yourcompany.com/#/operations/listUsers`. Google sometimes indexes these, sometimes not — depends on whether you've enabled `deepLinking: true` in your Swagger UI config.

**If your Swagger UI URLs are indexed in Google:**

Outworx paths look like `/endpoints/<operationId>` (no fragment). Two safe paths:

**Option A — keep Swagger UI alive for 30 days.** Run both in parallel on different subdomains. Add a redirect rule on the new domain:

```
docs.yourcompany.com/#/operations/* → docs.yourcompany.com/endpoints/$1
```

After Google reindexes (~30 days), tear down the Swagger UI server.

**Option B — accept a temporary dip.** Skip redirects. Rankings recover in 4–8 weeks once Google sees Outworx serving canonical content. If your Swagger UI traffic was modest, this is fine.

**If your Swagger UI URLs aren't well-indexed** (the common case — fragment-based URLs are fragile for SEO), skip this step entirely. Outworx's per-endpoint pages will index cleanly from day one.

## Step 6 — Decommission your Swagger UI server (5 minutes)

Once Outworx is serving your docs and the DNS has cut over, the old infrastructure can go away.

Common Swagger UI hosting setups and their teardown:

- **Vercel / Netlify deploy** — delete the project from the dashboard. Free, takes 30 seconds.
- **Docker container** behind your load balancer — remove the container from your compose file or k8s manifest. One PR.
- **Static site on S3 + CloudFront** — empty the bucket, delete the distribution. Saves you the CloudFront request charges.
- **Inside your main app** as a `/docs` route — remove the Swagger UI dependency, drop the route. Smaller bundle.

The savings depend on the setup. For most teams it's the CloudFront / Vercel cost (~$5-20/mo) plus the CI minutes building the docs site (~$10/mo). Modest in dollars, real in mental overhead.

## What you gain by leaving Swagger UI

- **Real Try It playground.** Headers persist across endpoints, auth flows actually work, multipart uploads supported, response previews are pretty. The Swagger UI defaults are functional; Outworx's playground is what teams currently use Postman *alongside* Swagger UI to get.
- **Free hosted mock server on every plan.** Every Outworx project gets a hosted mock URL the moment its spec uploads. Schema-walked responses, dynamic templating (`{{$uuid}}`, request echoing, faker), stateful overrides. Swagger UI ships nothing for mocking.
- **AI chat trained on your spec** (Pro / Business). Visitors can ask "how do I authenticate?" and get a real answer with clickable endpoint citations. Swagger UI shows the spec; Outworx explains it.
- **Per-project MCP server** (Pro / Business). Plug your API directly into Claude Desktop, Cursor, Cline, or Continue. The AI tools your team is already using can operate your API. Swagger UI has no equivalent.
- **Custom branding.** Your logo, your accent color, your favicon — built-in, not a custom CSS fork. (Pro / Business)
- **Custom domain with auto-SSL.** One CNAME, no Let's Encrypt cron, no certbot config. (Business)
- **Multi-version support.** Multiple active spec versions per project with a dropdown switcher and per-version base URLs. Swagger UI does not handle this gracefully.
- **Auto-sync from spec URL.** Your hosted docs always match what's live. No redeploys. Swagger UI requires a build / push every time the spec changes.
- **Webhooks playground.** Browser-side HMAC verifier for ten providers + capture / replay endpoint per inbox. Adjacent to your docs, included on Free.

## What you give up

To be honest about it — Swagger UI has one thing Outworx does not:

- **Self-hosting.** If your security posture requires the docs renderer to run inside your VPC with no third-party hosting, Swagger UI's static-site nature is a real advantage. Outworx is a hosted service. For 95% of teams this isn't a constraint, but if it is for yours, this guide doesn't apply.

If you're not in the self-hosting-required camp, the migration is pure upside.

## After the migration

Wire up auto-sync so the docs stay in lockstep with your repo. Either:

- Paste your spec URL into the project settings — we fetch on hourly / daily / weekly cadence
- Or push from CI: see [Auto-sync API Docs from GitHub Actions](/guides/auto-sync-github-actions)

Then connect your AI assistant via MCP: [Connect Claude Desktop to Your API Docs via MCP](/guides/connect-claude-desktop-mcp).

That's the full migration. Most teams finish in under fifteen minutes. The hardest part is usually deciding what to do with the Vercel/CloudFront budget you just freed up.

[Start your migration →](https://docs.outworx.io)


---

## Free Hosted Mock Server for Every API Spec

URL: https://docs.outworx.io/guides/mock-servers
Category: Integration
Published: 2026-05-02
Reading time: 18 min

> Every OpenAPI, Swagger, and GraphQL spec on Outworx Docs gets a free hosted mock URL on upload — with stateful overrides, templating, validation, and chaos.
Every API spec on Outworx Docs gets a free hosted mock URL the moment you upload it. Point your client at that URL and the responses come from the spec itself — examples, schemas, GraphQL types — so frontend work, integration tests, and SDK demos can run before the real backend exists. No CLI, no proxy, no separate "mock service" subscription.

This guide is the full reference: URL conventions, the `Prefer` header, stateful overrides, GraphQL support, per-version routing, the activity feed, and the diagnostic headers we ship with every response.

## Prerequisites

- An Outworx Docs project with at least one OpenAPI 3, Swagger 2, or GraphQL SDL spec uploaded
- The project must be **public** and **not password-protected** — the mock URL inherits the same access gate as the rendered docs

If your project is private the mock route returns `404` to anonymous traffic. Flip **Make documentation publicly accessible** under Settings → General to enable mocking.

## Step 1: Find your mock URL

Open any project in the dashboard and click the **Mock** tab. The Overview sub-tab shows the base URL for your project:

```
https://docs.outworx.io/mock/<your-slug>
```

For an OpenAPI/Swagger spec, append the path you'd hit on the real API:

```bash
curl https://docs.outworx.io/mock/acme/users/42
```

For a GraphQL spec, post to `/graphql`:

```bash
curl https://docs.outworx.io/mock/acme/graphql \
  -H 'content-type: application/json' \
  -d '{"query":"{ user(id: \"42\") { id name } }"}'
```

GraphQL also accepts `GET ?query=...` for quick browser testing.

## Step 2: How responses are synthesised

The mock engine walks the spec to build a response, in this priority order:

1. **A matching stateful override** (covered in step 4).
2. **A named example** from the operation's `examples` map — picked by `Prefer: example=<name>`, `random`, or `sequential`.
3. **The first `example` field** declared on the response or schema.
4. **A schema walk** — every property gets a sensible value from its type, format, enum, or pattern. `$ref`, `allOf`, and `oneOf` are resolved.
5. **An empty body** if the response defines no schema (e.g. `204`).

Every response carries an `X-Mock-Synth` header that tells you which path was taken: `override`, `example:<name>`, `example:random`, `example:sequential`, `schema`, or `empty`. When a request misses the spec entirely you get `X-Mock-Synth: fallback` with a `404`.

## Step 3: Steer responses with the Prefer header

[RFC 7240](https://datatracker.ietf.org/doc/html/rfc7240) defines `Prefer` as a way for clients to nudge servers — we use it as the steering wheel for mock responses:

| Header                          | Effect                                                              |
| ------------------------------- | ------------------------------------------------------------------- |
| `Prefer: code=404`              | Return the operation's `404` response instead of its `200`.         |
| `Prefer: example=randomized`    | Pick a random named example each call (see note below).             |
| `Prefer: example=sequential`    | Round-robin through the examples — handy for pagination tests.      |
| `Prefer: example=user-not-found`| Return the example named `user-not-found`.                          |

Stack them with commas: `Prefer: code=400, example=invalid-email`.

The sequential counter is per `(project, version, path, method, status)` and stored in Redis with a 24-hour TTL — restart-safe across deploys without leaking state forever.

A note on `random`: with five examples you'd expect even distribution, but small-sample runs of three or four calls regularly bunch up. That's normal — the rolling distribution evens out across ~30 calls.

## Step 4: Stateful overrides

Examples are static. Real apps need to demo states — "what does the UI look like when the user is rate-limited?" or "what happens if the order is in `pending_review`?" The Mock → Overrides sub-tab is where you set those up.

An override is a rule: **match these requests, return this response.** Each override lives at a specific endpoint (or `*` to match across all of them) and has:

- **Status code** and **response body** (any JSON).
- **Latency** in ms — useful for testing loading states.
- **Priority** — higher numbers win when multiple overrides match. Ties break by most-recently-updated.
- **Optional matchers**: query parameters, request headers, request body shape, GraphQL operation name.
- **Optional version scoping** — restrict an override to one version of the spec.

The matcher set is **deeply partial**: `{ "user": { "role": "admin" } }` matches any body that contains `user.role === "admin"`, regardless of what else is there. Headers and query strings work the same way. First match wins, sorted by priority desc.

The fastest way to create one is the **Duplicate** button on an existing override — clones every field including matchers so you can tweak one knob without re-typing the rest.

When an override fires the response includes `X-Mock-Synth: override`, `X-Mock-Override-Id: <uuid>`, and the body you defined. The activity feed (next step) tags the request with the override's name so you can audit which rule ran.

## Step 5: Dynamic templating in override responses

Static overrides only get you so far. The moment you need a fresh UUID per call, the current timestamp, or to echo back the user's email from the request body, a hand-rolled mock service starts to look attractive. Outworx ships a built-in templating engine so you don't have to.

Anywhere you can put a string in an override — the response body, a response header value, the Content-Type — `{{...}}` placeholders get rendered just before the response goes out the wire. Syntax is Mustache-style so it lines up with what you'd write in Postman, Handlebars, or any other tool you've used.

```json
{
  "id": "{{$uuid}}",
  "email": "{{request.body.email}}",
  "createdAt": "{{$now}}",
  "score": "{{$randomInt:0:100}}"
}
```

**Identifier and time tokens:**

- `{{$uuid}}` / `{{$guid}}` — fresh UUID v4 per request
- `{{$now}}` — current ISO 8601 timestamp
- `{{$timestamp}}` — current Unix seconds
- `{{$timestampMs}}` — current Unix milliseconds
- `{{$randomDate}}` / `{{$randomPastDate}}` / `{{$randomFutureDate}}` — `YYYY-MM-DD` within ±1 year

**Numbers:**

- `{{$randomInt}}` — integer 0–1000
- `{{$randomInt:1:100}}` — integer in your range
- `{{$randomFloat}}` — float 0–1000 with two decimals
- `{{$randomBool}}` — `true` / `false`

**Realistic fakes:**

`{{$randomEmail}}`, `{{$randomFirstName}}`, `{{$randomLastName}}`, `{{$randomFullName}}`, `{{$randomUserName}}`, `{{$randomPhone}}`, `{{$randomUrl}}`, `{{$randomIp}}`, `{{$randomColor}}`, `{{$randomCity}}`, `{{$randomCountry}}`, `{{$randomCompany}}`.

**Request echoing:**

- `{{request.method}}` — `GET`, `POST`, etc.
- `{{request.path.id}}` — for an override on `/users/{id}`, this resolves to whatever the caller put in the URL
- `{{request.query.page}}` — value of `?page=…`
- `{{request.headers.authorization}}` — case-insensitive header lookup
- `{{request.body.email}}` — dotted path into the parsed JSON body, including arrays (`{{request.body.items.0.id}}`)

If a placeholder resolves to a number or boolean we strip the surrounding quotes, so `"score": "{{$randomInt}}"` renders as `"score": 42` (a real number) not `"42"` (a string). JSON stays valid.

Unknown tokens, missing request fields, and non-JSON request bodies all degrade gracefully — the placeholder is left in the output untouched, so a typo shows up as a literal `{{$mystery}}` in the response and you can fix it without re-running anything.

The override editor in the dashboard has an **Insert template** button next to the Response body label. Click it and you get every available token grouped by category with a one-line description — pick one, it's appended to your body.

## Step 6: Strict request validation

Mocks are usually permissive — anything goes in, you get a sensible response back. That's great for prototyping and bad for catching contract bugs. Outworx Docs lets you flip a switch and turn the mock strict.

Toggle **Strict request validation** on the Mock Server **Overview** tab and every incoming request gets validated against the matched operation's spec — required path / query / header parameters, JSON request body schema. Anything off-spec gets a `400` with field-level error details:

```json
{
  "error": "Request failed strict validation against the spec.",
  "matchedPath": "/users",
  "operationId": "createUser",
  "errors": [
    { "field": "body.email", "code": "required", "message": "Missing required field 'email'." },
    { "field": "body.age", "code": "type", "message": "Expected integer, got string." },
    { "field": "query.limit", "code": "maximum", "message": "Value must be ≤ 100." }
  ],
  "hint": "..."
}
```

What's checked:

- **Type** — `string` / `integer` / `number` / `boolean` / `object` / `array` / `null`. OpenAPI 3.1's type arrays (`["string", "null"]`) and 3.0's `nullable: true` both work.
- **Required fields** — on the operation parameters and inside object schemas.
- **Enum / const** — value must match.
- **String constraints** — `minLength`, `maxLength`, `pattern`, `format` (uuid, email, uri, date, date-time, ipv4, ipv6).
- **Number constraints** — `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf`.
- **Array constraints** — `minItems`, `maxItems`, `uniqueItems`, plus per-item validation through `items`.
- **Object constraints** — `properties`, `additionalProperties: false` (rejects extras), `additionalProperties: <schema>` (validates extras).
- **Combinators** — `allOf` (all must pass), `oneOf` (exactly one), `anyOf` (at least one). `$ref` resolves recursively with cycle protection.

Path / query / header params are coerced from strings to the spec's declared type before validation, so `?limit=50` against a spec that says `type: integer` validates as `50` (integer), not as `"50"` (string). Mirrors how Express, FastAPI, and similar frameworks read params.

Stateful overrides skip validation. An override is the owner saying "I know what I'm doing for this request shape" — bypassing validation lets you demo error states (`400` with a custom shape, `422` with field errors) without the validator overriding your override.

Failed requests come back with `X-Mock-Synth: validation-error` and land in the activity feed so spec-mismatch traffic is visible in your usage stats.

## Step 7: Auth enforcement

The default mock is open — anyone can hit any endpoint without auth, even endpoints your spec marks as secured. That's fine for prototyping, terrible for catching the most common frontend bug class: the SDK silently dropping the auth header.

Toggle **Auth enforcement** on the Mock Server **Overview** tab and the route reads your spec's security blocks (`components.securitySchemes` on OpenAPI 3, `securityDefinitions` on Swagger 2) and rejects requests missing the required auth:

```
401 Unauthorized
WWW-Authenticate: Bearer realm="mock"

{
  "error": "Mock authentication required.",
  "matchedPath": "/users/{id}",
  "operationId": "getUser",
  "schemes": [
    { "name": "bearerAuth", "type": "http-bearer", "hint": "Send header Authorization: Bearer <token>" },
    { "name": "apiKeyAuth", "type": "apikey", "hint": "Send header X-API-Key: <api-key>" }
  ]
}
```

What's enforced:

- **API key** — in `header`, `query`, or `cookie`. Header lookup is case-insensitive; cookie lookup parses the `Cookie:` header.
- **HTTP Bearer** — `Authorization: Bearer <non-empty token>`.
- **HTTP Basic** — `Authorization: Basic <non-empty credentials>`.
- **OAuth2 / OpenID Connect** — same as Bearer, conventionally.
- **Other HTTP schemes** (Digest, Negotiate, …) — accept any non-empty `Authorization` header. The mock isn't going to validate the crypto.

The check is **presence-only**. The mock doesn't validate that an API key matches a real value — it has no notion of "real" credentials. But rejecting zero-byte tokens up front catches the bug everyone has shipped at least once: the SDK is "authenticated" but not actually attaching the header.

Per-operation `security` overrides the spec-level default. Empty `security: []` on an operation explicitly opts that operation out — useful for `/health`, `/auth/login`, etc.

Stateful overrides skip auth enforcement. An override is the owner's deliberate "return this exactly" path; second-guessing it would defeat the point.

Failed requests get `X-Mock-Synth: auth-required` and land in the activity feed so you can see exactly which endpoints integrators are hitting without auth.

## Step 8: Network simulation

Real APIs are slow sometimes and broken sometimes. Default mocks are neither, which means frontend code that handles "network is being weird right now" is the most under-tested code in the codebase. Network simulation fixes that.

The Mock Server **Overview** tab has a **Network simulation** card with four knobs:

- **Min latency (ms)** and **Max latency (ms)** — every request sleeps a uniform-random amount in this band before responding. `0–0` is off; `200–800` simulates a flaky cellular connection; `100–200` simulates "looks fast but is far away".
- **Chaos rate (%)** — fraction of requests forced to fail. `0` is off, `5` is "occasional flake", `25` is "your tests should handle this".
- **Error status** — what status to emit on chaos. Defaults to `503`. Any 4xx or 5xx works.

```
Latency 200–800ms · Chaos 5% · Error 503
```

Stateful overrides and strict-validation 400s **bypass** the simulator. An override is the owner's deliberate "return this exactly" — randomly breaking it would defeat the point. Same for validation errors: they're precise signals the frontend dev needs to see.

Diagnostic headers tell you exactly what happened:

- `X-Mock-Chaos-Latency-Ms: 437` — how many milliseconds of injected delay this request waited
- `X-Mock-Synth: chaos-error` — appears on responses where chaos rolled an error instead of returning the spec body

Chaos failures land in the activity feed with `synth: chaos-error` so usage stats keep simulation noise separate from real spec activity.

## Step 9: Import / export override bundles

Once you've spent time tuning a set of overrides on staging, you don't want to re-click them all into prod. Hit **Export** on the Overrides sub-tab and you get a single JSON file with every rule on the project — match config, response config, templating tokens, GraphQL operation matchers, the whole shape. Project-local IDs and timestamps are stripped so the bundle imports cleanly into any other project. The filename looks like `mock-overrides-a91f0c2d-2026-05-02.json` — a stable project prefix plus the export date.

**Import** asks merge-or-replace:

- **Merge** — appends the imported rules alongside whatever's already there. Great for layering staging-only debug rules on top of a production set without losing the production rules.
- **Replace** — wipes every existing override on the project, then imports. Great for "make staging match prod exactly".

Every imported rule is normalised through the same validation as a manually-created override, so a hand-edited bundle that tries to smuggle reserved headers or oversized bodies in gets rejected per-row. Invalid rules are reported in the import toast; the rest import successfully. If `merge` would push you past the 50-override cap, the import refuses up-front instead of partially applying.

The bundle format is versioned (`{ version: 1, exportedAt, overrides: [...] }`) so future schema changes can add a v2 codec without breaking existing exports — the importer dispatches on the version field.

## Step 10: GraphQL overrides

GraphQL doesn't have paths, so the override matcher takes a `match_graphql_operation` field instead. Set it to the operation name (`query MyQuery`, `mutation CreatePost`) and any request whose `operationName` matches gets the override response.

Combine that with `match_body` to match on variables: an override with `match_graphql_operation: "GetUser"` and `match_body: { "variables": { "id": "42" } }` only fires for that specific user lookup.

If no override matches, the GraphQL executor runs against the SDL — fields resolve to type-appropriate defaults (string, int, bool, enum first value, list of one) and your selection set is honoured. Custom scalars come back as strings unless you've put an `example` directive on them in the SDL.

## Step 11: Multi-version projects

If every version of your project uses the same kind of spec (all OpenAPI, all Swagger, all GraphQL) the base URL `https://docs.outworx.io/mock/<slug>` resolves to the **default version** — there's only one route to remember.

If you mix REST and GraphQL versions, the base URL splits per-version because the routing differs:

- `https://docs.outworx.io/mock/<slug>/v2/users/42` — REST version `v2`
- `https://docs.outworx.io/mock/<slug>/v1/graphql` — GraphQL version `v1`

The Overview sub-tab shows exactly which URLs you have. Hit the wrong one and we return a `400` with a `hint` and an `alternativeVersions` list pointing at the right format-aware URL.

## Step 12: Disable specific operations

Sometimes you want most of your API mocked but a handful of dangerous endpoints (anything that would hit Stripe, send mail, or charge a card) to come back `501` instead. The **Endpoints** sub-tab lists every operation with a per-version toggle — flip the switch and that operation returns `501 Not Implemented` with `X-Mock-Synth: disabled`.

Disabled state is per-version — `POST /payments/charge` can be mocked in `v1` and disabled in `v2`.

## Step 13: Watch the activity feed

Every mock request is logged: method, path, status, latency, override id (if any), `X-Mock-Synth` value, and the requesting IP's country. The Activity sub-tab shows the last 200 in real-time. The Overview sub-tab shows a 7-day usage summary so you can spot when traffic spikes — useful when an integration partner starts hammering your mock instead of the real API.

## Step 14: Plan limits

Limits are enforced against the project **owner's** plan, not the requesting collaborator's — a Free user collaborating on a Business project gets the Business caps; a Business user collaborating on a Free project is gated to Free.

| | **Free** | **Pro ($9/mo)** | **Business ($19/mo)** |
| --- | --- | --- | --- |
| Mock requests / month | 10,000 | 100,000 | Unlimited |
| Stateful overrides per project | 5 | 25 | 50 |
| Activity log retention | 24 hours | 14 days | 30 days |
| Auth enforcement | ✅ | ✅ | ✅ |
| Strict request validation | ✅ | ✅ | ✅ |
| Dynamic templating in overrides | ✅ | ✅ | ✅ |
| Network simulation (chaos) | — | ✅ | ✅ |
| Override import / export bundles | — | ✅ | ✅ |

Hitting the monthly request cap returns `429 Too Many Requests` with a `Retry-After` header counting down to the start of the next UTC month. The override count is enforced on create, duplicate, and import — going over returns a clear "limit reached" error with the cap and the plan name. Pro+-only features (network simulation, import/export) reject from server actions on Free with an upgrade message; the dashboard UI hides or locks the controls.

Free's correctness features (auth enforcement, strict validation, templating) are intentionally always-on — without them the mock isn't realistic enough to catch frontend bugs, which is the whole point. Plan tiering kicks in for *workflow* features (network simulation for stress-testing, import/export for staging↔prod parity) and *scale* (request count, override count, log retention).

## Try It panel — running mocks from the docs page

The Try It panel at the top of every endpoint reference page now has a **Mock** toggle. Flip it on and the request goes to your mock URL with all your `Prefer` headers attached. The response panel shows the `X-Mock-Synth` value as a coloured badge so readers can see at a glance whether they hit a real example, a synthesised schema, or a custom override.

GraphQL operations get the same treatment via a query/variables/operation-name editor — same toggle, same badge. It's the fastest way to demo "here's what this endpoint returns" without leaving the docs page.

## Diagnostic headers reference

| Header                  | Meaning                                                    |
| ----------------------- | ---------------------------------------------------------- |
| `X-Mock-Synth`          | `override`, `example:<name>`, `example:random`, `example:sequential`, `schema`, `empty`, `disabled`, `fallback` |
| `X-Mock-Override-Id`    | UUID of the override that fired (only when `synth=override`) |
| `X-Mock-Version`        | Which version of the spec served the response             |
| `X-Mock-Operation-Id`   | The operation id from the spec — handy for log correlation |
| `X-Mock-Latency-Ms`     | Server-side latency including any `latency_ms` from an override |

CORS is wide open (`Access-Control-Allow-Origin: *`, no credentials) — the mock URL is meant to be hit from any browser, frontend dev server, or Postman tab. The threat model is the same as the public docs: nothing private goes through it, no auth, no shared state across projects.

## What this replaces

If you were running [Prism](https://github.com/stoplightio/prism) locally, paying [Apidog](https://apidog.com/) for hosted mocks, or maintaining a `mocks/` directory of hand-written Express handlers — this is the integrated version. Spec uploads become live mock URLs automatically, overrides give you the dynamic-state escape hatch when examples aren't enough, and the activity feed plus Try It integration mean the docs and the mock are the same surface.

Open any project's **Mock** tab to grab your URL. The first request takes about 30ms and you're already mocking.


---

## Test Webhooks: Capture, Sign, and Replay

URL: https://docs.outworx.io/guides/test-webhooks-with-outworx
Category: Integration
Published: 2026-04-28
Reading time: 7 min

> A unique capture URL catches webhooks in real-time. Send-test, replay, and an HMAC verifier for Stripe, GitHub, Shopify, Slack + 6 more — all browser-side.
Webhooks are the hardest part of an API to debug. They're asynchronous, they fire from someone else's server, and the only signal you get when something goes wrong is a customer complaint days later. The usual loop — sender → your handler → silent failure — leaves you reverse-engineering a black box.

Outworx Docs ships a webhooks playground that turns that loop into something you can see, replay, and verify. A unique capture URL catches incoming requests in real-time. Send-test fires signed payloads at any handler. Replay re-runs a captured request against a different URL. And the HMAC verifier matches signatures from ten different webhook providers — Stripe, GitHub, Shopify, Square, Linear, HubSpot, Zoom, Zendesk, Slack — entirely in your browser.

This guide walks the whole flow: capturing a real webhook, replaying it against your local handler, sending test events, verifying signatures, locking inboxes down for production traffic, and the FAQ that always comes up about tunnels, retention, and rate limits.

## What you can debug with this

Before the steps, the use cases. People reach for a webhook playground when:

- **Stripe / Polar / Lemon Squeezy aren't firing the event you expected** and you need to confirm whether it's the sender or the handler
- **GitHub Actions sends a workflow webhook** and you want to see the full payload schema before writing your matcher
- **Shopify orders are dropping a field intermittently** and you need to capture the raw JSON to file a bug
- **You're building a webhook receiver from scratch** and want to confirm your HMAC verifier works against real traffic before going live
- **A flaky integration is sending duplicates** and you want to see the timing + bodies side by side
- **Your CI is testing webhook handlers** and you want a deterministic replay endpoint instead of asking Stripe to fire test events on a schedule

If any of those rings a bell, this is the guide.

## Prerequisites

- An Outworx Docs account (free signup includes 5 webhook inboxes)
- Something that emits webhooks — Stripe, GitHub, your own service in test mode

You don't need a project, a spec, or any prior setup. Webhooks is a standalone workspace at `/webhooks` in the dashboard.

## Step 1 — Create an inbox

Go to **/webhooks** in the dashboard and click **+ New inbox**. Give it a label like "Stripe staging" — only you see it. Linking to a project is optional and we'll skip it for now.

You'll land on a page with a prominent capture URL:

```
https://docs.outworx.io/api/inbox/2NX_7mCiC46d.......
```

Click **Copy**. This is the only auth on the inbox by default — anyone with the URL can post to it, so treat it like a webhook signing secret. (We'll lock it down in Step 6.)

## Step 2 — Point a sender at it

Paste the URL into Stripe's webhook configuration (Dashboard → Developers → Webhooks → Add endpoint), or GitHub's repo webhooks settings, or whatever sender you're debugging. Send a test event from the sender's UI.

The capture appears in the dashboard's live stream within ~200ms — no refresh needed. We use Postgres logical replication via Supabase Realtime, so every authenticated browser tab subscribed to that inbox sees inserts the moment they happen.

Click any captured row to open the inspector. You get the full method + path, the source IP and ASN, every header (cookies stripped for safety), and the body pretty-printed if it's JSON / XML / form-encoded. Binary uploads (multipart) get a hex-dump preview with a download button.

## Step 3 — Verify the signature

Most webhook senders sign their payloads. The Outworx HMAC verifier handles ten common schemes plus raw HMAC variants:

- **Stripe** (v1, hex)
- **GitHub** (sha256 + legacy sha1, hex)
- **Slack** (v0, hex, with timestamp basestring)
- **Shopify** (sha256, base64)
- **Square** (sha256 over URL + body, base64)
- **Linear** (sha256, hex)
- **HubSpot** (v3, sha256 over method + URI + body + timestamp, base64)
- **Zoom** (v0, sha256, hex, with timestamp basestring)
- **Zendesk** (sha256 over timestamp + body, base64)
- **Outworx** (our own Send-test signatures)
- **Raw HMAC-SHA1 / 256 / 512** in hex or base64

The verifier auto-detects the right scheme from the captured headers. Open a capture, expand "Verify signature (HMAC)", paste your signing secret, click Verify. Math runs in WebCrypto in your browser — your secret never crosses our network.

If the math passes, you also get a staleness check: schemes with timestamps (Stripe, Slack, HubSpot, Zoom, Zendesk) flag signatures older than 5 minutes, since most senders reject those as a replay defence. Useful when you're debugging "why does Stripe say my signature is valid but my handler rejects it" — odds are your timestamp tolerance is too tight.

## Step 4 — Replay against your handler

Found a malformed payload that broke production? Reproducing it normally means asking the sender to fire another one — Stripe doesn't make that easy. Outworx solves this with one click.

Hover the captured row, click **Replay**. The Send-test modal opens with the original body and headers pre-filled. Paste your handler URL (or a tunnel URL like `https://abc.ngrok.io/webhooks` for a local handler), optionally add your signing secret, and fire. We sign with HMAC-SHA256 in Stripe-v1 format under `X-Outworx-Signature: t=<unix>,v1=<hex>` so your handler can verify with the standard library it already uses.

Replays drop the original sender's signature header — the math wouldn't verify against your secret anyway, and we add `X-Outworx-Replay: true` so a paranoid handler can refuse replays if it wants.

The response from your handler is captured back into the same inspector view: status code, headers, body, timing. So a replay loop reads top-to-bottom: original capture → modified replay → your handler's response. That's usually enough to nail down whether the handler is the bug.

## Step 5 — Send test events without waiting for the sender

The Send-test modal isn't just for replays. From `/webhooks`, click **Send test** to fire any payload at any URL:

- **Method**: POST, GET, PUT, PATCH, or DELETE
- **Custom headers**: Authorization, X-Webhook-Source, etc.
- **Signing secret**: optional HMAC-SHA256 in your choice of scheme
- **Body**: paste raw JSON, or pre-fill from a spec event

If your project's OpenAPI spec includes the OpenAPI 3.1 `webhooks:` block, those events show up under **/webhooks?section=events** with per-event Send buttons that pre-fill payloads from the schema. One click and you've fired a sample `invoice.paid` at your handler — useful when you're building a new integration and don't want to wait on Stripe to actually issue an invoice.

## Step 6 — Lock the inbox down for production traffic

The default inbox is open — anyone with the URL can post. That's the point during exploration. When you're ready to point real traffic at it, open **Security** in the inbox toolbar and turn on any combination of three layers:

- **HMAC signature verification** — pick a scheme (Outworx, Stripe, GitHub sha256/sha1, Slack, Shopify, Linear, Zendesk, or **Custom HMAC** where you set the header name, algorithm, encoding, and prefix), paste the shared secret, and the receiver will reject anything missing or mismatched with `401`. Schemes that sign a timestamp also get replay protection — configurable tolerance, default 5 minutes.
- **HTTP Basic auth** — username + password gate; missing or wrong credentials get `401 + WWW-Authenticate` so well-behaved senders prompt for the right ones.
- **Source IP allowlist** — paste IPv4 / IPv6 CIDR ranges, one per line. Off-network requests get `403`. Useful for providers that publish their egress IPs (Stripe, GitHub).

Each layer is independent. Replays auto-sign with the inbox's stored secret using the configured scheme, so a locked-down inbox accepts its own replays without you having to re-paste the secret. Secrets and passwords never round-trip to the browser — the dialog shows a "leave blank to keep" affordance so saving other settings doesn't expose the stored value.

The combination "HMAC + IP allowlist" is what most production teams ship. Stripe publishes their egress IPs; lock to those, verify the signature, done.

## Localhost and tunnels

Outworx runs in the cloud and can't reach `localhost` on your machine. The Send-test modal shows a tunnel hint when it detects a localhost URL:

```bash
npx ngrok http 3000
# or
cloudflared tunnel --url http://localhost:3000
# or
npx localtunnel --port 3000
```

Paste the resulting public URL into Send-test. The captured response shows up in the inspector even when your local handler is the destination, so you can debug `console.log` output by reading the response body in the dashboard.

When you're running the Outworx app *itself* on localhost in dev mode, we auto-allow loopback addresses — no tunnel needed. Production is HTTPS-only with the SSRF guard fully active so a captured webhook can't be replayed against `169.254.169.254` (instance metadata) or any internal RFC1918 range.

## Plan limits

Free includes:

- **5 inboxes**
- **500 captures** received in any rolling 7-day window
- **100 sends/day**
- **7-day retention**

Pro: 25 inboxes, 10,000 captures / 30 days, 5,000 sends/day, 30-day retention.

Business: unlimited everything, 90-day retention.

The capture cap is enforced via an append-only ledger that survives "Clear all" — so a malicious user can't reset their quota by clearing inboxes. Senders that hit the cap receive HTTP `429` with `Retry-After` until ledger entries age out.

## Frequently asked questions

**Does the inbox URL change if I rotate it?** Yes — that's the point. Rotation is on the inbox page; it generates a new token, the old URL stops accepting captures, and you'll need to update the sender to the new URL. Senders will get `404` on the old URL, which is intentional (they don't quietly fall back to a stale endpoint).

**Can I have multiple inboxes pointing at the same handler?** Yes. Common pattern: one inbox per environment (staging / prod / per-customer). Each inbox has its own capture URL, its own retention window, its own security config, and its own replay history.

**What happens during the 7-day / 30-day / 90-day retention window?** Captured requests are stored with their full headers + body for the retention period. After expiry they're hard-deleted. The capture count quota uses an append-only ledger that tracks count separately from row presence — so deleted captures still count toward your monthly cap. This stops the "clear inbox to reset cap" exploit.

**Can I replay an old capture after retention expires?** No — once a capture is hard-deleted, the body is gone and replay isn't possible. Pro / Business retention windows exist precisely so production teams have enough time to investigate intermittent issues without losing the body.

**Is my webhook signing secret stored anywhere?** When you use the verifier in the dashboard, no — the secret is computed in WebCrypto in your browser and never leaves it. When you turn on inbox-level Security, the secret is stored encrypted at rest on our servers (server-side HMAC verification needs it). The "leave blank to keep" affordance means you can update other security settings without re-pasting the secret.

**How do I make my CI tests deterministic?** Pre-record a capture during exploration, then drive replays from the dashboard — open the capture and click **Replay**, or save it as a Sender template and trigger it from there. The body is byte-identical every time, the signature is reproducible, and the test runs in milliseconds instead of waiting on a real Stripe event. (The inbox token is capture-only by design — there's no anonymous-token replay endpoint, so a leaked token can't be used to re-fire arbitrary payloads at your handler.)

**Can I forward all captures to multiple handlers?** Not natively. The pattern is: one Outworx inbox → your "fan-out" handler → multiple downstream services. Outworx is the inspection point, not the routing layer. (If a fan-out feature is something you actually need, drop us a line — we'll prioritize it if there's demand.)

**What about webhook order? Will captures arrive in send order?** In practice yes (sub-millisecond), but webhooks are inherently parallel and HTTP doesn't guarantee delivery order. If your handler relies on order, fix that bug — webhook senders explicitly disclaim order. Use a sequence ID in the payload itself if you need it.

**Do I need to whitelist Outworx IPs in my firewall?** Only for the *replay direction* — your handler receives requests from Outworx's egress. We publish the current egress IP range in the dashboard's Security panel. The capture direction is inbound to us; senders don't see Outworx IPs.

**What about WebSocket or SSE webhooks?** The capture URL is HTTP only — it accepts any method, any body, but doesn't upgrade connections. WebSocket-style "webhooks" (the Slack RTM API, Discord gateway) need a different tool. Most "webhooks" in modern usage are plain HTTP POSTs, which Outworx handles.

## What this replaces

If you were using webhook.site, ngrok inspect, RequestBin, or a tab full of `console.log` statements in your handler — Outworx Webhooks is the integrated version. Capture + replay + signature verification all in one workspace, with plan limits sized for real production debugging instead of a forced upgrade after the third capture.

The capture URL is yours forever (or until you rotate it). The signing secret is yours and never crosses our network. Everything else — the schemas, the docs, the AI chat, the MCP server — is right next door if you need it.

Open `/webhooks` in your dashboard and create your first inbox. The whole flow is under thirty seconds.


---

## Migrate from ReadMe in 15 Minutes

URL: https://docs.outworx.io/guides/migrate-from-readme
Category: Migration
Published: 2026-04-25
Reading time: 8 min

> Move off ReadMe ($99/mo) onto Outworx Docs ($9–19/mo) without losing versions, custom domains, or SEO. Step-by-step with redirects and 30-day rollback.
If you're on **ReadMe** and the $99/mo Startup plan is starting to feel steep for what is, fundamentally, a renderer for your OpenAPI file — this guide gets you off it and onto Outworx Docs in about fifteen minutes. No data loss, no SEO regression, no per-seat invoices.

We'll cover: exporting your spec, preserving versions, migrating the custom domain, redirecting old URLs to keep your search rankings, and the things ReadMe doesn't ship that Outworx Docs does.

## Step 1 — Export your spec (2 minutes)

ReadMe stores the source OpenAPI definition for every API version you've added.

1. Open the ReadMe dashboard
2. **API Reference** tab
3. Click the three-dot menu on your active version → **Export OpenAPI**

You get a `.json` file. Save it. Repeat for every version you want to keep (`v1`, `v2-beta`, etc.).

If you've been editing your spec inside ReadMe's web editor instead of in git, that exported JSON *is* your source of truth — commit it to your repo before going further. You don't want to lose hand-edits made over the past year because your only copy lived in a vendor dashboard.

## Step 2 — Upload to Outworx Docs (1 minute)

1. Sign up at [docs.outworx.io](https://docs.outworx.io) — free tier, no credit card.
2. Click **New Project**, name it after your API, pick a slug. This becomes your default URL: `yourslug.docs.outworx.io`.
3. **API Spec** tab → **Upload** → drag in the JSON.

Your docs go live immediately. Every endpoint, every parameter, every example. The Try It playground works against your real API the moment it's uploaded.

## Step 3 — Recreate your versions (3 minutes)

ReadMe versions become Outworx versions one-to-one. Versions appear in a switcher on your public docs site, so existing customers reading `/v1/users` don't suddenly hit a 404 because you migrated.

For each exported file:

1. **API Spec** tab → **New version**
2. Upload the file
3. Label it exactly as it was on ReadMe (`v1`, `v2-beta`, …)
4. Mark the version that should be the default

URL shape: `yourslug.docs.outworx.io/v1`, `yourslug.docs.outworx.io/v2-beta`. This matches ReadMe's path conventions, which matters for Step 5.

## Step 4 — Migrate the custom domain (5 minutes)

If your docs live at `docs.yourcompany.com`, keep them there.

**On Outworx Docs** (Business plan, $19/mo — vs ReadMe's $99/mo Startup, $399/mo Business):

1. **Settings → Custom domain** → enter `docs.yourcompany.com`
2. Copy the CNAME target

**On your DNS provider:**

1. Edit (don't delete) the existing CNAME pointing at `readmedocs.com`
2. Change it to point at Outworx's target
3. Cloudflare specifically: set proxy to **DNS only** (grey cloud). Outworx provisions its own Let's Encrypt cert; Cloudflare's orange-cloud proxy double-encrypts and breaks things.

Wait 1–5 minutes for propagation. Outworx polls and auto-issues SSL the moment the CNAME resolves. Green "Verified" badge appears in the dashboard.

Your custom domain now serves from Outworx. Bill drops to $19/mo.

## Step 5 — Keep your SEO with proper redirects (3 minutes)

This is the step every migration guide handwaves and the one that costs you traffic if you skip it.

ReadMe paths look like `/reference/listPosts`. Outworx paths look like `/endpoints/listPosts`. Google has indexed the old shape; if endpoint pages 404 after the switch, your hard-earned rankings disappear.

Two safe paths:

**Option A — keep the old ReadMe subdomain alive for 30 days.** Run both in parallel. Add a Cloudflare Page Rule (or equivalent) redirecting old paths to new:

```
docs-old.yourcompany.com/reference/* → docs.yourcompany.com/endpoints/$1
```

After Google reindexes (~30 days), cancel ReadMe.

**Option B — accept a temporary dip.** Skip redirects. Rankings recover in 4–8 weeks once Google sees Outworx serving canonical content. Cheaper, slightly more painful.

Most teams use Option A. The 30-day overlap is the cost of a clean migration.

## What you gain by leaving ReadMe

- **Per-project MCP server.** ReadMe doesn't ship one. Outworx Docs gives every Pro and Business project a Model Context Protocol server — Claude Desktop, Cursor, and Cline can connect directly to your docs and operate your API.
- **AI chat included.** ReadMe charges extra for AI features. Outworx ships AI chat trained on your spec, on every public docs page, included in Pro and Business.
- **Team seats included.** ReadMe's higher tiers gate seats. Outworx includes 3 (Pro) or 10 (Business) collaborator seats with no per-seat billing.
- **Localhost dev loop.** `npx @outworx/proxy` lets your Try It playground talk to localhost APIs through a CORS-bypass proxy. No equivalent on ReadMe.
- **Pricing honesty.** $9 Pro, $19 Business. No annual-only discount tier, no "Contact Sales" enterprise gating.

## After the migration

Wire up auto-sync so the docs stay in lockstep with your repo. Either:

- Paste your spec URL into the project settings — we fetch on hourly / daily / weekly cadence
- Or push from CI: see [Auto-sync API Docs from GitHub Actions on Every Push](/guides/auto-sync-github-actions)

Then connect your AI assistant via MCP: [Connect Your API Docs to Claude Desktop via MCP](/guides/connect-claude-desktop-mcp).

That's the full migration. Most teams finish in under fifteen minutes if they don't have an unusual custom domain setup.

[Start your migration →](https://docs.outworx.io)


---

## Migrate from Mintlify (Step-by-step)

URL: https://docs.outworx.io/guides/migrate-from-mintlify
Category: Migration
Published: 2026-04-25
Reading time: 8 min

> Switch off Mintlify ($150/mo team plan) onto Outworx Docs ($19/mo) without losing your custom domain, version history, or rankings. Includes MDX guide handling.
**Mintlify** is great for narrative documentation but the bill compounds fast: $150/mo for the team plan, separate add-ons for AI features, and per-editor seats once you outgrow the starter tier. If your product is API-first and you mostly need a renderer for OpenAPI plus an AI assistant, Outworx Docs covers the same ground for $9–$19/mo with no seat math.

This guide walks the migration end-to-end: getting your spec out, mapping Mintlify's MDX-driven structure onto Outworx, preserving SEO, and what to do with your guide pages.

## Step 1 — Locate your spec (2 minutes)

Mintlify usually keeps your OpenAPI definition as a file in your docs repo (`openapi.yaml` or `openapi.json`), referenced from `mint.json`.

```bash
# Most Mintlify repos have a spec file at the root
ls api/openapi.yaml openapi.yaml openapi.json 2>/dev/null
```

If you've been editing the spec in Mintlify's web editor instead of git, click **Download** in the dashboard to grab the current snapshot, then commit it to your repo. You want git as the source of truth before going further.

## Step 2 — Upload to Outworx Docs (1 minute)

1. Sign up at [docs.outworx.io](https://docs.outworx.io). Free tier, no card.
2. **New Project** → name it after your API → pick a slug. URL becomes `yourslug.docs.outworx.io`.
3. **API Spec** tab → **Upload** → drag in `openapi.yaml`.

Docs go live instantly. Endpoints, parameters, examples, the Try It playground — all working against your real API.

## Step 3 — Decide what to do with your MDX guides

This is the one Mintlify-specific decision. Mintlify mixes API reference (rendered from OpenAPI) with hand-written MDX guide pages (`introduction.mdx`, `quickstart.mdx`, etc.) in the same site.

Outworx Docs is API-reference-first. Two reasonable paths:

**Path A — keep Mintlify alive for guides only.** Move the API reference to Outworx (the expensive part), keep Mintlify on its cheapest tier ($24/mo) for your narrative docs. Set a `Guides` link in your top nav pointing to `guides.yourcompany.com` (Mintlify) and an `API Reference` link pointing to `api.yourcompany.com` (Outworx). Net cost: $24 + $19 = $43/mo, vs. $150/mo all-Mintlify.

**Path B — host guides on Outworx's `/guides` hub.** We support long-form MDX-style content at `/guides/<slug>`. Migrate each `.mdx` file as-is. Currently this requires a small content commit on our side (we ship guides via the registry); reach out at info@outworx.io and we'll set it up. Net cost: $19/mo, single domain, single login.

Most teams do Path A initially, then migrate to Path B once the API reference has been live for 30 days and they're sure they want everything on one platform.

## Step 4 — Preserve versions (3 minutes)

If your Mintlify site had multiple API versions:

1. **API Spec** tab → **New version**
2. Upload the spec for each old version
3. Label them exactly as they were (`v1`, `v2-beta`, …)
4. Mark the default

URLs become `yourslug.docs.outworx.io/v1`, `yourslug.docs.outworx.io/v2-beta`. The version switcher renders on every public docs page automatically.

## Step 5 — Migrate the custom domain (5 minutes)

If your docs live at `docs.yourcompany.com`:

**On Outworx Docs** (Business plan, $19/mo):

1. **Settings → Custom domain** → enter your domain
2. Copy the CNAME target

**On your DNS provider:**

1. Edit the existing CNAME (currently pointing at `mintlify.app` or similar)
2. Point it at Outworx's target
3. Cloudflare: set the record to **DNS only** (grey cloud). Outworx provisions its own SSL — orange-cloud proxy will conflict.

Wait 1–5 minutes. SSL provisions automatically. Done.

## Step 6 — SEO and redirects (3 minutes)

Mintlify path shape is typically `/api-reference/v1/listUsers`. Outworx is `/endpoints/listUsers` with the version on the subpath. Different shape → you need redirects to keep your search rankings.

**Recommended:** keep the old Mintlify subdomain alive for 30 days, set up a Cloudflare Page Rule:

```
docs-old.yourcompany.com/api-reference/* → docs.yourcompany.com/endpoints/$1
```

Cancel Mintlify after Google has reindexed (~30 days). You'll see new pages in Search Console within 1–2 weeks.

## What you actually gain

- **Per-project MCP server.** Mintlify doesn't ship one. Outworx Docs gives every Pro+ project a Model Context Protocol server — Claude, Cursor, Cline plug straight in.
- **AI chat included.** Mintlify's AI assistant is a separate add-on. Outworx bakes it into Pro and Business at no extra cost.
- **Localhost dev loop.** Run `npx @outworx/proxy`, hit Send Request from the docs UI, the proxy routes through to your `localhost:3000`. CORS just works. No equivalent on Mintlify.
- **No per-seat billing.** Pro includes 3 collaborator seats, Business includes 10. Mintlify's team plan starts at $150/mo before per-seat upcharges.
- **Plan inheritance.** Invite a teammate who's still on Free, they get your project's full feature set when working on it. No "upgrade them first" friction.

## After the migration

Set up auto-sync so docs stay current: paste your spec URL, we fetch hourly / daily / weekly. Or push from CI — see [Auto-sync API Docs from GitHub Actions on Every Push](/guides/auto-sync-github-actions).

Then wire MCP for Claude / Cursor / Cline: [Connect Your API Docs to Claude Desktop via MCP](/guides/connect-claude-desktop-mcp).

That's the migration. Fifteen minutes, maybe an hour if you're untangling guide pages alongside the API reference.

[Start your migration →](https://docs.outworx.io)


---

## Migrate from Stoplight (Step-by-step)

URL: https://docs.outworx.io/guides/migrate-from-stoplight
Category: Migration
Published: 2026-04-25
Reading time: 9 min

> Move off Stoplight's per-editor pricing and Studio workflow onto Outworx Docs. 20-minute migration with bundled multi-file specs and version preservation.
**Stoplight** is one of the more polished API design tools on the market — but the moment your team grows, the per-editor seat pricing and the Studio-tied workflow start to feel like a tax. If you mostly need a hosted API reference (not the full design + governance + linting suite), Outworx Docs is a cleaner fit at $9–$19/mo with no per-seat billing.

This guide moves your existing Stoplight docs onto Outworx in about twenty minutes.

## Step 1 — Export your spec from Stoplight (3 minutes)

Stoplight stores your API definition as OpenAPI under the hood, regardless of whether you authored it in Studio or in their web editor.

**Stoplight Platform (web):**
1. Open the project
2. Click the **API** node in the left sidebar
3. **Export** menu → **Download OpenAPI** → pick JSON or YAML

**Stoplight Studio (desktop app):**
Your spec is the file you've been editing the whole time. Look for `openapi.yaml` (or `openapi.json`) in your project folder. Studio uses git, so it's already source-controlled.

**Multi-file specs (`$ref` to other files):**
If your project uses Stoplight's split-file convention (one OpenAPI per resource, stitched via `$ref`), bundle them into a single file before uploading:

```bash
npx @redocly/cli bundle openapi.yaml -o bundled.yaml
```

Outworx Docs accepts a single file. The bundle command from `@redocly/cli` resolves all `$ref` pointers and emits a flat document.

## Step 2 — Upload to Outworx Docs (1 minute)

1. Sign up at [docs.outworx.io](https://docs.outworx.io). Free tier, no card.
2. **New Project** → name → slug. URL: `yourslug.docs.outworx.io`.
3. **API Spec** tab → **Upload** → drag in `bundled.yaml` (or your single-file spec).

Docs go live. Endpoints, parameters, examples, Try It — all working.

## Step 3 — Recreate versions (3 minutes)

Stoplight versions become Outworx versions one-to-one.

For each version:
1. **API Spec** tab → **New version**
2. Upload the bundled spec
3. Label as it was (`v1`, `2024-01-01`, etc.)
4. Mark the default

URL shape: `yourslug.docs.outworx.io/v1`. Version switcher renders on every public docs page.

## Step 4 — Migrate the custom domain (5 minutes)

If your docs live at `docs.yourcompany.com`:

**On Outworx Docs** (Business, $19/mo):
1. **Settings → Custom domain** → enter your domain
2. Copy the CNAME target

**On DNS:**
1. Edit the CNAME currently pointing at Stoplight's hosting
2. Point it at Outworx's target
3. Cloudflare: **DNS only** (grey cloud), not orange — Outworx handles SSL itself

Wait 1–5 minutes. SSL provisions automatically. Done.

## Step 5 — Mocking & governance — what to keep, what to drop

This is where you want to be honest about what you actually use.

**Stoplight features that don't have direct Outworx equivalents (yet):**
- API mocking (Prism)
- Spectral linting / style guides
- Visual API design in Studio

**If you use these heavily,** keep Stoplight alive on its cheapest tier for design, then publish the resulting OpenAPI spec to Outworx for hosted documentation. The handoff is automatic if you wire up auto-sync — Outworx fetches your published spec URL on a schedule.

**If you don't use them** (most teams who design APIs in their backend frameworks don't), drop Stoplight entirely. Use a free Spectral CLI run in CI for linting, use your existing dev environment for mocking.

## Step 6 — Redirects for SEO (3 minutes)

Stoplight's path shape is typically `/docs/<workspace>/<api-id>/operations/<operation-id>`. Outworx is `/endpoints/<operation-id>`. Different shape → set up redirects so Google doesn't drop your indexed pages.

Keep the Stoplight subdomain alive for 30 days. Add a redirect rule on your DNS or CDN:

```
docs-old.yourcompany.com/docs/*/operations/* → docs.yourcompany.com/endpoints/$2
```

After ~30 days, Search Console shows the new URLs indexed. Cancel Stoplight then.

## What you gain by leaving Stoplight

- **No per-editor pricing.** Stoplight charges per editor seat once you scale. Outworx Pro includes 3 seats, Business includes 10. Flat fee.
- **Per-project MCP server.** Stoplight doesn't ship one. Outworx Docs gives every Pro+ project a Model Context Protocol server — your AI assistants can list endpoints, generate types, ask docs, and execute live calls grounded in your spec.
- **AI chat for visitors.** Stoplight has no built-in AI chat for the rendered docs. Outworx ships streaming AI chat trained on your spec, with citation pills that link back to the referenced endpoint.
- **Localhost CORS proxy.** `npx @outworx/proxy` lets your Try It playground hit `http://localhost:3000` from a hosted docs domain without CORS errors. Stoplight's playground hits this every time.
- **Plan inheritance for collaborators.** Invite a Free user to your Business project, they use Business features on it. Stoplight's licensing model can't express this — you upgrade everybody or nobody.

## After the migration

Wire auto-sync from your spec URL: [Auto-sync API Docs from GitHub Actions on Every Push](/guides/auto-sync-github-actions).

Connect Claude Desktop / Cursor / Cline via MCP: [Connect Your API Docs to Claude Desktop via MCP](/guides/connect-claude-desktop-mcp).

If your localhost API hits CORS errors when you Try It from the hosted docs, the [@outworx/proxy](https://www.npmjs.com/package/@outworx/proxy) package solves it in one terminal command.

Total time: about twenty minutes for the average team. Longer if you're untangling a multi-file Stoplight project, shorter if your spec was already a single bundled file in your repo.

[Start your migration →](https://docs.outworx.io)


---

## Migrate from Redoc (Step-by-step)

URL: https://docs.outworx.io/guides/migrate-from-redoc
Category: Migration
Published: 2026-04-25
Reading time: 7 min

> Get the Try It playground, AI chat, MCP, and analytics Redoc OSS doesn't ship — without Redocly Premium. 10-minute migration onto Outworx Docs.
**Redoc** is one of the most popular open-source OpenAPI renderers — and that's exactly why teams hit a wall. The OSS version has no Try It playground, no AI chat, no analytics, no auto-sync. To get any of that you upgrade to **Redocly Premium**, which lands at enterprise pricing. If you've outgrown Redoc OSS but don't want to negotiate a Redocly contract, Outworx Docs is the obvious next step at $9–$19/mo.

This guide takes whatever you have today (Redoc OSS, Redocly CLI, or Redocly Reef-hosted) and lands it on Outworx Docs in about ten minutes.

## Step 1 — Locate your spec (1 minute)

You almost certainly already have it. Redoc renders directly from an OpenAPI file — no proprietary format, no vendor-locked storage.

```bash
# Common locations
ls openapi.yaml openapi.json api/openapi.yaml docs/openapi.yaml 2>/dev/null
```

If your Redoc deployment uses Redocly's multi-file `$ref` convention, bundle to a single file:

```bash
npx @redocly/cli bundle openapi.yaml -o bundled.yaml
```

This is the cleanest part of migrating from Redoc — your source is already exactly what Outworx wants.

## Step 2 — Upload to Outworx Docs (1 minute)

1. Sign up at [docs.outworx.io](https://docs.outworx.io). Free, no card.
2. **New Project** → name → slug. URL: `yourslug.docs.outworx.io`.
3. **API Spec** tab → **Upload** → drag in `bundled.yaml` (or your existing single file).

Docs go live. Every endpoint rendered, **with a working Try It playground** (the thing you couldn't get on Redoc OSS), code snippets in cURL / Fetch / Axios / Python, version switcher, and the option to enable AI chat.

## Step 3 — Compare what changed visually (2 minutes)

Open both side by side: your old Redoc site and the new Outworx site. Specifically check:

- **Endpoint pages** — Outworx renders schema definitions in collapsible cards rather than Redoc's three-column layout. Most users find it scans better; some Redoc fans miss the dense view. Either way, every field your Redoc had is here.
- **Code samples** — Redoc supports `x-codeSamples` extensions in your spec. Outworx renders these natively for cURL/Fetch/Axios/Python and falls back to AI-generated examples for any language not in your spec.
- **Auth flows** — OAuth2, API key, bearer auth all render correctly. The Try It playground respects them and lets visitors paste credentials to make real calls.

If something looks off, check the OpenAPI source. Outworx is strict about spec conformance; Redoc was occasionally lenient about malformed `$ref` chains. Run `npx @redocly/cli lint` against your spec to catch issues.

## Step 4 — Versions (2 minutes)

If your Redoc setup served multiple versions (typically as separate deploys: `docs-v1.yourcompany.com` and `docs-v2.yourcompany.com`), consolidate them into one Outworx project:

1. **API Spec** tab → **New version**
2. Upload each version's spec
3. Label as `v1`, `v2`, etc.
4. Mark the default

URLs become `yourslug.docs.outworx.io/v1`, `yourslug.docs.outworx.io/v2` — version switcher visible on every page.

## Step 5 — Custom domain (5 minutes)

If your Redoc was deployed at `docs.yourcompany.com`:

**On Outworx** (Business, $19/mo):
1. **Settings → Custom domain** → enter the domain
2. Copy the CNAME target

**On DNS:**
1. Update your existing CNAME (currently pointing at your Redoc host — Vercel, Netlify, S3, wherever)
2. Point it at Outworx's target
3. Cloudflare: **DNS only** (grey cloud)

SSL provisions in 1–5 minutes. Done.

## Step 6 — SEO redirects if your old paths differ

Redoc's URL shape varies depending on how you deployed it:

- **Self-hosted Redoc**: usually `/operation/listUsers` or `#operation/listUsers` (anchor-based)
- **Redocly Reef-hosted**: `/<api-name>/operations/listUsers`
- **Outworx**: `/endpoints/listUsers`

If your old setup used hash-based anchors (`#operation/listUsers`), Google indexes those as fragments of the same page, and migration usually doesn't need redirects — your indexed page (`/`) still resolves and Google reindexes the new structure naturally.

If you used path-based URLs, set up redirects:

```
docs-old.yourcompany.com/operation/* → docs.yourcompany.com/endpoints/$1
```

Keep the old deploy alive for 30 days during the transition.

## What you gain by leaving Redoc OSS

This is mostly a list of "things Redoc OSS doesn't have":

- **Try It playground** that works against your real API. Redoc OSS doesn't ship one. Redocly Premium has it.
- **AI chat** trained on your spec, on every public docs page (Pro and Business). No equivalent on either Redoc OSS or Redocly.
- **Per-project MCP server** — Claude, Cursor, Cline plug straight into your docs. No equivalent anywhere in the Redocly ecosystem.
- **Auto-sync from spec URL** on hourly / daily / weekly cadence. Redoc requires you to re-deploy on every spec change.
- **Hosted analytics** — paths, referrers, countries, browsers, devices, time series — included on Business. Redoc OSS has none; Redocly Premium has them as a paid add-on.
- **Auth-protected docs.** Password protection on private docs, included. Redoc OSS doesn't ship this; you'd build it yourself with a reverse proxy.
- **Team seats with no per-seat billing.** 3 on Pro, 10 on Business.

## What you lose by leaving Redoc

Honest: you give up full control over the rendered HTML/CSS. Outworx is opinionated about layout and theming — you can pick brand colors and a theme variant on Business, but you can't ship arbitrary CSS or custom React components into the renderer the way you can when you `npm install redoc`. If you've built deep custom UI on top of Redoc, that work doesn't port.

For 95% of teams that's a feature, not a bug — but worth knowing.

## After the migration

- Wire auto-sync: [Auto-sync API Docs from GitHub Actions on Every Push](/guides/auto-sync-github-actions)
- Add MCP for AI assistants: [Connect Your API Docs to Claude Desktop via MCP](/guides/connect-claude-desktop-mcp)
- Run [@outworx/proxy](https://www.npmjs.com/package/@outworx/proxy) on dev machines so the Try It playground works against `localhost`

Total time: about ten minutes if your spec is already a single bundled YAML, fifteen if you need to bundle a multi-file Redocly project first.

[Start your migration →](https://docs.outworx.io)


---

## Generate TypeScript Types from OpenAPI in Seconds

URL: https://docs.outworx.io/guides/openapi-to-typescript
Category: Integration
Published: 2026-04-24
Reading time: 6 min

> Turn any OpenAPI or Swagger spec into clean TypeScript types via Outworx Docs' MCP server — no CLI, no codegen configs. Generate live, cached, and current.
If you've ever integrated against a REST API from a TypeScript codebase, you know the drill. You read the OpenAPI spec, hand-write interfaces for the request body and response, miss a nullable field, ship a bug, and find it at 2am when production returns a shape you didn't expect. The next week the API adds a field, nobody remembers to update your types, and the whole cycle repeats.

There's a better way. Your OpenAPI spec already describes every request, response, and error shape. The job of turning that spec into TypeScript types should be automatic — and ideally it should stay accurate as the API drifts.

This guide covers three approaches end-to-end: the classic CLI codegen route (good for monorepos that want types checked into git), the modern MCP-powered approach (best ergonomics for AI-assisted workflows), and a hybrid that gets you the best of both. We'll show working code for each, the tradeoffs, the failure modes, and a short FAQ at the end for the questions that always come up.

## Approaches at a glance

| Approach | Setup time | Stays in sync? | Handles incomplete specs? | Where types live |
| --- | --- | --- | --- | --- |
| `openapi-typescript` CLI | 5 min | Manual re-run | No — `unknown` for missing schemas | Checked into git |
| `orval` codegen | 15 min | CI-driven | No | Checked into git, includes hooks |
| Outworx MCP `generate_types` | 30 sec | Live, on-demand | Yes — infers from real responses | Either: paste into git OR consume via MCP |
| Hybrid (MCP + checked-in cache) | 30 sec | Re-prompted on drift | Yes | Both |

If you have a single API and a small monorepo, the CLI route is simplest. If you're using Cursor / Claude Desktop / Cline daily, MCP wins on ergonomics. If you ship to production and want auditable types in git, hybrid is the answer.

## Approach 1 — `openapi-typescript` CLI

The most-installed option (`openapi-typescript` has ~3M weekly downloads). It reads your spec and writes a single `.d.ts` file of interfaces.

```bash
# Install once
npm install -D openapi-typescript

# Generate types from a spec URL
npx openapi-typescript https://api.example.com/openapi.json \
  --output src/types/api.d.ts

# Or from a local file
npx openapi-typescript ./openapi.yaml --output src/types/api.d.ts
```

The output looks like this:

```typescript
export interface paths {
  "/users": {
    get: operations["listUsers"];
    post: operations["createUser"];
  };
  "/users/{id}": {
    get: operations["getUser"];
  };
}

export interface operations {
  listUsers: {
    parameters: { query?: { page?: number; limit?: number } };
    responses: {
      200: { content: { "application/json": components["schemas"]["UserList"] } };
      401: { content: { "application/json": components["schemas"]["Error"] } };
    };
  };
  // ...
}
```

It's verbose by design — you address types via the `paths` and `operations` indices. The `openapi-fetch` companion package makes this ergonomic:

```typescript
import createClient from "openapi-fetch";
import type { paths } from "@/types/api";

const client = createClient<paths>({ baseUrl: "https://api.example.com" });

const { data, error } = await client.GET("/users", {
  params: { query: { page: 1, limit: 20 } },
});
// data is fully typed; error is the typed 4xx/5xx union.
```

**Wire it into CI** so it runs on every spec change:

```yaml
# .github/workflows/regenerate-types.yml
name: Regenerate API types
on:
  schedule:
    - cron: "0 6 * * *"
  workflow_dispatch:

jobs:
  regenerate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: "20" }
      - run: npx openapi-typescript $SPEC_URL -o src/types/api.d.ts
      - uses: peter-evans/create-pull-request@v6
        with:
          title: "chore: regenerate API types"
          branch: chore/regenerate-types
```

**Where this approach falls down:** if your spec is incomplete — and most are, because most teams generate the spec from server code that doesn't fully describe response shapes — you get `unknown` everywhere a schema is missing. You're back to hand-typing.

## Approach 2 — `orval` for hooks + types

`orval` builds on top of `openapi-typescript` and emits a fully-typed client per endpoint, with React Query / SWR / Vue Query / Angular hooks. It's the heavier, more-opinionated option.

```bash
npm install -D orval
```

Drop a config file:

```typescript
// orval.config.ts
import { defineConfig } from "orval";

export default defineConfig({
  api: {
    input: "https://api.example.com/openapi.json",
    output: {
      target: "./src/api/generated.ts",
      client: "react-query",
      mode: "split",
      mock: true,
    },
  },
});
```

```bash
npx orval
```

You get a per-endpoint hook plus its types in one bundle:

```typescript
import { useListUsers } from "@/api/generated";

function UserList() {
  const { data, isLoading } = useListUsers({ page: 1, limit: 20 });
  // data is typed as ListUsersResponse | undefined
}
```

The cost is heavier output, more opinion, and a slow regeneration step. For codebases that already use React Query, the ergonomic win is real. For everything else, the CLI is leaner.

## Approach 3 — MCP `generate_types` (the modern way)

Outworx Docs ships a per-project [Model Context Protocol](https://modelcontextprotocol.io) server. Your API already has docs hosted at `yourslug.docs.outworx.io`; the MCP endpoint at `docs.outworx.io/api/mcp/yourslug` exposes 12 tools that AI assistants like Claude Desktop, Cursor, Cline, and Continue can call — including `generate_types`.

From inside Cursor (or Claude Desktop, or wherever), you literally ask:

> "Generate TypeScript types for the `listPosts` endpoint."

The assistant calls `generate_types` with `scope="endpoint"`, gets back a self-contained TypeScript module, and drops it into your codebase. Under the hood, Outworx:

- Parses your hosted spec into a normalized internal model
- Renders every named schema as an `export interface`
- Emits per-endpoint `OpNameRequest`, `OpNameResponse`, `OpNameError` aliases
- Caches the result so the next caller gets it instantly

Here's what you get back for one endpoint:

```typescript
// Types for listPosts — GET /api/feed/posts
// Generated by Outworx MCP at 2026-05-03T08:14:22Z

export interface ListPostsQueryParams {
  /** Page number (1-indexed) */
  page?: number;
  /** Results per page (max 100) */
  limit?: number;
  /** Filter by author username */
  author?: string;
}

/** 200 — Page of posts */
export type ListPostsResponse = {
  items: Post[];
  total: number;
  page: number;
  has_more: boolean;
};

/** 401 — Unauthorized */
export type ListPostsError401 = {
  error: string;
  code: string;
};

export interface Post {
  id: string;
  author_id: string;
  content: string;
  created_at: string;
  /** community-inferred — see "Self-healing types" below */
  reactions?: Reaction[];
}
```

Notice the `community-inferred` comment on `reactions`. That's the killer move.

## Self-healing types

When an MCP client calls `execute_endpoint` with real credentials, Outworx captures the response body and merges it into an inferred schema stored per `(version, endpoint, status)`. Over multiple samples from multiple users, the stored schema converges on the real contract — including fields the OpenAPI spec never documented.

The next `generate_types` call uses the inferred schema as a fallback, so generated TypeScript reflects actual API behavior even when the spec is incomplete. And because every live call re-validates, drift is caught immediately and the cached types regenerate cleanly.

This is particularly powerful for:

- APIs specced after the fact (FastAPI, Django REST Framework, Express)
- Community-driven APIs where the spec trails the implementation
- Internal APIs where the spec is hand-maintained and always slightly out of date

**The types improve as people use them.** No CLI codegen tool can do this — they only see the spec, not the wire.

## Approach 4 — Hybrid (MCP + checked-in cache)

For production TypeScript monorepos you still want types checked into git so offline builds and deterministic CI work. The MCP flow dovetails with that pattern:

1. Use the MCP `generate_types` tool to draft types for the endpoints you actually use (not the whole spec)
2. Paste into `src/types/api.ts` (or a dedicated `@company/api-types` package)
3. When the AI hits your API via `execute_endpoint` later and detects drift, it surfaces a "your cached types are stale, regenerate?" prompt
4. Regenerate, commit, ship

You get the ergonomic benefit of on-demand generation plus the audit-friendly behavior of checked-in types. The package boundary makes the regeneration explicit — you'll see the diff in code review.

## Common errors and how to fix them

**`Cannot find module '@/types/api.d.ts'` after running codegen.** Check your `tsconfig.json` `paths` mapping. The CLI tools default to writing under `src/types/`, but if your alias `@/*` points to `./src/*` you may need to refresh the TypeScript server (`Cmd+Shift+P` → Restart TS server in VS Code / Cursor).

**Types are all `unknown` for response bodies.** Your spec has `application/json` declared but no schema — the API ships an unstructured response. Two fixes: (a) update the source code to declare a response model (FastAPI `response_model=`, NestJS `@ApiResponse({ type: ... })`, etc.), or (b) use Outworx MCP, which infers the schema from real traffic and patches the gap.

**`429 Too Many Requests` from the spec URL during CI.** The CLI is fetching your spec on every CI run. Cache it: download the spec into the repo as `openapi.lock.json`, run codegen against the local file, and only refresh the lockfile on a scheduled job.

**Generated types break after a backend deploy.** The spec changed and your client wasn't regenerated. Fix in the long run by running codegen on a daily cron and opening a PR. In the short run, regenerate locally and commit.

## Frequently asked questions

**Does this work for Swagger 2.0?** Yes. Both `openapi-typescript` and the Outworx MCP server support OpenAPI 3.x and Swagger 2.0. Swagger 2.0 produces slightly less precise types because it lacks `oneOf` / `anyOf`, but it works.

**Does this work for GraphQL?** GraphQL has its own ecosystem (`graphql-codegen`, `gql.tada`, Apollo, Relay). For GraphQL specifically, use `graphql-codegen` — it's the equivalent of `openapi-typescript` for GraphQL. Outworx hosts GraphQL docs and a GraphQL mock server, but type generation is downstream of the GraphQL ecosystem.

**Can I generate types for a private API?** Yes, with both approaches. For the CLI, pass an authenticated spec URL (`Authorization: Bearer ...` via `--header`). For Outworx MCP, the `execute_endpoint` tool prompts the user for their auth, then the inferred schema improves as they use real credentials.

**What happens if my API uses `oneOf` / `anyOf` / `allOf`?** All three CLI approaches support them, with caveats. `openapi-typescript` produces a discriminated union you can `switch` on; `orval` does too. Outworx MCP resolves them at generation time and emits a clean union type. Refs (`$ref`) are followed and inlined.

**How do I version my types so old clients keep working?** Tag the spec at each release (e.g., `v1.openapi.json`, `v2.openapi.json`) and generate per-version type packages. Outworx supports per-version mock URLs and per-version MCP scopes natively, so an MCP client targeting `v1` gets `v1` types.

**Do generated types include doc comments?** Yes, all three approaches preserve the OpenAPI `description` field as JSDoc. Outworx adds an extra `/** community-inferred */` annotation on fields it inferred from real traffic — useful in code review.

**Can I commit the generated file to git but ignore the diff in PRs?** Add `src/types/api.d.ts linguist-generated=true` to `.gitattributes`. GitHub will collapse the diff by default in PRs but still track the file.

**What's the tradeoff vs hand-writing types?** Hand-writing is faster for one-off scripts. Codegen wins the moment you need to call more than ~5 endpoints, or any time the API changes. The Outworx MCP flow is faster than hand-writing even for one-off scripts because the AI does the typing for you.

## Try it

If you already host your API docs on Outworx, open the **MCP** tab on your project, copy the Cursor or Claude Desktop snippet, paste it into your MCP config, and ask your AI assistant to generate types for any endpoint. The whole loop takes about 30 seconds — including the moment when the assistant first realizes it can call your live API.

If you don't host your docs with us yet, that's the next 30 seconds. Upload your OpenAPI spec, get a hosted URL, and the MCP endpoint comes free on Pro and Business plans. The mock server, AI chat, webhook playground, and all the other pieces of the API toolchain are right there next door if you need them.


---

## Connect Claude Desktop to Your API Docs via MCP

URL: https://docs.outworx.io/guides/connect-claude-desktop-mcp
Category: AI
Published: 2026-04-24
Reading time: 8 min

> Give Claude Desktop live access to your API docs. One config snippet — Claude lists endpoints, generates typed code, and runs real API calls.
Claude Desktop is most developers' daily AI driver. It's fast, the interface is clean, and its tool-use support — via the Model Context Protocol (MCP) — means you can wire it up to any system that speaks the protocol. Your API docs should be one of them.

When you connect Outworx Docs' per-project MCP server to Claude Desktop, Claude gains twelve new capabilities: listing and searching endpoints, fetching full schemas, generating TypeScript types, executing live API calls with your credentials, and running grounded Q&A over your spec. You stop pasting curl commands into chat. You stop explaining your API at the start of every conversation. Claude just *knows*.

This guide walks through the whole setup — five minutes, one config file.

## Prerequisites

- A project hosted on Outworx Docs (free signup, Pro or Business plan for MCP access)
- Claude Desktop installed on macOS, Windows, or Linux
- Your project's MCP token (grab it from your dashboard in a moment)

## Step 1: Get your MCP endpoint + token

Open your Outworx Docs dashboard, click into any project, and go to the **MCP** tab. You'll see two values:

- **Endpoint URL** — looks like `https://docs.outworx.io/api/mcp/your-slug`
- **Access token** — starts with `mcp_`, about 50 characters

Click the eye icon to reveal the token, then copy both values. If your project is on the Free plan you'll see an upgrade gate instead — MCP is a Pro / Business feature.

## Step 2: Open Claude Desktop's config

The config file lives at:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

If it doesn't exist yet, create it. If it does and you already have other MCP servers wired up, you'll add a new entry alongside them.

## Step 3: Paste the config

Replace `<YOUR_SLUG>` and `<YOUR_TOKEN>` with your values:

```json
{
  "mcpServers": {
    "outworx-my-api": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://docs.outworx.io/api/mcp/<YOUR_SLUG>",
        "--header",
        "Authorization: Bearer <YOUR_TOKEN>"
      ]
    }
  }
}
```

Claude Desktop uses a local stdio bridge (`mcp-remote`) to talk HTTP to remote MCP servers. The `-y` flag lets npx auto-install the bridge on first run. If you've already got it installed globally you can replace `npx -y mcp-remote` with `mcp-remote`.

The MCP tab in your dashboard has this snippet pre-filled with your actual token — paste directly from there to skip the manual edit.

## Step 4: Restart Claude Desktop

Fully quit the app (⌘Q on macOS — not just close the window) and reopen. Claude Desktop only reads the MCP config on startup.

When it reloads, you should see a small plug icon near the input box. Click it — the dropdown lists "outworx-my-api" with a green dot. That's your server, connected.

## Step 5: Use it

Start a new chat and try something like:

> Using the outworx-my-api tools, list every endpoint tagged "posts" and generate TypeScript types for the first three.

Claude will:

1. Call `list_endpoints` with `tag="posts"` to get the endpoint list
2. Call `generate_types` with `scope="endpoint"` for each one
3. Produce a single self-contained TypeScript module

No copy-paste from the docs site. No re-explaining what the API does. The schemas, descriptions, and examples are all just *there*.

## What else Claude can do with this connection

Twelve tools are exposed through the MCP server. The highlights:

- **`ask_docs`** — natural-language Q&A grounded only in your spec. Claude uses this before making up answers about your API.
- **`execute_endpoint`** — hit your API live with caller-provided auth. Claude samples the response, and Outworx infers the schema automatically so future type generation reflects reality even when your OpenAPI is incomplete.
- **`search_endpoints`** — semantic search across every endpoint and schema. Useful when Claude doesn't know which endpoint to pick.
- **`recheck_types`** — validate that an endpoint's response still matches the stored inferred schema. Great for pre-ship drift checks.

You don't have to memorize tool names. Claude will pick the right ones when you ask normal questions ("what's the simplest way to create a new user?") and the system prompt from the MCP server nudges it toward grounded, cite-aware answers.

## Permissions and security

The access token in the config grants *all* MCP tools by default. If you want to scope it — say, disable `execute_endpoint` because you don't want Claude making real API calls — head to the **Tools** sub-tab in the MCP dashboard and toggle individual capabilities.

Tokens are opaque, revocable, and tied to one project. If you ever think one leaked, click **Rotate** on the dashboard: the old token stops working instantly and you'll need to update the config on any machine using it.

## Troubleshooting

- **Plug icon doesn't appear**: usually a JSON syntax error in the config. Run it through `jq .` to validate.
- **Tools show "Error: 401"**: token is wrong, expired, or the project's MCP is disabled. Re-copy from the dashboard.
- **Tools show "Error: 402"**: owner's plan was downgraded to Free. Upgrade to Pro to re-enable.
- **Timeouts on `execute_endpoint`**: the API you're targeting is slow or unreachable. Rate-limited to 15 calls/minute per project.

Once it's wired up, it tends to stay wired up. The workflow unlocks a lot — give it an afternoon and you'll wonder how you shipped integrations without it.


---

## Auto-sync OpenAPI Docs from GitHub Actions

URL: https://docs.outworx.io/guides/auto-sync-github-actions
Category: Integration
Published: 2026-04-24
Reading time: 5 min

> Keep hosted API docs in lockstep with main. Wire a GitHub Action that uploads your OpenAPI spec to Outworx Docs on every push — no redeploys, no manual updates.
Docs drift. You ship a new endpoint, your OpenAPI spec updates in the repo, but the hosted docs still show last week's schema. Customers file "your docs are wrong" tickets. You swear you'll set up a cron. You don't.

Outworx Docs solves this two ways. The easiest is *spec URL auto-sync* — point us at a URL and we re-fetch on a schedule. The more robust way is a GitHub Action that pushes the spec to us on every merge to `main`, so docs update the instant your API does.

This guide covers both, with the GitHub Action setup at the center.

## Option 1 — Spec URL auto-sync (the 30-second option)

If your API serves the OpenAPI JSON at a public URL (e.g. `https://api.yourcompany.com/openapi.json`), you don't need GitHub Actions at all.

1. Open your project's **API Spec** tab on Outworx.
2. Click **New version** → **From URL**.
3. Paste the URL and pick a sync interval: hourly, daily, or weekly.
4. Done.

Every interval tick, Outworx fetches the URL, parses it, and bumps the version. Your hosted docs reflect the latest spec without any CI pipeline.

**When this isn't enough**: if your OpenAPI spec lives only in a git repo (never served publicly), or you want zero-lag updates the moment a PR merges, use the GitHub Action approach below.

## Option 2 — GitHub Actions (zero-lag, push-based)

The flow:

1. You merge a PR to `main` that changes your OpenAPI spec
2. A GitHub Action fires on push
3. It POSTs the spec file to Outworx's upload API
4. Your hosted docs update within seconds

### Step 1: Get your project upload token

[Open your Outworx Docs dashboard](https://docs.outworx.io/dashboard), click into your project, and go to the **Settings** tab. Scroll down past Project Details to the **API access — spec upload** card and click **Generate upload token**. You'll get a token that looks like `otwx_...` and is scoped to spec upload on this one project (nothing else — it can't read chats, analytics, or MCP). The same card shows pre-filled curl and GitHub Actions snippets with your token already dropped in, so you can copy-paste straight into your workflow file.

Copy the token. If you miss it, you can click the eye icon to reveal it again later, or rotate to get a new one.

Add it to your GitHub repo as a secret: **Settings → Secrets and variables → Actions → New repository secret**.

- Name: `OUTWORX_TOKEN`
- Value: your `otwx_...` token

### Step 2: Drop in the workflow

The fastest path is the official `abdallaemadeldin/upload-spec-action@v1`. Three lines of YAML, no `curl` to maintain, no exit-code translation, no "did I quote the JSON right?" debugging at 2am.

Create `.github/workflows/sync-docs.yml`:

```yaml
name: Sync API docs

on:
  push:
    branches: [main]
    paths:
      - "openapi.yaml"
      - "openapi.json"
      # Uncomment if your spec is generated from source — pair this
      # with the "Regenerate spec" step below so a code change actually
      # produces a fresh openapi.yaml before the upload runs.
      # - "src/**/*.ts"

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Uncomment if your API auto-generates its spec from code.
      # - name: Regenerate spec
      #   run: npm ci && npm run generate:openapi

      - uses: abdallaemadeldin/upload-spec-action@v1
        with:
          token: ${{ secrets.OUTWORX_TOKEN }}
          project: <YOUR_SLUG>
          spec: ./openapi.yaml
```

Replace `<YOUR_SLUG>` with your project slug (the subdomain before `.docs.outworx.io`). Without a `version` input, the push updates your project's current default version in place — the behavior most teams want for a `main`-branch sync.

> **Where does `${{ secrets.OUTWORX_TOKEN }}` come from?** It's the repo secret you added in Step 1. GitHub substitutes it at run time so your actual token is never in the YAML (or your git history). The action's exit codes mirror the CLI: 1 for user errors (won't retry on its own), 2 for transient API errors (safe to re-run).

### Step 3: Optional — version your docs by git tag

If you want each git tag to become a new docs version rather than overwriting the default, pass the `version` input:

```yaml
- uses: abdallaemadeldin/upload-spec-action@v1
  with:
    token: ${{ secrets.OUTWORX_TOKEN }}
    project: <YOUR_SLUG>
    spec: ./openapi.yaml
    version: ${{ github.ref_name }}  # e.g. v1.2.3 → version label "v1.2.3"
```

### Step 4: Optional — preview deploys for every PR

Pair the action with `pull_request` events to publish a per-PR preview at `/preview/<pr-number>`:

```yaml
on:
  pull_request:
    paths: ["openapi.yaml"]

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: abdallaemadeldin/upload-spec-action@v1
        with:
          token: ${{ secrets.OUTWORX_TOKEN }}
          project: <YOUR_SLUG>
          spec: ./openapi.yaml
          preview: true
          pr: ${{ github.event.pull_request.number }}
          commit: ${{ github.event.pull_request.head.sha }}
          branch: ${{ github.event.pull_request.head.ref }}
```

Preview pushes are filtered out of your public docs picker, never become the default version, and auto-prune 14 days after the PR closes. They also require a **personal access token** (`otwx_pat_*`) — per-project upload tokens don't carry the `version:write` scope previews need. Mint one in [Settings → API tokens](https://docs.outworx.io/settings).

### Prefer raw curl?

You don't need the action. The same upload endpoint is reachable via `curl`:

```yaml
- name: Upload to Outworx Docs
  env:
    OUTWORX_TOKEN: ${{ secrets.OUTWORX_TOKEN }}
  run: |
    curl -sS --fail-with-body -X POST \
      "https://docs.outworx.io/api/projects/<YOUR_SLUG>/upload" \
      -H "Authorization: Bearer $OUTWORX_TOKEN" \
      -H "Content-Type: application/yaml" \
      --data-binary "@openapi.yaml"
```

Trigger on tag pushes instead:

```yaml
on:
  push:
    tags:
      - "v*.*.*"
```

Now every release tag becomes a permanent docs version visitors can switch between. The latest tag becomes the default.

## Verifying it works

After your first merge, check the **Actions** tab on GitHub — you should see "Sync API docs" green. On the Outworx side, go to **API Spec** → you should see a new version with `Last synced: a few seconds ago`.

If the action fails, the response body is JSON with a machine-readable `code` and a human `error`:

- `MISSING_TOKEN` / `INVALID_TOKEN` — the `Authorization` header is absent or doesn't match. Re-copy from the Settings tab.
- `UPGRADE_REQUIRED` — you're on a plan that caps the number of active versions (Free: 1, Pro: 3). The body includes your plan + limit + an upgrade URL. Either drop the `?version=` query param to update your default version in place, or upgrade.
- `SPEC_TOO_LARGE` — bigger than 50MB (or whatever your hosting platform caps request bodies at — Vercel serverless is 4.5MB on Hobby/Pro). For truly huge specs, point a spec URL at the file and let auto-sync fetch it server-side, which has no size cap.
- `UNKNOWN_FORMAT` — the body wasn't recognized as OpenAPI/Swagger/GraphQL. Often a curl pathing issue; check `--data-binary '@path/to/openapi.yaml'`.
- `PARSE_FAILED` — the spec was malformed. The message explains which line / field.
- `LABEL_CONFLICT` — race between two pushes at the same label. Retry.

## Why this pattern works so well

API specs are the source of truth for your contract with developers. When docs lag behind the spec, you pay in confusion, support tickets, and lost trust. Push-based sync flips the dynamic — **you can't ship an API change that doesn't update the docs**, because they're literally the same commit.

Combine this with Outworx's [MCP server](https://docs.outworx.io/guides/connect-claude-desktop-mcp) and your users' AI assistants will always have the latest spec too. Ship once, everything else catches up automatically.


---

# Changelog

Every user-visible change to Outworx Docs, newest first.

---
## Enterprise foundation — REST API, PR previews, RBAC, audit log, theme tokens, CLI

Date: 2026-05-09
Categories: Feature, Platform

> Outworx grows up: a public REST management API with personal access tokens for full automation, PR preview deploys so every pull request gets its own throwaway docs URL, two-layer role-based access control for Business teams, a complete audit log pipeline with SIEM webhooks and per-account retention, per-theme color tokens with a light/dark lock for brand-matched docs, and an official `@outworx/cli` plus `outworx/upload-spec-action` so any CI can push specs in three lines. Six features that close the SOC2 / enterprise gap and make the spec-to-docs loop fully automatable.

Highlights:
- **Public REST API at `/api/v1`** — full CRUD on Projects (`GET/POST/PATCH/DELETE /api/v1/projects[/{slug}]`) and Versions (`GET/POST/PATCH/DELETE /api/v1/projects/{slug}/versions[/{label}]`). Standard error envelope (`{ error: { code, message, details? } }`) and list envelope (`{ data, pagination }`). Single-default invariant enforced server-side: `PATCH is_default:true` demotes the previous default in the same write, `DELETE` on the default returns 409. Sensitive columns (`password_hash`, `mcp_token`, `upload_token`) filtered through `serializeProject` so future schema fields can't auto-leak
- **Personal access tokens** — `otwx_pat_*` prefix, sha-256 hashed at rest, plaintext shown once at creation, optional `expires_at`, revocation by row delete. New `personal_access_tokens` table with a unique-on-hash index for O(1) auth lookups. New API tokens card on Settings with create / list / revoke + a copy-once dialog. `last_used_at` is awaited (not fire-and-forget) so the dashboard's dormant-token signal is reliable
- **PR preview deploys** — Pro+ feature on the v1 API. `POST /api/v1/projects/{slug}/versions?preview=true&pr=42&commit=<sha>&branch=<name>` creates a 14-day preview version with PR metadata for the banner. Re-pushing the same label as commits land on the PR updates the row and rolls the TTL forward. Separate `maxPreviewsPerProject` plan cap so previews don't crowd out release versions. Hidden from the default version list unless `?include_previews=true`. Pruning runs in `pg_cron` — no Vercel Cron quota burn
- **Two-layer RBAC** — Business plan unlocks `editor` / `viewer` / `none` roles. Layer 1 (`account_collaborators.role`) sets the account-wide default; Layer 2 (`project_collaborator_roles`) is a per-project override. `none` explicitly hides a project from a collaborator who'd otherwise have access ("Bob can see all my stuff except this acquisition project"). Owners are implicit and never have a row anywhere. Roles enforce in `requireApiPermission` (v1 API) and `requireActionPermission` (dashboard server actions) — every mutation goes through the same gate. Pro / Free flatten to `editor` for back-compat but stored overrides survive a downgrade so re-upgrading restores the permission map without a re-pick
- **Per-project Access tab** — owners get a UI to invite seats, set the account-default role for new collaborators, and override roles per project. Viewer rows render with mutation UI disabled across every project tab (Spec, Mock, Customize, SDKs, Diffs, etc.) so the role gate is visible, not just enforced server-side. Cmd+K and direct `/dashboard/<id>` nav respect `none` overrides — no leaked surface area for projects you've explicitly hidden
- **Audit log** — every mutation (dashboard or API) writes a row with a stable UPPER_SNAKE action code, actor, target, project, source (`dashboard` / `api` / `system`), and structured metadata. 30+ codes covering project lifecycle, branding / theme, versions, previews, specs, collaborators, and tokens. Plan-gated to Business for both writes and reads. New `/settings/activity` page with a filter strip (date range, actor, project, action category) and CSV export at `/api/audit/export.csv` for SOC2 evidence dumps. Per-row `describeEvent()` produces the human one-liner (`bob@acme.com: editor → viewer (project override)`) instead of dumping raw metadata
- **Audit log retention** — per-account `audit_log_retention_days` configurable from 30 to 3650 days (default 730 / 2 years, covers SOC2 Type II). Daily prune job at 03:23 UTC via `pg_cron`, single-statement DELETE through the indexed (account, created_at) path. Retention setter is on the new Audit log card on Settings
- **Audit webhook delivery** — Business customers can pipe the full event stream into their own SIEM (Datadog Logs, Splunk HEC, Honeycomb). One `POST` per audit row with `Content-Type: application/json`, `X-Outworx-Event` (action code), `X-Outworx-Delivery` (event uuid for idempotency), and `X-Outworx-Signature: sha256=<hex>` (HMAC-SHA256 over the body). 5s timeout, never throws — the receiver's own retry/queue handles durability
- **Security notifications** — owner gets an email (always) and an optional Slack webhook ping on `COLLABORATOR_ROLE_CHANGED` and `TOKEN_CREATED`. Slack uses block-kit (header + section + Review-activity-log button) and a 5s budget so a flapping webhook can't stall the underlying mutation
- **Per-theme color tokens** — Pro+ feature gated on `brandingEnabled`. Override a bounded set of tokens (primary, background, foreground, muted, border, card) per theme, set a shared corner radius, and lock the docs to light-only or dark-only when your brand has no second palette — the theme toggle hides when locked. Tokens apply to both the hosted docs page and the Try-It embed widget. Legacy `branding.accentColor` falls through as the per-theme primary so existing projects render identically until they opt in. **Tokens are preserved across plan downgrades** (read-time gated, not wiped) so re-subscription snaps the visual config back without forcing a re-pick
- **`@outworx/cli` on npm** — `outworx push <spec> --project <slug>` works on any CI runner or laptop. Hand-rolled argv parser (no commander/yargs dep) keeps the tarball at ~30KB for fast `npx` cold-starts. Sniffs the token prefix: `otwx_pat_*` routes to the v1 API (preview pushes work), `otwx_*` routes to the per-project upload endpoint. Config resolver walks up from cwd looking for `outworx.json` / `.outworxrc.json` (eslint-style discovery). Scriptable exit codes: 1 user error, 2 transient (5xx / network), 3 internal — CI can pattern-match for retry policy
- **`outworx/upload-spec-action` on the GitHub Marketplace** — composite action wrapping `npx @outworx/cli@<pin>`. Three lines in a workflow file replace 15 lines of curl. `cli-version` input pins a major so wire-format bumps are opt-in. Drops into any workflow that already runs Node 20+ on github-hosted runners
- **Three-tab discovery** (CLI / Action / curl) on the PAT card, the per-project upload-token card, the `/api` Quick Start step, and the empty-state of the Spec tab — every place a customer first realizes "I need to push this from CI" now leads with the right snippet. CLI is recommended for non-GitHub CI and laptop pushes; Action is recommended for GitHub-hosted CI; curl stays as the escape hatch
- **Settings page tabs** — eight stacked cards became four tabs (Account / Security / Plan / Danger), URL-persisted at `?section=` so deep-links from emails and audit-log notifications land on the right tab. Mobile uses a `<Select>` instead of a tab strip to avoid horizontal scrolling. Security tab clusters the SOC2 nucleus: API tokens, security notifications, audit log delivery + retention, recent activity
- **Diffs / SDKs / Collections / Monitoring lock cards unified** — Pro+ features now share one consistent lock-card chrome with a clear upgrade CTA, replacing four bespoke gating layouts
- Six new Supabase migrations: `add_personal_access_tokens`, `add_account_collaborators_updated_at`, `add_preview_versions`, `add_rbac_and_audit_log`, `add_account_default_role`, `add_security_slack_webhook`, `audit_log_retention`, `audit_log_webhook`, `add_theme_tokens` — all additive, all RLS-locked or admin-client-only as appropriate
- ~1,400 lines of new tests covering v1 auth (`v1-auth.test.ts`), Projects + Versions CRUD with RBAC scenarios (`v1-projects.test.ts`, `v1-versions.test.ts`), the CLI argv parser + push routing (`tools/cli/tests/`), audit-log writers + describe (`audit-log.test.ts`, `audit-log-describe.test.ts`), webhook signing + delivery (`audit-webhook.test.ts`), theme-token resolution (`theme-tokens.test.ts`), RBAC matrix + action gates (`rbac.test.ts`, `rbac-action-gates.test.ts`), and the security notifier (`notifications-security.test.ts`)

---
## Docs page builder — custom header, per-endpoint markdown, white-label option

Date: 2026-05-07
Categories: Feature

> Pro and Business projects can now compose their hosted docs the way you'd compose a marketing page. Replace the default top bar with your own logo, custom title, CTA buttons, top-bar search, and plain-text links. Add markdown intros above the auto-generated parameters and extras below the Try-It panel on every endpoint — same idea as a Mintlify MDX endpoint page, no scaffolding required. Paid plans can also remove the “Powered by Outworx Docs” footer for fully white-labeled docs.

Highlights:
- **Custom docs header** — logo override, custom title, up to 6 CTA buttons (solid / outline / ghost variants), up to 8 plain-text links, and an optional ⌘K-aware top-bar search input that mirrors the sidebar filter
- **Per-endpoint markdown overrides** — write GitHub-flavored markdown that renders ABOVE the auto-generated parameters/responses (intro) and BELOW the Try-It panel (extras). Headings, tables, task lists, code blocks, and inline links all work; raw HTML is sanitised to prevent cross-tenant XSS
- **Live preview in the dashboard** — a new Customize tab with an endpoint picker, version selector, and toggle-able preview pane mirrors exactly how the markdown will render on your public docs
- **Watermark removal toggle** — Free-plan docs always show the “Powered by Outworx Docs” badge; paid plans default to keeping it but can flip a single switch to remove it for white-labeled docs
- **14-day retention on downgrade** — if a paid account drops to Free, the saved customizations sit untouched in the database for 14 days. Re-subscribing inside the window restores everything; afterwards the prune cron hard-deletes the rows. Set/cleared on every Stripe webhook and on the safety-net `syncSubscriptionStatus` path
- New Supabase tables `project_customizations` (one row per project: header config + watermark flag) and `endpoint_customizations` (markdown intros/extras keyed by version + endpoint), both RLS-locked to project owners and active collaborators
- Plan gate: new `customizationsEnabled` flag on `PlanConfig` reused by the dashboard tab, the server actions, and the public renderer — single source of truth, same pattern as `mcpEnabled`
- Cron route `/api/cron/customizations-prune` runs hourly behind `CRON_SECRET`, deletes expired rows in batches, and clears the expiry timestamp so re-runs are idempotent

---
## Full API lifecycle — SDKs, spec diffs, uptime monitoring, saved requests, embeddable Try-It

Date: 2026-05-06
Categories: Feature, Platform

> Outworx becomes the platform for API teams: type-safe SDKs in TypeScript and Python, breaking-change detection on every spec PR with a one-line GitHub Action, per-version uptime monitoring with public status pages, Postman-style saved requests with environment variables, and an embeddable Try-It widget you can drop on any marketing page or blog. Replaces five separate tools (Speakeasy / Bump.sh / Checkly / Postman / docs site) with one $9/mo subscription.

Highlights:
- **SDK generator** — every spec compiles to a single drop-in `.ts` or `.py` file with typed methods, dataclasses, and a Client class. No npm package to maintain, no build step, no codegen toolchain. Re-download from the dashboard or pipe through `curl` in CI on every spec change. Adding new languages is a 150-line generator under `lib/sdk/`
- **Spec diff + GitHub PR action** — compare any two project versions with semver-bump suggestion (major / minor / patch) classifying every change as breaking / additive / cosmetic. Drop the included GitHub Action workflow into `.github/workflows/` and every PR that touches your spec gets an automatic comment with the diff before reviewers approve. Cross-format guard allows OpenAPI ↔ Swagger (useful for migrations) and refuses GraphQL ↔ HTTP (different semantic models)
- **Per-version uptime monitoring** — toggle monitoring per endpoint and we probe every 10 minutes from the edge, recording latency + status. Each version gets its own status page at `/status/<slug>/<version>` so staging/production branches don't share an incident dashboard. Public projects get a shareable `/status/<slug>` URL customers can bookmark. GraphQL specs get a single introspection probe instead of per-query checks. 14-day check retention
- **Embeddable Try-It widget** — drop a runnable demo of any endpoint into a marketing page or blog with one `<script src="https://docs.outworx.io/widget.js">` tag plus a `<div data-outworx-embed>`. Lazy-loaded iframe, no React or Vue dependency, dispatches a `outworx:rescan` event for SPA route changes
- **Saved requests + environments (API client built in)** — Postman-style request templates with `{{var}}` placeholders that resolve from a chosen environment at run time. One click to flip between staging and production. Run any saved request with response auto-rendering for JSON / HTML (sandboxed) / XML / images / video / audio / PDF, with byte-faithful base64 round-trip for binary types. Localhost requests automatically route through `npx @outworx/proxy` (same SSRF guard as the docs Try-It panel)
- Single source of truth for plan gating via `lib/plan-gate.ts` — paid features (SDKs / diffs / monitoring / collections / embed) all gate on the same flag with consistent crown badges in the dashboard sidebar and 402 server-side enforcement on every action. Free downgrade is graceful: existing rows survive, cron stops probing, dashboard shows the upgrade UI
- Per-project rate limits on the diff and SDK endpoints (60/min/project, same Upstash limiter as the MCP route) so CI workflows can't loop hot
- Two new Supabase migrations: `monitor_targets` / `monitor_checks` / `project_environments` / `project_collections` (additive, RLS-locked), then `monitor_targets.version_id` for per-version status pages
- Cron lives in Supabase pg_cron (free-tier friendly) calling `/api/cron/uptime` on a 10-minute schedule with the `CRON_SECRET` Bearer fetched from Vault

---
## Mock server — free mock URL for every public project

Date: 2026-05-02
Categories: Feature, Platform, AI

> Every public project gets a hosted mock at `docs.outworx.io/mock/{slug}/{...}`. Frontends call it while the real backend is still in flight; integration tests pin it as a deterministic fixture. Spec-driven responses for OpenAPI / Swagger / GraphQL, stateful overrides with dynamic templating, opt-in strict request validation, opt-in spec-driven auth enforcement, network simulation for retry / timeout testing, override import / export bundles, per-version routing, an activity feed, and a working Try It panel for both REST and GraphQL.

Highlights:
- Path-based mock URL on every public, non-password-protected project — `docs.outworx.io/mock/<slug>/<...path>` for REST, `/mock/<slug>/graphql` for GraphQL. No plan gate, on by default
- Response selection priority: explicit `example` → named `examples` → schema-level example → faker-extended sample with full `$ref` / `allOf` / `oneOf` / `anyOf` resolution and OpenAPI 3.1 nullable handling
- GraphQL execution via the `graphql` package — selection-set aware, scalars / enums / lists / mutations all return shape-correct samples (Int → 42, ID → uuid, DateTime → ISO timestamp, lists → 2 sample items, enums → first value). Errors come back as standard `{errors:[...]}` with status 200
- `Prefer: code=N` for status overrides; `Prefer: example=<name|random|sequential>` for picking a named example or cycling through them. Sequential is Redis-backed and keyed per `(project, version, method, path)` — perfect for pagination testing
- **Stateful overrides** — pin a custom (status, body, headers) for a specific request shape right from the dashboard. Match by method + path + optional query / headers / partial JSON body / GraphQL operationName. Priority + first-match-wins, optional latency simulation (0–10s), 50 overrides per project. One-click duplicate clones a rule into a disabled copy for safe iteration
- **Dynamic templating in overrides** — override response bodies, headers, and Content-Type render `{{...}}` placeholders at request time. ~30 built-in tokens: `{{$uuid}}`, `{{$now}}`, `{{$timestamp}}`, `{{$randomInt:1:100}}`, `{{$randomEmail}}`, `{{$randomFullName}}`, `{{$randomCity}}`, plus full request echoing — `{{request.body.email}}` (dotted-path JSON lookup), `{{request.path.id}}` (template binding), `{{request.headers.authorization}}`, `{{request.query.page}}`. Smart unwrapping keeps JSON valid when the placeholder resolves to a number / bool. In-dialog cheatsheet click-to-insert. Graceful degradation on unknown tokens
- **Strict request validation (opt-in)** — toggle on per project to validate every incoming request against the matched operation: required path / query / header parameters, JSON body schema (types, `required`, `enum`, `pattern`, `format`, lengths, ranges, `multipleOf`, `additionalProperties`, full `$ref` / `allOf` / `oneOf` / `anyOf` resolution). Failures return 400 with field-level error paths (`body.user.email`, `query.limit`) and `X-Mock-Synth: validation-error`. Overrides skip validation
- **Spec-driven auth enforcement (opt-in)** — toggle on to honor the spec's `securitySchemes` / `securityDefinitions`. Requests missing the required apiKey (header / query / cookie) / Bearer / Basic / OAuth2 / OpenID Connect get 401 with a tailored `WWW-Authenticate` header and a per-scheme hint. Per-operation `security` overrides spec-level; empty `security: []` opts an op out. Presence-only check — catches the SDK-dropping-the-API-key bug class without faking a real auth backend. Overrides skip enforcement
- **Network simulation** — configurable latency band (uniform-random per request, 0–30,000ms) plus chaos error rate (0–100% of requests forced to a custom 4xx/5xx). Stress-tests frontend retry logic, loading states, and timeout handling without writing per-endpoint failure rules. Overrides + validation errors bypass the simulator. `X-Mock-Chaos-Latency-Ms` + `X-Mock-Synth: chaos-error` diagnostics
- **Override import / export** — download every override as a versioned JSON bundle (`mock-overrides-<project>-<date>.json`), import into another project with merge-or-replace. Per-rule normalisation on import skips malformed entries instead of failing the whole bundle. Capacity-checked up-front against the 50-override cap. Project-local IDs stripped so a bundle round-trips cleanly between staging and prod
- Multi-version aware — projects with mixed REST + GraphQL get per-version URLs in the dashboard; all-REST projects collapse to one URL with smart fallthrough across versions when a path lives only in v2
- Per-endpoint disable list — opt specific operationIds out of mocking, scoped per-version or project-wide. Returns 503 for those alone; rest of the spec keeps mocking. Useful for payment / auth / destructive endpoints
- Activity feed in the Mock Server dashboard tab — last 50 hits with method / path / response source, plus 24h/7d totals, error rate, top endpoint, and a synth breakdown that flags spec gaps (`empty-schema` highlights endpoints whose spec is missing a response model)
- Try It panel works for both REST and GraphQL — REST shows the existing method/path/params builder; GraphQL gets a query editor with auto-generated starter, variables JSON, and operationName. Same emerald 'Use Outworx mock server' toggle on both, same `Mock override fired` badge after a request
- Open CORS — call the mock from any browser. No built-in auth (use the spec-driven enforcement toggle). Same access threshold as the public docs page
- Two-layer rate limiting (per-project 120/min, per-IP 60/min) so a single tenant or client can't monopolise the function budget
- Diagnostic response headers on every call: `X-Mock-Server`, `X-Mock-Synth` (`override` / `example` / `schema-walk` / `empty-schema` / `graphql-schema-walk` / `validation-error` / `auth-required` / `chaos-error` / etc.), `X-Mock-Override-Id` when a rule fires, `X-Mock-Version`, `X-Mock-Matched-Path`, `X-Mock-Operation-Id`, `X-Mock-Chaos-Latency-Ms` when the simulator added delay
- Empty-schema FastAPI-style responses (`schema: {}`) return an explanatory placeholder instead of a confusing `{}` — points at the missing `response_model`
- 14-day request-log retention with a 5,000-row cap per project; HTTP-spec-compliant body handling for 1xx / 204 / 304 statuses

---
## Inbox security — HMAC, Basic auth, IP allowlist

Date: 2026-04-28
Categories: Feature, Platform

> Webhook inboxes can now enforce signature verification, HTTP Basic auth, and a source-IP allowlist on incoming requests. Defaults stay open so the zero-config capture flow still works, but a Security toggle on each inbox turns it into a production-grade endpoint that rejects unsigned, unauthenticated, or off-network traffic before anything is persisted.

Highlights:
- Per-inbox HMAC verification with 8 branded schemes (Outworx, Stripe, GitHub sha256/sha1, Slack, Shopify, Linear, Zendesk) plus a Custom HMAC mode where you pick the header name, algorithm (sha1/256/512), encoding (hex/base64), and prefix
- Configurable timestamp tolerance (default 300s) for replay protection on schemes that sign a timestamp; constant-time comparison on every check
- HTTP Basic auth — username + password gate with a proper 401 + WWW-Authenticate response on mismatch
- Source IP allowlist — IPv4 and IPv6 CIDR ranges, validated by Postgres at write time so half-configured rules can't ship
- Replays auto-sign with the inbox's stored secret using the configured scheme — Security-locked inboxes accept their own replays without manually re-pasting the secret
- Secrets and passwords never leave the server: the Security dialog shows a 'leave blank to keep' affordance instead of round-tripping the stored value to the browser

---
## Webhooks playground — capture, sign, replay

Date: 2026-04-28
Categories: Feature, Platform

> A standalone webhooks workspace that captures incoming requests, lets you fire signed test payloads at any handler, replays captures to a different URL, and verifies signatures from 10 webhook providers — all without leaving Outworx. Built for API providers documenting their webhooks AND for any developer debugging an integration.

Highlights:
- New /webhooks top-level workspace — Inboxes, Events, Activity sub-sections all URL-persisted
- Standalone-first inboxes — paste the unique capture URL into Stripe, GitHub, Slack, or any sender; requests stream into the dashboard in real-time via Supabase Realtime
- Send-test from anywhere — fire arbitrary payloads at any endpoint, sign with HMAC-SHA256 in Stripe-v1 format, and capture the response. Reusable from the workspace, the inbox toolbar, the Cmd+K palette, and per-event from spec catalogs
- Replay captures — one click takes any captured request and re-sends it to a new URL with the original payload + headers preserved
- HMAC verifier with 10 schemes — Stripe, both GitHub variants, Slack, Shopify, Square, Linear, HubSpot, Zoom, Zendesk, plus raw HMAC-SHA1/256/512 in hex or base64. Auto-detects the scheme, computes the signature in your browser (secret never hits the server), warns on stale timestamps
- Tamper-proof plan limits — append-only ingest ledger means clearing your captures doesn't reset the cap; senders that hit the limit get 429 with Retry-After until entries age out
- Optional project link — when an inbox is tied to a project whose OpenAPI 3.1 spec declares webhooks, the catalog shows up under the Events tab with Send buttons per event
- Free: 5 inboxes, 500 captures / 7d. Pro: 25 inboxes, 10,000 captures / 30d. Business: unlimited.

---
## Team collaboration — invite teammates as seats

Date: 2026-04-26
Categories: Feature, Platform

> Pro and Business plans now include collaborator seats. Invite teammates by email and they get full access to your projects — upload specs, edit settings, configure MCP, view analytics. Only two things stay owner-only: deleting projects and managing billing.

Highlights:
- Pro: 3 collaborator seats included. Business: 10 seats.
- Invite via email; invitees sign in with the invited address to accept.
- Collaborators see your projects alongside their own with a 'Shared by' badge.
- Features on shared projects use the OWNER's plan — a Free collaborator gets Business AI chat + MCP when working on a Business-tier project.
- New Team card in Settings for managing active members + pending invites + one-click remove.
- Row-Level Security extended across every owner-gated table so data access stays airtight.

---
## Launch — MCP server, guides hub, dynamic OG

Date: 2026-04-25
Version: 1.0
Categories: Feature, AI, Platform

> The 1.0 launch push: every project gets a Model Context Protocol server so AI assistants can operate your API; new /guides content hub with seeded long-form tutorials; dynamic OG image generation for better link previews everywhere.

Highlights:
- Per-project MCP server at /api/mcp/<slug> with 12 tools (list/search endpoints, generate TypeScript types, ask docs, execute live calls, and more)
- Schema inference — live calls via execute_endpoint sample response bodies and merge into a stored schema, so generated types stay accurate even when the OpenAPI spec is incomplete
- Dashboard MCP tab — one-click token + Claude Desktop / Cursor / Cline / curl connection snippets, per-tool permission toggles, recent activity feed
- Guides content hub at /guides with OpenAPI-to-TypeScript, Claude Desktop MCP setup, GitHub Actions auto-sync, and ReadMe/Mintlify migration tutorials
- Dynamic OG images via /api/og — every marketing page, guide, and comparison gets a branded, on-brand preview
- Tightened chat token accounting — visitors are billed per-turn (their message + response) instead of the full system prompt, so daily caps now correlate with real visitor intent
- Sliding conversation window — chat keeps the last 8 messages instead of the entire session, bounding our OpenAPI bill as threads get long

---
## Analytics, SEO, and mobile polish

Date: 2026-04-24
Categories: Improvement, Platform

> PostHog analytics wired at the conversion points that matter, structured-data + sitemap cleanups so Google indexes what we actually want, and a pass over the MCP tab for mobile screens.

Highlights:
- PostHog client-side integration with custom events at chat, subscription, and project lifecycle moments
- FAQPage / SoftwareApplication / BreadcrumbList / Organization JSON-LD across marketing
- Sitemap emits subdomain/custom-domain canonicals for hosted docs (no more duplicate-content flags in Search Console)
- Hero badge, MCP tab, and activity feed laid out cleanly on mobile
- llms.txt published so Claude, ChatGPT, and Perplexity see accurate context about the product

---
## AI chat quality + billing correctness

Date: 2026-04-22
Categories: Fix, AI

> A round of chat-drawer fixes that landed right before launch: accurate endpoint pills in responses, honest daily-token counters, and a hard-to-spot DB constraint bug that was silently dropping every chat usage row.

Highlights:
- ai_usage CHECK constraint now allows action='chat' — previously every chat usage insert was silently rejected, leaving the daily-tokens counter at 0 forever
- Fallback completion-token estimation when OpenAI omits the usage chunk
- Assistant messages now pill-ify `[endpointId]` citations correctly even when the model wraps them in backticks
- Copy-to-clipboard on every code block in the chat drawer + the Chat Activity admin view

---
## Sentry, welcome email, and onboarding

Date: 2026-04-20
Categories: Platform, Feature

> Pre-launch infrastructure so new users have a first-run experience that doesn't feel empty and errors actually get reported.

Highlights:
- Sentry error monitoring wired for server, edge, and browser runtimes
- Welcome email on first dashboard load (Resend) with a 3-step onboarding checklist, Outlook + dark-mode-safe HTML, and atomic once-only delivery
- Dashboard empty state with a clear 'upload your first spec' CTA
- Global crash page that reports to Sentry

---
## AI chat drawer on public docs

Date: 2026-04-15
Categories: Feature, AI

> The big visitor-facing AI feature. A floating Ask AI button on every Pro/Business docs site opens a chat drawer trained on the project's spec.

Highlights:
- Streaming chat completions with per-visitor session persistence via localStorage
- pgvector-backed RAG retrieval for specs with 50+ endpoints, with lazy embedding on first query
- Chat Activity dashboard tab so project owners see what visitors actually ask
- Daily token caps per plan (Free 0 / Pro 25k / Business 200k) + hourly rate limits per visitor
- Endpoint citations in answers render as clickable pills that jump the docs to the referenced endpoint

---
## Subscription flows reworked

Date: 2026-04-10
Categories: Feature, Improvement

> Upgrade and downgrade UX rebuilt around explicit preview-and-confirm dialogs, plus scheduled downgrades via Stripe Subscription Schedules so customers never lose paid access mid-cycle.

Highlights:
- Preview dialog shows exactly what will be charged today, the prorated breakdown, and the next recurring amount
- Downgrades are scheduled to the end of the current period (not immediate) via Stripe Subscription Schedules
- Billing cycle switches (monthly ↔ yearly) handled in-place without creating new subscriptions
- Pricing restructured — Pro at $9/mo, Business at $19/mo, 10-month discount on yearly

---
## Multi-version + custom domain + auto-sync

Date: 2026-03-20
Categories: Feature, Platform

> Project-level features that make hosted docs production-ready for teams.

Highlights:
- Multiple active versions per project with a dropdown switcher on public docs
- Custom domains with auto-provisioned SSL (Business plan) — one CNAME, done
- Auto-sync from a spec URL on an hourly / daily / weekly schedule
- Deep-link to any endpoint by URL hash; Overview page lists every endpoint clickably

---
## AI search, descriptions, code examples

Date: 2026-02-25
Categories: AI

> First-pass AI features for documentation quality, before the full chat drawer landed.

Highlights:
- Natural-language search across the spec (Free tier gets 5/month; paid gets unlimited)
- Auto-generated endpoint descriptions for sparse specs
- AI code examples in any language or framework — NestJS, Django, Rails, FastAPI, Rust, and more

---