Get Annotation Coverage
How much of your API surface is documented, and the latest @stx drift alerts.
Returns how much of the project's API surface is documented, which endpoints are not, and the drift alerts from the most recent @stx drift report submitted for the project.
Session JWT and org membership required. Any role can read it — an API key gets 401, a non-member 403.
Pro plan or higher. Lower plans get 402 plan_required with feature: annotations — see Plan errors. driftAlerts also needs drift_detection (Pro).
Path Parameters
projectIdResponse Fields
data.coveragePercentdocumentedSymbols as a percentage of totalSymbols, rounded.data.undocumentedsymbol ("METHOD /path"), file (the doc page path, or "" when there is none) and type ("endpoint").data.driftAlertsIssues from the newest drift report stored for this project, highest severity first, at most 100:
symbol — the code entity that driftedfile — path:line (just path when the line is unknown)reason — what changeddetectedAt — when the report was submitted (every alert in a report shares it)severity — error, warning or infotype — e.g. signature-changed, missing-annotation, stale-example, param-mismatch[] until a report has been stored with POST /v1/annotations/drift and a projectId, when the workspace's plan does not include drift detection, or when the alerts cannot be read.
Enforce a minimum coverage threshold in CI with stx check — see the CI/CD guide.
Submitting drift reports
/v1/annotations/driftSyntext does not clone your repository to look for drift. Your CI (or any script with a session JWT) sends the current and previous versions of the source files, and the endpoint compares their @stx annotations and signatures. Add projectId to store the result for this project, so its issues show up as driftAlerts above.
current{ path, content }, 1–500.previous{ path, content }, 1–500.configstrictness (strict, moderate — the default — or relaxed), ignorePatterns, ignoreInternal, requireAnnotations, checkExamples.formatjson, text or github. text and github return a plain-text report."json"projectIdThe response is not wrapped in data. stored appears only when you sent projectId and asked for json: reportId is the stored report and issues how many issues were kept. A report keeps at most 500 issues, highest severity first. With format text or github the report is still stored, but the plain-text response does not mention it.
Errors
| Status | error.code | When |
|---|---|---|
| 400 | validation_error | The body failed validation, for example a projectId that is not a UUID. details.issues lists each problem |
| 401 | unauthorized | Missing, invalid or expired session JWT, or an API key |
| 402 | plan_required | feature: drift_detection, requiredTier: pro. With projectId, the project's organization is below Pro; without it, none of your organizations is on Pro |
| 403 | forbidden | projectId belongs to an organization you are not a member of |
| 404 | not_found | projectId does not exist or has been deleted |
Error Responses
402 Payment Required
The workspace is below Pro:
401 Unauthorized
Missing, invalid or expired session JWT, or an API key.
403 Forbidden
You are not a member of the organization that owns the project.
404 Not Found
The project does not exist or has been deleted.