Frequently asked questions

DocSemantic is an API contract drift detection tool. It learns your API's real contract from live traffic — no OpenAPI spec required — and tells you exactly which consumers break when a response drifts from that contract, before you ship.

It ships as five surfaces over one engine: a CLI, an HTTP API, a GitHub Action, a public README badge, and an MCP server for AI agents. Anything you can do in the dashboard you can do from the CLI or by calling the API directly.

DocSemantic focuses strictly on structural schema drift detection. Behavioral analysis, self-hosting, and first-class GraphQL are not supported.

Three steps.

1. Detect drift from real traffic. Point DocSemantic at your live requests; it learns the real contract and catches the moment a response drifts from it.

2. Name exactly who breaks. It tracks who consumes the API, so it names the specific app, service, or team that breaks when a field changes — not just that "something changed".

3. Fix it with one PR. Get the change explained in plain English and open a pull request that reconciles your contract with reality. Auto-fix PRs are in early access and cover structural schema drift only.

Optic was archived in early 2026 and is no longer maintained. DocSemantic keeps what Optic got right — learning your contract from real traffic and blocking breaking changes in CI — and adds plain-English AI explanations of each change, naming which consumer actually breaks, auto-fix pull requests, continuous production monitoring, and active maintenance.

You can bring your existing optic.yml and keep your CI gate. The import wizard reads both the v2 capture block and the legacy apis map.

No. DocSemantic learns your contract from live traffic, so you can start with zero specs. If you do have an OpenAPI document, or an optic.yml, you can import it to seed the contract — but it is optional, not a prerequisite.

Blast Radius is the answer to "who breaks if this ships?". Every other contract tool watches the API; DocSemantic also tracks who consumes it, so when a field changes it names the specific consumers affected and ranks them by share of real affected traffic.

That ranking is what lets you tell a harmless rename from a rollback. A consumer whose baseline is still too new to judge is reported as unverifiable rather than being assigned a confident severity.

About five to ten minutes for the common path: create an API key, add a few lines of middleware to your API, and deploy. Drift starts appearing as soon as real traffic flows.

Two things are faster still. The public README badge is a single image URL and needs no setup at all. The GitHub Action is a copy-paste workflow file from Settings, and needs no CLI install because it calls the API over HTTP.

Contract Health needs a little observed traffic before it becomes meaningful, so expect useful baselines within hours on a busy endpoint rather than instantly.

Usually not. The HTTP API, the GitHub Action, the README badge, and the MCP server all work without installing a package — they are HTTP endpoints you call or embed.

Two exceptions. To stream traffic you add a small middleware to your own API, which is a few lines of your existing framework's code, not a dependency you install from us. And the CLI is not published to npm yet, so you run it from a git clone with node cli/bin/docsemantic.js. It is zero-dependency and needs Node 18 or newer.

Yes, with any CI system. There is a ready-made GitHub Action you can copy from Settings, which posts a pull-request comment naming the consumers that break and can block the merge on consumer impact.

For anything that is not GitHub Actions — GitLab CI, CircleCI, Jenkins, Buildkite — call the read-only check endpoint with curl, or run docsemantic check. Both signal pass/fail the way CI already expects: HTTP 200 and exit 0 when the contract is compliant, HTTP 422 and exit 1 when drift is found. There is no output to parse.

Only partially, and it is worth being straight about the limitation. DocSemantic models drift per HTTP method and path against JSON responses. GraphQL sends nearly every operation as a POST to one endpoint, so all of your operations collapse into a single path and per-operation drift is not modelled.

You can still send GraphQL responses as traffic and get type and shape drift on the response body, and privacy mode works normally. What you will not get is per-query or per-resolver attribution. First-class GraphQL support is not shipped, so if that is your main use case, treat DocSemantic as a partial fit today.

Yes, with one caveat: there is no built-in environment switcher, so you separate environments yourself.

The clean pattern is one API key per environment, and a distinct consumer name per environment when you declare consumer expectations — for example web-app-staging versus web-app-prod. That keeps staging noise out of your production baselines, because a baseline is learned from the traffic sent under that key.

Do not send staging and production traffic under the same key expecting them to be separated automatically. They will be learned as one contract.

The report is flat, self-describing JSON, built so a CI script or an AI agent can reason over it without extra context.

At the top: schemaVersion, and a driftScope of "structural/schema" — a deliberate statement that this is type and shape drift, not behavioral analysis. Then a summary with total samples, violating samples, compliance rate, and how many endpoints have open drift.

Then the detail: a list of endpoints, each with the fields that violated, and for each field the expected type, the actual type, and an occurrence count. Read occurrence count first. A field that flipped type in 4,000 of 4,000 samples is a real change; one that flipped in 3 of 4,000 is usually a bad upstream response or a rare code path.

It lets you do drift detection without sending us your payloads — for teams where that is simply not allowed, like banks, health, and fintech.

Instead of posting the response body, you fingerprint the response inside your own infrastructure and send only its shape: a map of field path to JSON type, like {"id":"number","email":"string","profile.displayName":"string"}. Same endpoint, same key — you include a "fingerprint" field instead of "response".

DocSemantic never receives and never stores a single value: no email, no token, no amount. Type flips and dropped required fields are still caught, because types are all structural drift detection ever needed. Blast Radius still works too, because consumer expectations are declarative.

It depends on your plan, and the same window is applied consistently across the dashboard, the report endpoint, and the MCP tools.

Free reads the last 7 days. Developer reads the last 30 days. Team reads the last 90 days and adds trends. Enterprise has no history limit.

This is a read window, not a delete policy: on a shorter window older samples are simply not readable, and upgrading widens the window again.

Create one under Settings, in the API keys section. Keys start with the prefix dsk_live_.

The raw key is shown exactly once, at creation, and is never stored — we keep only a SHA-256 hash plus a short display prefix so you can recognise it in a list. Copy it into your secret manager immediately; if you lose it, you create a new key rather than recovering the old one.

The same key authenticates everything: the traffic endpoint, the report and check endpoints, the GitHub Action, the CLI, and the MCP server.

It depends which mode you run, and you control that.

In the default mode you send response bodies, so treat it like any other observability vendor: sample responsibly and avoid sending fields you would not want stored.

In privacy mode you send only field-path-to-type shapes, so no values ever leave your infrastructure. That is the mode to use if you handle regulated data.

Either way, API keys are stored only as a SHA-256 hash, uploaded specs are served through an authenticated route rather than a public URL, and third-party destination secrets are encrypted with AES-256-GCM.

Not today. DocSemantic is a hosted SaaS. The source is available for reference and contribution, but it is not licensed for self-run production deployments.

If self-hosting is a hard requirement for you — usually compliance or an air-gapped network — get in touch and we will talk it through.

Any language or framework that can make an HTTP POST, because that is the whole integration surface — you send JSON to an endpoint.

Official middleware snippets are provided for Express, Next.js, and FastAPI. For anything else, the pattern is about ten lines: after your handler produces a response, fire a sample at the traffic endpoint. Send it fire-and-forget so telemetry can never block or break a user request; the snippets already do this, and failures are swallowed by design.

DocSemantic runs a Model Context Protocol server, so IDE and AI agents like Cursor, Claude, and Copilot can query your contract drift the same way CI does. Point the agent at https://docsemantic.com/api/mcp over streamable HTTP and authenticate with the same dsk_live_ key.

Three tools are exposed. check_contract_drift runs a pass/fail structural drift gate across every monitored spec. impact_report answers "who breaks if this ships?" and returns at-risk consumers plus a ready-to-post Markdown summary. drift_report returns current structural drift as flat JSON, and takes an optional limit between 1 and 500 for how many recent samples to analyze.

All three respect your plan's history window, exactly like the dashboard.

Yes — that is why it exists as a no-auth endpoint. Embed https://docsemantic.com/api/badge as an image, and add ?label=API to change the left-hand text.

The badge exposes only an aggregate compliance state. It never reveals endpoint paths, payloads, field names, or counts. It is cached at the CDN for about five minutes, and it always renders a valid badge — falling back to an "unknown" state — so your README never breaks because of a request to us.

A 401 means the key was missing or not recognised. Work through these in order.

Check the header format. It must be Authorization: Bearer dsk_live_... — a bare key with no Bearer prefix is the most common cause.

Check the key is whole. Keys are long and get truncated by copy-paste, and shell quoting can silently drop characters.

Check it was not deleted. A deleted key stops working immediately and cannot be restored.

Check which environment you are in. Pointing at production with a key created in another workspace, or reading a stale DOCSEMANTIC_KEY from a cached CI secret, both present as 401.

If the CLI is involved, run docsemantic status to see which credentials it actually resolved — flags win over environment variables, which win over the saved config file.

Almost always one of three things.

No samples yet. Compliance is computed from observed traffic, so a brand-new project with no traffic has nothing to be compliant with. Confirm your middleware is actually firing — a single curl POST to the traffic endpoint returning 202 proves the key and URL are right.

Every sample is violating. If your documented contract disagrees with what the API really returns, compliance genuinely is 0%. Open the drift report; it will name the fields.

You are looking at a cached badge. It is cached at the CDN for about five minutes, so a fix will not appear instantly. Wait, then hard-refresh.

Also worth knowing: a low percentage renders red rather than green. That is the badge working, not a rendering bug.

Check the three limits first. The file must be 5 MB or smaller, the extension must be .json, .yaml, or .yml, and the content must actually parse.

Malformed YAML is the usual culprit, and tabs are the usual cause of malformed YAML — the spec forbids them for indentation. A JSON file exported with a trailing comma will also fail to parse.

If the file parses locally but still fails, try it as JSON instead of YAML to isolate whether the problem is the format or the content.

A spec that cannot be parsed is rejected at upload with the reason, rather than being half-ingested — so a broken file never becomes a broken baseline.

A spec that parses but is incomplete is treated as the contract you declared, which matters: if your spec omits a field your API really returns, that field is reported as undocumented drift. That is usually the correct and useful answer, not a false positive.

You do not have to fix a spec by hand. Once drift is detected, auto-fix can open a pull request that patches the spec to match reality. It applies type changes, added fields, and nullability directly, and anything ambiguous is preserved as an x-docsemantic-drift annotation rather than guessed at. Auto-fix PRs are in early access.

Check occurrence count first. A field flagged in 3 of 4,000 samples is usually a genuine rare code path or an upstream error response — real, but not what you thought you were looking at.

If a consumer is listed as unverifiable, that is deliberate: the endpoint's baseline is still too new to judge, and DocSemantic waits for more traffic instead of guessing a severity. It resolves itself as traffic accumulates.

If a consumer looks wrong, re-read its declared "expects" map. Blast Radius compares what you declared a consumer reads against the learned response shape, so a stale expects map produces a confidently wrong answer.

Remember the scope, too: this is structural and schema drift. Behavioral and semantic analysis are not shipped, so a value that is legal but wrong is out of scope by design.

If it still looks wrong, copy your report output directly into the in-app AI assistant. The AI can inspect your raw payload shape and highlight baseline mismatches instantly.

Rotate rather than reset, and do it in this order to avoid a gap in coverage.

Create the new key in Settings. Deploy it everywhere the old one is used — application middleware, CI secrets, the CLI config at ~/.docsemantic/config.json, and any connected agent. Then delete the old key.

Deleting takes effect immediately, so anything still using the old key starts getting 401s. And because we only ever store a hash, a lost key cannot be recovered — creating a new one is the only path.

Yes — the Free plan, 7-day drift history, no card required. It includes 100,000 API requests a month, up to 2 monitored APIs, one developer seat, the CLI, the GitHub Action, the public drift badge, and local MCP server access.

New signups also get a 14-day trial with unlimited traffic, so you can run realistic staging tests before the 100,000/month cap applies. The viral surfaces — CLI, GitHub Action, and public badge — are on every plan.

Developer is $29 a month: everything in Free, 1,000,000 API requests a month, up to 3 seats, up to 5 monitored APIs, 30-day drift history, Slack and email alerts, and single-user MCP context. It is the step up once a solo API starts heading to production.

Team is $89 a month and is where teams and production integrations live: everything in Developer, 10,000,000 API requests a month, up to 10 seats, unlimited monitored APIs, 90-day history with trends, drift destinations for Slack, Datadog and Sentry, the PR Auto-Fix bot and the "who breaks" report, and shared team MCP context.

It exists to fill the gap between Developer and Enterprise, so a growing team is not forced to jump straight to the top tier.

Enterprise starts at $299 a month: everything in Team, custom traffic volume, unlimited seats, unlimited drift history, SAML SSO and audit logs, and priority support with an SLA.

The published tiers check out self-serve through the same Stripe flow; custom traffic volume above the Team cap is arranged through the contact form.

Each plan includes a monthly request allowance: 100,000 on Free, 1,000,000 on Developer, and 10,000,000 on Team. Enterprise is custom. The cap protects the database and compute behind your drift history, which is what grows with the volume you send.

New signups get a 14-day unlimited-traffic trial so you can load-test a real integration before the cap applies. If you regularly approach your plan's allowance, that is the signal to move up a tier rather than being hit with a per-request overage bill.

No. The monthly plan price is the whole bill: no per-request overage charges, no per-endpoint pricing, no charge for the CLI, the GitHub Action, the badge, or the MCP server. If you exceed your plan's monthly request allowance you move up a tier — there is no surprise usage invoice.

The two things worth naming so they are not surprises: paid plans are billed monthly in advance through Stripe until you cancel, and teammates are capped by plan rather than billed per seat — so exceeding your seat count means upgrading, not an automatic extra charge.

Yes, in both directions, and it is self-serve.

To move up, check out the new plan from the Billing page; when the new subscription becomes active, the previous one is cancelled automatically so you are never paying for both. Your entitlement is reconciled from the live Stripe subscription, so it stays correct even if a billing webhook is delayed.

To move down, cancel — you keep paid features until the end of the period you already paid for, then land on the Free plan.

Yes, from the Billing page, with no retention call and no cancellation fee. You keep paid features until the end of the current billing period rather than losing them the moment you click.

Your subscription stays active until the end of the period you have already paid for. After that you move to the Free plan automatically.

What changes: your readable history window narrows to 7 days, seats drop to one, your monthly request allowance returns to 100,000, and paid integrations like drift destinations and scheduled alerts stop.

What does not change: your account, specs, keys, and baselines are not deleted. Older drift samples become unreadable while you are on the free window, not erased — resubscribing widens the window again. If you want your data actually deleted, ask and we will delete it.

Not as a formal programme today, so there is no code to enter.

In practice the Free plan is likely all a student needs: 100,000 requests a month, up to 2 monitored APIs, the CLI, the GitHub Action, and the public badge, at no cost. If you are teaching a course or running a student project that needs more than that, ask through the contact form at /contact.

The Terms state that fees are non-refundable except where refunds are required by law, so there is no general refund window — that is the honest answer rather than a maybe.

Two practical notes. Cancelling keeps your paid features until the end of the period you already paid for, so cancelling early is not lost money. And if you were charged in error — a duplicate charge, or a plan you did not intend — report it through the contact form at /contact and pick the billing topic; that is a billing mistake, not a refund request, and it gets fixed.

Card details are held by Stripe, never by DocSemantic — we store only a customer reference, so there is no card form in this app to edit.

Manage your subscription from the Billing page. If you need to change the card on an active subscription and do not see an option for it, say so through the contact form at /contact and it will be sorted out. Never send card details in a message — a secure Stripe link will be sent to you instead.

Invite them by email from the Team page. When someone signs up with an invited address, the role you assigned is applied automatically, so there is no second approval step.

Roles are owner, admin, member, and viewer; the first account on a workspace becomes owner. Seats are capped by plan: one on Free, up to 3 on Developer, up to 10 on Team, unlimited on Enterprise.

Not self-serve today. Moving a subscription between workspaces or to a different billing owner is a manual operation.

Use the contact form at /contact, give the email address that owns the subscription as your contact address, and say where it should move. Naming the owning address matters — it is how the request is verified, so a transfer cannot be requested by someone else. Do not cancel first: cancelling loses the remainder of the period you paid for, and the transfer does not need it.

Yes, in transit and at rest.

In transit, everything is HTTPS/TLS — the API, the dashboard, the CLI, and the MCP server. In addition, specific secrets get application-level encryption: third-party destination credentials, like a Sentry DSN, a Datadog key, or a webhook URL, are encrypted with AES-256-GCM and only a non-sensitive preview is ever displayed. GitHub tokens for auto-fix PRs are stored encrypted and never shown again after you save them.

API keys are not encrypted, they are hashed — we store a SHA-256 hash and a short prefix, so we cannot reveal your key even to you.

At rest, database and blob storage are encrypted by the underlying providers, Neon and Vercel Blob.

The strongest option is still privacy mode: data you never send cannot be leaked.

Access is restricted by design, not by policy alone. Administrative access is tightly limited, and every data path is locked down at the infrastructure level: uploaded specs are served through an authenticated route instead of public URLs, destination secrets are encrypted so they are not readable by browsing the database, and API keys are stored hashed so they cannot be read at all.

Your data is not used to train models. If you need a stronger guarantee than trust, privacy mode removes the question entirely by never sending values off your infrastructure.

Yes. You can delete your account, which removes your account data along with the specs, keys, and traffic samples attached to it.

Deletion is permanent and is not the same as cancelling — cancelling narrows what you can read but keeps your data. If you want specific specs or samples removed rather than the whole account, or you want written confirmation once it is done, use the contact form at /contact and pick the privacy topic.

We do not sell personal data and we do not share it for advertising.

We do use a small number of subprocessors to run the service, which is different from sharing: Vercel for hosting, Neon for the Postgres database, Vercel Blob for uploaded specs, Stripe for payments, and Resend for transactional email. AI features send the relevant drift context to a model provider to generate explanations. Each processes data to deliver the service, not for their own purposes.

If you configure drift destinations, you are deliberately sending your drift reports to those tools — Slack, Sentry, Datadog, or your own webhook. That is your integration, under your control.

Privacy is a core design principle, not an afterthought. All data is encrypted in transit and at rest, API keys are hashed, and third-party secrets are AES-256-GCM encrypted.

The strongest protection is that we are built to never see your sensitive values in the first place. Privacy mode sends only the shape of your responses — field names and types — never the actual values, so no customer data leaves your infrastructure.

We never use your data to train AI models. If your procurement process needs security documentation, request it through the contact form at /contact.

There is no standard counter-signed DPA published today. If you need one, ask through the contact form at /contact and it can be handled on request.

Two things often make the question moot. In privacy mode no personal data reaches us at all, so there is nothing to process. And in default mode, whether personal data is involved depends entirely on which responses you choose to sample — sampling non-personal endpoints keeps you out of scope.

On Vercel and Neon infrastructure. Uploaded specs live in Vercel Blob and are served only through an authenticated route; drift samples and account data live in Neon Postgres.

If you have a specific regional residency requirement, raise it before you rely on the service — use the contact form at /contact.

DocSemantic is built to align with GDPR. Data-subject rights are supported, including access, deletion, and export; personal data is not sold; and the subprocessors used to run the service are listed in the privacy policy.

For requests or questions, use the contact form at /contact and pick the privacy topic. As above, privacy mode is the cleanest path to minimisation: shapes instead of values means the personal data never leaves your systems.

Technical support: All technical questions, framework integrations, and drift troubleshooting are strictly handled self-service via our in-app AI assistant and documentation. The AI has direct access to your schema context and will solve setup faster than manual email threads.

Account & legal inquiries: For enterprise sales, billing corrections, security disclosures, or data deletion requests, submit a ticket via the contact form at /contact.

Not yet. There is no hosted status page or uptime history to link you to, and pretending otherwise would just cost you time during an incident.

What you can use in the meantime: the public badge endpoint at /api/badge needs no authentication and always responds, so it is a quick liveness check. The check endpoint returns 503 specifically when the DocSemantic backend is unreachable, which distinguishes "we are down" from "your contract is failing" — a 422 is drift, not an outage.

No — this is the same gap as the status page, and it is not built yet.

For your own APIs, the dashboard does show contract health and live traffic continuously, which is the monitoring DocSemantic is actually for. For the availability of DocSemantic itself, use the badge endpoint as a liveness probe and treat a 503 from the check endpoint as our problem rather than yours.

There is no changelog page on the site yet. The source of truth is the GitHub repository — commits and releases at github.com/LingodocApi/docsemantic.

Two changes do announce themselves in the product: the report endpoint carries a schemaVersion so an integration can detect a format change, and driftScope states the analysis scope explicitly, so a future expansion beyond structural drift will be visible in the payload rather than silent.