/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Run Project Lint

Run Project Lint

Lint every doc page in the project's repository against its style rules and glossary.

POST/v1/projects/{projectId}/lint-runsTry it
Session token

Lint every page of the project at once. The run reads each .md and .mdx file under the docs folder at the head of the project's branch, checks it against the project's style rules and glossary, and saves the findings. The whole run happens inside the request, and the response is the finished run.

Note

Requires the admin or owner role, signed in with a session JWT — API keys are refused with 401. A member gets 403 forbidden with details.requiredRole: "admin" and details.currentRole — see Role errors. You must belong to the organization that owns {projectId}. Available on every plan.

It reads every page from the connected repository — through a GitHub App installation that belongs to its workspace — or, for a project written in Syntext, from Syntext.

This is not POST /lint, which lints one page's content that you send in the body.

How a run works

•
Files matching the linter's ignoredPaths are skipped. At most 500 pages are linted per run, 8 at a time; the rest are counted in pagesSkipped. A page that cannot be read is skipped too.
•
The findings are saved to GET /lint-results and replace the previous run's findings. Results you saved for a single page through POST /lint are kept.
•
One run per project at a time. A run that has not finished after 15 minutes is treated as failed, so it cannot block the next one.

Path Parameters

NameDescription
projectId:stringpathRequired
The project ID.

Request Body

None.

Response — 201 Created

The same shape as Get Latest Lint Run:

Error Responses

400 Bad Request

bad_request — the project has no repository, an invalid repository URL, or no GitHub App installation.

401 Unauthorized

No session JWT, an expired one, or an API key.

403 Forbidden

forbidden — your role is below admin, or you are not a member of the organization that owns the project.

installation_not_owned — the project's GitHub App installation is not connected to its workspace. Reconnect the repository from the dashboard.

404 Not Found

not_found — the project does not exist or was deleted.

409 Conflict

lint_run_in_progress — a run is already going for this project. details.runId names it. Wait for it, then call Get Latest Lint Run.

json
{
"error": {
"code": "lint_run_in_progress",
"message": "A lint run is already in progress for this project.",
"details": {
"runId": "e4a1c9b2-7d3f-4b6e-8a1c-2f9d0b3e4c5a",
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}

500 Internal Server Error

internal_error — the GitHub integration is temporarily unavailable.

502 Bad Gateway

lint_run_failed — the repository could not be read (or the findings could not be saved). The run is recorded as failed, and details.runId names it. The previous run's findings are left in place.

Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl -X POST https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/lint-runs \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Responseapplication/json
201Created
{
"data": {
"id": "e4a1c9b2-7d3f-4b6e-8a1c-2f9d0b3e4c5a",
"status": "completed",
"buildSha": "a3f9c21b7e04d5f6a7b8c9d0e1f2a3b4c5d6e7f8",
"pagesChecked": 142,
"pagesSkipped": 3,
"durationMs": 4200,
"createdAt": "2026-11-08T09:00:00.000Z",
"completedAt": "2026-11-08T09:00:04.200Z",
"errors": 3,
"warnings": 12,
"info": 5
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext