Quickstart

1. Create an account

Sign up with email and a password, or with GitHub or Google. The Free plan needs no card and is not a trial: one repository, 25 watched pages and 30 syncs a month, permanently.

Create an account, then come back here.

2. Connect a repository

From Settings → Repositories, install the Docsmith GitHub app and grant it access to one repository. Then nominate the paths that hold your documentation:

docs/**/*.md
docs/**/*.mdx
README.md

Docsmith reads code from anywhere in the repository, but it will only ever write a draft for a file inside these paths. Indexing a 340-page docs set alongside a 200,000-line repository takes about four minutes; you will get an email when it finishes.

The permissions the app requests, and why each one is needed, are listed on the GitHub app page.

3. Wait for a commit, or force one

From here Docsmith is passive: it reads every push and drops the four in five that cannot affect documentation. If you would rather not wait for a real change, run one by hand.

With the CLI

npm install --global @docsmith/cli
docsmith login
docsmith sync --diff HEAD~1..HEAD --docs docs/

The CLI reads the diff from your local git history and the pages from disk, so it works before you have connected anything. Full usage is on the CLI page.

With the API

One request. Everything the product does is behind this endpoint.

curl https://api.docsmithhq.com/v1/sync \
  -H "Authorization: Bearer $DOCSMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "acme/checkout-sdk",
    "docPath": "docs/guides/retries.md",
    "diff": "'"$(git diff HEAD~1 -- src/retry.ts | jq -Rsa . | sed 's/^"//;s/"$//')"'",
    "doc": "'"$(jq -Rsa . < docs/guides/retries.md | sed 's/^"//;s/"$//')"'"
  }'

4. Read the result

A stale verdict looks like this, trimmed for length:

{
  "verdict": "stale",
  "changeSummary": "Lowered the default attempt count from 5 to 3 and replaced the fixed delay with exponential backoff.",
  "headline": "Two passages on this page state the old defaults.",
  "findings": [
    {
      "section": "Defaults",
      "quote": "By default the client makes up to 5 attempts and waits a fixed 200 ms between",
      "why": "DEFAULT_ATTEMPTS moved from 5 to 3 and delayMs was replaced by baseDelayMs, defaulting to 250.",
      "severity": "breaking",
      "confidence": 0.94,
      "verified": true
    }
  ],
  "reasoning": ["...", "..."],
  "draft": "# Retries\n\nThe checkout client retries...",
  "stats": { "added": 3, "removed": 3 },
  "model": "gpt-4.1",
  "ms": 6120
}

Three fields matter most. quote is the passage Docsmith believes is wrong, taken verbatim from the page you sent — if it could not be located on the page, the finding would have been dropped before you saw it. draft is the complete rewritten page, ready to commit. verdict is current whenever nothing needed changing, in which case there is no draft and no diff.

5. Decide what happens to drafts

Three options, set per repository:

• Review queue (default) — drafts wait in the dashboard. Approve, edit then approve, or reject with a reason.
• Pull request (Team and above) — approved drafts open a PR on a branch named after the commit that caused them. Docsmith opens and updates; it never merges.
• Webhook — you receive sync.completed and do whatever you like with it. See webhooks.

6. Tune it in week two

Most teams change two settings once they have seen a week of output.

• Confidence floor. Findings below this are not surfaced. The default is 0.6; raising it to 0.75 is the single most effective way to quieten the queue.
• Ignore rules. Exclude a glob. Changelogs and archived version directories are excluded by default; add anything generated.

Troubleshooting

Next

• GitHub app — permissions and path scoping
• API reference — every endpoint, error and rate limit
• Webhooks — events and signature verification
• How the AI works — routing, verification and the evaluation numbers