> ## Documentation Index > Fetch the complete documentation index at: https://docs.noetive.io/llms.txt > Use this file to discover all available pages before exploring further. # Lint and auto-complete a SemQL query > Validates a SemQL query and returns diagnostics (parse/validation errors) and auto-complete suggestions at the given cursor position. Always returns both diagnostics and completions in a single call. Requires `Content-Type: application/json`. ## OpenAPI ````yaml /api/public-api.yaml post /v1/lint openapi: 3.0.3 info: title: Noetive Semantik API version: 0.4.0 description: > Noetive Semantik is a managed semantic search and subscription service. Publish messages tagged with embedding vectors, query them with the SemQL query language, and subscribe to live match streams over Server-Sent Events. All request and response bodies are JSON. The `/v1/subscribe` endpoint accepts a JSON POST request and upgrades the response to an SSE stream of match events. ## Request decoding Every JSON endpoint decodes strictly. A request is rejected with `400 invalid_request` when the body is empty, is not valid JSON, **carries a field this specification does not define**, or carries trailing content after the first JSON value. Unknown fields are an error rather than being ignored, so a misspelled field name fails loudly instead of silently taking a default. ## SemQL query limits These bound the `query` field on `/v1/search`, `/v1/subscribe`, and `/v1/lint`. Search and subscribe reject an over-limit query with `400 invalid_request` while parsing it — before any anchor is embedded, so a rejected query is not billed for embedding. `/v1/lint` reports the same problems as diagnostics with `valid: false` and a `200`, which makes it the cheap way to check a generated query before sending it. | limit | value | | --- | --- | | anchors per query, across all clauses | 32 | | anchors in one list (`DIRECTION` toward, `ATTRACT`, `REPEL`) | 8 | | namespace names in `NAMESPACE` | 8 | | namespace names in the `NOT` exclusion list | 8 | | floats in one vector anchor | 4096 | | floats across all vector anchors in one query | 8192 | | anchor text plus namespace names, combined | 4 KB | | nodes per query (clauses plus boolean operators) | 64 | | operands per `AND` or `OR` | 16 | | parenthesis nesting depth | 128 | Value ranges: `WITHIN` in `[0, 1]`, `CONE` in `[0, π]` radians, `LIMIT` and `WINDOW` strictly positive. `WITHIN` and `TOP` are mutually exclusive on one clause. `LIMIT` is the exception to the reject rule — see `SearchRequest.limit`. ## Request correlation Every response — success or error — carries an `X-Request-Id` header with a server-assigned correlation token. Error response bodies repeat the same value in the `request_id` field so it survives client-side logging that strips headers. Quote `request_id` when contacting support; it pivots directly to the corresponding server log line. Inbound `X-Request-Id` headers from clients are ignored — the server assigns the value authoritatively to prevent log injection. When the request carries an `X-Amzn-Trace-Id` header, its `Root=` segment is used as the request id so upstream trace correlation works without translation. Otherwise a fresh server-side identifier is minted. ## Error codes Error responses carry a stable machine-readable `error` code, an optional human-readable `message`, the server-assigned `request_id`, and (for retryable failures) a `retry_after_ms` hint. Known codes: | code | meaning | | --- | --- | | `invalid_request` | request body failed validation | | `unauthorized` | missing or invalid bearer token | | `not_found` | no endpoint at the request path — check the base URL; do not retry | | `idempotency_key_conflict` | the `idempotency_key` is live from an earlier publish carrying different content; nothing was stored | | `unsupported_media_type` | `Content-Type` is not `application/json` | | `request_too_large` | request body exceeds the endpoint size limit | | `rate_limited` | per-client burst or rate limit exhausted | | `too_many_requests` | concurrency limit exhausted, or the namespace is at its concurrent-subscription cap | | `unavailable` | service temporarily unavailable; retry after `retry_after_ms` | | `namespace_unavailable` | namespace lookup is transiently unavailable; retry after `retry_after_ms` | | `namespace_disabled` | the namespace alias exists but has been administratively disabled | | `model_not_provisioned` | the namespace alias exists but has no entry for the requested (model, dimensions) combination | | `not_billable` | no active subscription on the account; resolve billing before retrying | | `metering_unavailable` | metered billing is transiently unavailable; retry with backoff | | `internal_error` | unexpected server error — quote `request_id` when contacting support | contact: name: Noetive Support url: https://noetive.io email: support@noetive.io license: name: Noetive Commercial url: https://noetive.io/terms servers: - url: https://semantik.noetive.io description: Global Semantik endpoint security: - bearerAuth: [] tags: - name: Search description: Run a SemQL query against published messages. - name: Publish description: Ingest messages with embedding vectors. - name: Subscribe description: Open a live SSE stream of matches for a SemQL query. - name: Tooling description: Query authoring helpers (lint, auto-complete). - name: Health description: Liveness probe. paths: /v1/lint: post: tags: - Tooling summary: Lint and auto-complete a SemQL query description: | Validates a SemQL query and returns diagnostics (parse/validation errors) and auto-complete suggestions at the given cursor position. Always returns both diagnostics and completions in a single call. Requires `Content-Type: application/json`. operationId: lint requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LintRequest' examples: simple: summary: Lint a partial query value: query: 'MATCH DISTANCE("climate change") WITHIN ' cursor: 40 responses: '200': description: Lint diagnostics and completions. content: application/json: schema: $ref: '#/components/schemas/LintResponse' '400': description: >- Invalid request body, malformed JSON, missing query, or cursor out of bounds. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '405': description: Method not allowed (only POST is accepted). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '413': description: Request body exceeds 64 KB size limit. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '415': description: Content-Type must be application/json. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: | Rate limited or too many concurrent requests. Error codes: `rate_limited` or `too_many_requests`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: [] components: schemas: LintRequest: type: object required: - query properties: query: type: string description: Raw SemQL text to lint and auto-complete. cursor: type: integer minimum: 0 description: | Byte offset in the query where auto-complete context is evaluated. When omitted, defaults to the end of the query. An explicit `0` is honoured as written and returns start-of-query completions — it is not treated as "omitted". An offset past the end of the query, or a negative one, returns `400 invalid_request`. LintResponse: type: object properties: valid: type: boolean description: True when the query has no diagnostics. normalized: type: string description: Canonical SemQL text form (empty when invalid). diagnostics: type: array items: $ref: '#/components/schemas/LintDiagnostic' description: Parse and validation errors found in the query. completions: type: array items: $ref: '#/components/schemas/LintCompletion' description: Valid next tokens at the cursor position. ErrorResponse: type: object required: - error properties: error: type: string description: | Machine-readable error code. See the "Error codes" table in the API description for the full list. message: type: string description: Human-readable error description. request_id: type: string description: | Server-assigned correlation token, also returned in the `X-Request-Id` response header. Quote this when contacting support — it pivots directly to the relevant server log line. retry_after_ms: type: integer format: uint32 description: | Hint for how long to wait before retrying. Present on `backpressure`, `unavailable`, `namespace_unavailable`, and `metering_unavailable` errors; absent (or `0`) means do not retry. LintDiagnostic: type: object properties: severity: type: string description: Diagnostic severity (`error`, `warning`). message: type: string description: Human-readable error description. line: type: integer description: 1-based line number where the error starts. col: type: integer description: 1-based column number where the error starts. end_line: type: integer description: 1-based line number where the error ends. end_col: type: integer description: 1-based column number where the error ends. LintCompletion: type: object properties: label: type: string description: Display text for the completion. kind: type: string description: >- Completion kind (`clause`, `keyword`, `operator`, `delimiter`, `anchor`). detail: type: string description: Human-readable description of what the completion does. securitySchemes: bearerAuth: type: http scheme: bearer description: | API key bearer token. Obtain from the Noetive dashboard. Pass as: `Authorization: Bearer `. ````