Documentation

DocSemantic is an AI-native API contract drift detection tool. It reads your API documentation and the contract you declare, extracts enforceable rules from it, and checks live API payloads against those rules — surfacing violations when your real API behavior drifts from what the docs promise. It is positioned as the modern replacement for Optic.

DocSemantic has two product surfaces that wrap the same API: a command-line interface (the docsemantic CLI, which was the original product) and an HTTP API. Anything you can do from the dashboard you can also do from the CLI or by calling the API directly with a dsk_live_ key.

Core terminology: "rules extracted" are the enforceable checks pulled from your documented contract; "payload violations" are live samples that broke a rule; "specs analyzed" is how many contract files have been processed; "compliance" is the percentage of samples that matched the contract.

DocSemantic works in three stages.

1. Upload a spec. Add a JSON, YAML, or OpenAPI file (up to 5 MB). Each upload is stored privately in Blob storage and queued for analysis. Private specs are served through an authenticated route and never exposed publicly.

2. Detect drift. DocSemantic compares your documented contract against live behavior and flags schema drift, type changes, and undocumented fields.

3. Auto-heal. Review the alerts and open a pull request that patches your OpenAPI spec to match reality — available from the header. (Auto-fix PRs are in early access; see the Auto-fix PRs entry.)

To stream live traffic, first create an API key under Settings -> API keys (keys start with dsk_live_). Set DOCSEMANTIC_URL and DOCSEMANTIC_KEY in your environment, then add a small middleware to your API that samples responses and POSTs them to {DOCSEMANTIC_URL}/api/v1/traffic with an Authorization: Bearer dsk_live_... header.

Samples are sent fire-and-forget, so they never block or break a request — telemetry failures are swallowed. A traffic sample needs at least a method and path; include the status and response to get real drift detection against the documented contract. Drift then lands on the Live Traffic dashboard.

Official middleware snippets are provided for Express, Next.js, and FastAPI. You can smoke-test your key and endpoint with a single curl POST to /api/v1/traffic — a 202 response means it is working.

Privacy mode is for teams that cannot send production payloads to a third party (banks, health, fintech). Instead of sending the response body, you fingerprint the response inside your own infrastructure and send only its shape: a map of field path to JSON type (for example, {"id":"number","email":"string","profile.displayName":"string"}).

You send this on the same endpoint with the same key — just include a "fingerprint" field instead of "response". DocSemantic learns the baseline and detects type and shape drift from the fingerprint alone. It never receives, and never stores, a single value like an email, token, or amount. Type flips and dropped required fields are still caught, because types are all drift detection ever needed. Consumer drift ("who breaks") also works in this mode because the consumer and expects fields are declarative too.

The docsemantic CLI wraps the same API for terminal and CI use. It ships zero-dependency and runs on Node 18+. It is not published to npm yet, so you run it from a clone: "git clone https://github.com/LingodocApi/docsemantic.git", then "node cli/bin/docsemantic.js <command>". Aliasing it with 'alias docsemantic="node /path/to/docsemantic/cli/bin/docsemantic.js"' lets you use the shorter "docsemantic <command>" form shown below. For CI, the bundled composite action (LingodocApi/docsemantic/github-action@main) needs no CLI at all because it calls the API over HTTP.

Configure a key once with "docsemantic init" (saved to ~/.docsemantic/config.json), or non-interactively with "docsemantic init --url ... --key ...". Credentials resolve from flags first, then the DOCSEMANTIC_URL / DOCSEMANTIC_KEY environment variables, then the saved config file; run "docsemantic status" to see what is resolved.

Everyday commands: "docsemantic report" shows current drift as a table (add --json to pipe machine-readable output into jq or an agent); "docsemantic send" pushes a sample from the terminal; "docsemantic watch --interval 5" live-polls the report while debugging a deploy; and "docsemantic check" exits non-zero when drift is found so a breaking change fails the build.

When drift is detected, DocSemantic can open a pull request that patches your OpenAPI spec to match what your API actually returns, so your contract stops lying to consumers. This feature is in private early access — request access and it is enabled per workspace.

The patch is deterministic: type changes, added fields, and nullability are applied directly to the schema, and anything ambiguous is preserved as an x-docsemantic-drift annotation rather than guessed. Access is scoped: you provide a fine-grained GitHub token with Contents and Pull requests read/write on the target repo; it is stored encrypted and never shown again. Scope today is structural / schema drift only — behavioral and semantic analysis are on the roadmap and not claimed.

You can read the current drift state as flat, self-describing JSON from GET /api/v1/report, authenticated with the same dsk_live_ key. It is built for CI scripts and IDE/MCP agents such as Cursor, Claude, and Copilot: every field is named and documented so a model can reason over it without extra context.

The report includes a schemaVersion, a driftScope of "structural/schema", a summary (total samples, violating samples, compliance rate, open endpoints with drift), and a list of endpoints each with their violating fields (field name, expected type, actual type, and occurrence count).

DocSemantic can push its drift and "who breaks if this ships" report into the tools your team already watches. Add destinations under Settings -> Drift destinations; provider secrets (DSN, API key, or webhook URL) are stored AES-256-GCM encrypted and only a non-sensitive preview is shown.

Supported destination kinds are Sentry (creates an issue), Datadog (creates an event you can alert on), Slack (posts a message), and a generic signed webhook (receives the full self-describing report). Trigger a broadcast to every enabled destination by POSTing to /api/v1/publish; the response reports how many deliveries succeeded and failed.

DocSemantic runs a Model Context Protocol (MCP) server so IDE and AI agents such as Cursor, Claude, and Copilot can query your API contract drift the same way CI does. Connect an agent to https://docsemantic.com/api/mcp over streamable HTTP (a legacy SSE endpoint at /api/sse is also available), authenticating with the same dsk_live_ API key used by the REST API.

The server exposes three tools, each a thin wrapper over the same functions behind the public v1 REST API: check_contract_drift runs a pass/fail structural drift gate across every monitored spec; impact_report answers "who breaks if this ships?" and returns the at-risk consumers plus a ready-to-post Markdown summary; and drift_report returns the current structural drift as flat, self-describing JSON with per-endpoint expected-vs-actual field violations. drift_report accepts an optional limit (1–500, default 200) for how many recent samples to analyze, and respects your tier's readable history window.

DocSemantic serves a public, no-auth SVG badge for your README, like a coverage badge. Embed https://docsemantic.com/api/badge as an image; add ?label=API to customize the left-hand label. The badge exposes only an aggregate contract-compliance state — never endpoint paths, payloads, or counts — so it is safe on a public README. It is cached at the CDN for about five minutes and always renders a valid badge (falling back to an "unknown" state) so your README never breaks on a request to DocSemantic.

DocSemantic publishes a ready-to-import Postman Collection (v2.1) covering the public API. Download it without authentication from https://docsemantic.com/api/postman; it ships with empty credential variables you fill in after importing. By default the collection's requests point back at this DocSemantic instance's origin, and you can override that with a ?baseUrl= query parameter.

DocSemantic ships a GitHub Action that fails pull requests on drift and can comment which consumers break if the change ships. Grab the ready-made workflow from Settings -> CI/CD. It calls the read-only /api/v1/check endpoint and exits non-zero when violations are found, so a breaking change never reaches production undocumented.

The action accepts an api-key input, a comment-impact option (post a PR comment listing which consumers break), and a fail-on-impact option (set true to block the merge on consumer impact, not just raw drift).

The impact endpoint answers "who breaks if this ships?" by analyzing current drift against the consumer expectations DocSemantic has learned. Call GET or POST /api/v1/impact with your dsk_live_ key. It returns a summary, the list of consumers at risk, and a ready-to-post Markdown report. The HTTP status is meaningful: 200 means no consumer breaks and it is safe to ship, while 422 means at least one consumer would break and a pipeline should fail.

The DocSemantic GitHub Action uses this endpoint to post the Markdown as a pull-request comment and, when fail-on-impact is enabled, to block the merge on consumer impact rather than raw drift alone.

Beyond on-demand checks, DocSemantic runs a scheduled drift check daily via Vercel Cron. That endpoint fails closed: it requires a CRON_SECRET and refuses to run (returning 503/401) if the secret is missing or wrong, so it can never be triggered by an anonymous caller.

For CI, the read-only check endpoint (GET or POST /api/v1/check, authenticated with a dsk_live_ key) returns 200 when the contract is compliant so the pipeline passes, 422 when drift is detected so the pipeline fails, 401 for a missing or invalid key, and 503 if the DocSemantic backend is unreachable. Public API endpoints are rate limited per key, and every response includes standard rate-limit headers.

Frontend/backend drift catches the drift that actually breaks apps: a client reading a field the API quietly stopped returning, or a field that now comes back as a different type. You declare what a consumer reads by adding two optional fields to any traffic sample: "consumer" (a stable name for the caller, such as web-app, ios, or partner-x) and "expects" (a map of the fields it reads to the JSON type it expects).

DocSemantic compares those declared expectations against the response shape it has already learned from real traffic and classifies each field. Broken: the backend never returns the field (or returns it almost never), or the type disagrees with what the consumer expects. At risk: right type, but the field is only returned intermittently. Unverifiable: the endpoint's baseline is still too new to judge, so DocSemantic waits for more traffic rather than guessing. Results appear on the Frontend/Backend Drift page.

The Contracts page is the consolidated home for your API contracts, which DocSemantic learns from real traffic. It presents one dataset through three lenses (tabs): Live traffic is the raw compliant/drifting sample feed as it arrives; Baselines is the "normal" response shape DocSemantic has learned for each endpoint; and Contract Health is a confidence score per endpoint that compounds as more requests are observed. The older standalone Baselines and Contract Health pages now redirect here, so existing links keep working.

If you are moving off Optic, the "Import from Optic" wizard reads your optic.yml — both the v2 capture block and the legacy apis map — and registers each referenced or pasted OpenAPI spec for monitoring. Specs it cannot fetch automatically are listed with a one-step manual upload path, so nothing is dropped silently.

DocSemantic accepts .json files (OpenAPI / Swagger definitions and JSON schemas) and .yaml / .yml files (OpenAPI specs and documentation front-matter). Uploaded files are forwarded to the DocSemantic API for analysis and are never exposed publicly; private specs are served through an authenticated route.

API keys are created under Settings -> API keys and are used by the CI/CD GitHub Action and any direct API call to authenticate against the public endpoints (for example /api/v1/traffic, /api/v1/report, /api/v1/check, /api/v1/publish). Keys start with the prefix dsk_live_. Only a SHA-256 hash of the key plus a short display prefix is stored — the raw key is shown once at creation and never persisted, so store it securely.

DocSemantic has four tiers: Free, Developer, Team, and Enterprise. Everyone starts on the Free tier. Paid tiers are backed by real Stripe subscriptions, managed from the Billing page where you can subscribe, confirm, manage, or cancel. Your entitlement is reconciled from the live Stripe subscription, so it stays correct even if a billing webhook is delayed.

Each tier includes a monthly request allowance — 100,000 on Free, 1,000,000 on Developer, 10,000,000 on Team, custom on Enterprise — alongside its seats, monitored-API count, and drift-history window. New signups get a 14-day unlimited-traffic trial before the Free cap applies.

Your tier also controls how far back drift reports and dashboards can read: higher tiers get a longer readable history window, while lower tiers see a more recent slice of traffic. The same history window is applied consistently across the dashboard, the REST report endpoint, and the MCP tools.

The in-app AI assistant is the primary support channel for DocSemantic, and it is available on every plan including the free plan. It answers from the product documentation and the public FAQ, and it can see the signed-in user's own dashboard context.

The public FAQ at /faq is the second channel and needs no account.

The third channel is the contact form at /contact. There is no public support email address — the form is the only way to reach the team, and it goes straight to them. Never give out an email address for support, and never invent a support@ or hello@ address; neither exists.

The form is reserved for what a chat cannot do: enterprise and procurement questions, security documentation and vulnerability reports, a data processing agreement on request, billing corrections, data deletion and GDPR requests, subscription transfers between teams, and self-hosting requirements. It asks for a topic so the request is routed correctly. For technical how-do-I questions, direct the user to the assistant or the FAQ rather than to the form.