Run syntax checks against a doc asset's source

POST

/assets/{id}/lint

• Local development behind nginx (port 8088 by default)

Dispatches to a language-aware syntax checker based on the asset’s file extension and returns a flat diagnostic list.

First cut ships three Go-native checkers (JSON / YAML / Markdown). For any other extension the response carries skipped: true so the UI can render “no linter configured for this language” instead of “0 issues”.

Future iterations slot in subprocess-based linters (py_compile, node --check, luac -p, shellcheck, …) behind the same shape; the client doesn’t need to know which producer generated a diagnostic — it just renders the line / col / severity / message.

Synchronous: every Go-native checker runs in single-digit milliseconds on a typical doc.

Authorizations

• cookieAuth
• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Responses

200

Lint result

object

linter

required

Producer name, or "none" when no linter is wired for the asset’s extension.

string

skipped

required

true when no linter ran (unsupported extension or empty source). The diagnostics array is omitted or empty in that case.

boolean

diagnostics

Array<object>

object

line

required

1-based line number.

integer

>= 1

col

required

1-based column.

integer

>= 1

end_line

integer

nullable >= 1

end_col

integer

nullable >= 1

severity

required

string

Allowed values: info warning error

message

required

string

source

required

The linter that produced this diagnostic (json / yaml / markdown for the first cut). Frontend renders it as a small badge next to each row.

string

401

Authentication required, missing, or invalid

object

error

required

Human-readable error summary

string

Example

the request could not be completed

Example

{
  "error": "authentication required: sign in and retry with a valid session or API token"
}

404

Resource not found

object

error

required

Human-readable error summary

string

Example

the request could not be completed