/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Get Annotation Coverage

Get Annotation Coverage

How much of your API surface is documented, and the latest @stx drift alerts.

GET/v1/projects/{projectId}/analytics/annotation-coverageTry it
Session token

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.

Note

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

NameDescription
projectId:stringpathRequired
The project ID.

Response Fields

NameDescription
data.coveragePercent:integer
documentedSymbols as a percentage of totalSymbols, rounded.
data.undocumented:array
Endpoints with no documentation: symbol ("METHOD /path"), file (the doc page path, or "" when there is none) and type ("endpoint").
data.driftAlerts:array

Issues from the newest drift report stored for this project, highest severity first, at most 100:

•
symbol — the code entity that drifted
•
file — path:line (just path when the line is unknown)
•
reason — what changed
•
detectedAt — when the report was submitted (every alert in a report shares it)
•
severity — error, warning or info
•
type — 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.

Note

Enforce a minimum coverage threshold in CI with stx check — see the CI/CD guide.

Submitting drift reports

POST/v1/annotations/drift

Syntext 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.

NameDescription
current:object[]bodyRequired
Current source files, { path, content }, 1–500.
previous:object[]bodyRequired
The same files at the previous version, { path, content }, 1–500.
config:objectbody
strictness (strict, moderate — the default — or relaxed), ignorePatterns, ignoreInternal, requireAnnotations, checkExamples.
format:stringbody
json, text or github. text and github return a plain-text report.
Default"json"
projectId:stringbody
Optional project UUID. With it, you must be a member of the project's organization, the plan check uses that organization's plan, and the report is stored for the project. Without it, nothing is stored and the request is allowed when any organization you belong to is on Pro or higher.
bash
curl -X POST https://api.syntext.dev/v1/annotations/drift \
-H "Authorization: Bearer $SYNTEXT_JWT" \
-H "Content-Type: application/json" \
-d '{
"projectId": "3f6c1d2e-8a4b-4f7e-9c21-5b0d7e6a9f13",
"current": [{ "path": "src/routes/members.ts", "content": "..." }],
"previous": [{ "path": "src/routes/members.ts", "content": "..." }]
}'
json
{
"issues": [
{
"type": "signature-changed",
"severity": "error",
"file": "src/routes/members.ts",
"line": 88,
"entityName": "inviteMember",
"message": "Parameter count changed from 1 to 2"
}
],
"summary": { "total": 1, "errors": 1, "warnings": 0, "info": 0 },
"checkedFiles": 1,
"checkedEntities": 14,
"timestamp": "2026-11-08T09:12:44.000Z",
"stored": { "reportId": "b7d0f3a2-1c4e-4a9b-8e6f-2d5c7a1b9e30", "issues": 1 }
}

The 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

Statuserror.codeWhen
400validation_errorThe body failed validation, for example a projectId that is not a UUID. details.issues lists each problem
401unauthorizedMissing, invalid or expired session JWT, or an API key
402plan_requiredfeature: drift_detection, requiredTier: pro. With projectId, the project's organization is below Pro; without it, none of your organizations is on Pro
403forbiddenprojectId belongs to an organization you are not a member of
404not_foundprojectId does not exist or has been deleted

Error Responses

402 Payment Required

The workspace is below Pro:

json
{
"error": {
"code": "plan_required",
"message": "@stx annotation scanning requires the Pro plan or higher. This workspace is on Starter.",
"details": {
"feature": "annotations",
"requiredTier": "pro",
"currentTier": "starter",
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}

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.

Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/analytics/annotation-coverage \
-H "Authorization: Bearer $SYNTEXT_JWT"
Responseapplication/json
200OK
{
"data": {
"coveragePercent": 76,
"totalSymbols": 248,
"documentedSymbols": 189,
"undocumented": [
{ "symbol": "POST /v1/members/invite", "file": "", "type": "endpoint" }
],
"driftAlerts": [
{
"symbol": "inviteMember",
"file": "src/routes/members.ts:88",
"reason": "Parameter count changed from 1 to 2",
"detectedAt": "2026-11-08T09:12:44.000Z",
"severity": "error",
"type": "signature-changed"
}
]
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext