REST API

A small local HTTP surface for contracts, audits, harmony, and catalog data.

Nerviq exposes a zero-dependency local server so dashboards, extensions, scripts, and internal tools can query the same engine the CLI uses, inspect the live OpenAPI contract, and avoid terminal scraping.

Zero extra depsGET-onlyOpenAPI 3.1Local-first JSON

Start the Server

The API server runs locally with Node's built-in HTTP module. There is no framework layer, no external runtime dependency, and no background cloud service required.

3000

Default port

Override with the CLI flag when you need a different local port.

Read endpoints

OpenAPI, health, audit, harmony, and catalog are the current serve surface.

2441

Current checks

The live health response reports the merged catalog size exposed by the server.

bash

nerviq serve --port 3000

Base Directory

Relative dir values resolve from the directory where the server was started. If you want API callers to audit sibling repos, either start the server from a shared parent directory or pass absolute paths.

Contract First

Use /api/openapi.json as the source of truth for generated clients, Swagger UI imports, and internal integrations. The static docs on this page mirror that contract, but the live JSON is canonical for a running server.

Separate from MCP

This page documents the nerviq serve HTTP API. If your tool expects Model Context Protocol over stdio, register the separate nerviq-mcp binary instead of pointing it at this server.

Endpoint Index

All current endpoints are GET-only and return JSON with no cache persistence.

Method	Path	Purpose
GET	`/api/openapi.json`	Returns the live OpenAPI 3.1 contract for the current Nerviq serve instance.
GET	`/api/health`	Server status probe for local dashboards, readiness checks, and wrapper scripts.
GET	`/api/audit`	Runs a full Nerviq platform audit for one repository and one platform.
GET	`/api/harmony`	Runs cross-platform drift analysis and returns the canonical model, detected drift, and recommendations.
GET	`/api/catalog`	Returns the unified check catalog for UI rendering, ranking, search, and internal tooling.

Common Behavior

These rules apply across the whole REST surface.

Contract

Methods

Every endpoint is GET-only today. Sending POST, PUT, PATCH, or DELETE returns a 405 JSON error.

Contract

Errors

Failures return a small object with an error string. Validation problems use 400; unexpected failures fall back to 500.

Contract

Envelope

Operational endpoints return success payloads as { data, meta }. The only exception is /api/openapi.json, which returns the raw OpenAPI document.

Contract

Caching

Responses are served with Cache-Control: no-store so audit and harmony consumers always see fresh local state.

GET /api/openapi.json

Returns the live OpenAPI 3.1 contract for the current Nerviq serve instance.

Field	Value
Method	GET
Path	`/api/openapi.json`
Request body	None. This contract endpoint is read-only.

Param	Required	Description
`None`	No query parameters.	The response is generated from the running local server context.

Error code	When it happens
405	Method not allowed when a non-GET method is used.

Request

cURL example

bash

curl http://127.0.0.1:3000/api/openapi.json

JSON

Response body example

json

{
  "openapi": "3.1.0",
  "info": {
    "title": "Nerviq Local API",
    "version": "1.30.0"
  },
  "servers": [
    {
      "url": "http://127.0.0.1:3000"
    }
  ]
}

GET /api/health

Server status probe for local dashboards, readiness checks, and wrapper scripts.

Field	Value
Method	GET
Path	`/api/health`
Request body	None. This endpoint only accepts GET requests.

Param	Required	Description
`None`	No query parameters.	Always local server state.

Error code	When it happens
405	Method not allowed when a non-GET method is used.
500	Unexpected server failure while building the response.

Request

cURL example

bash

curl http://127.0.0.1:3000/api/health

JSON

Response body example

json

{
  "data": {
    "status": "ok",
    "version": "1.30.0",
    "checks": 2441
  },
  "meta": {
    "version": "1.30.0",
    "timestamp": "2026-04-09T12:00:00.000Z"
  }
}

GET /api/audit

Runs a full Nerviq platform audit for one repository and one platform.

Field	Value
Method	GET
Path	`/api/audit`
Request body	None. Supply inputs through the query string.

Param	Required	Description
`platform`	No	Target platform. One of claude, codex, gemini, copilot, cursor, windsurf, aider, opencode. Defaults to `claude`.
`dir`	No	Directory to audit. Relative paths resolve from the server base directory; defaults to `.`.

Error code	When it happens
400	Unsupported platform or directory not found.
405	Method not allowed when a non-GET method is used.
500	Unexpected audit engine failure.

Request

cURL example

bash

curl "http://127.0.0.1:3000/api/audit?platform=claude&dir=."

JSON

Response body example

json

{
  "data": {
    "platform": "claude",
    "platformLabel": "Claude",
    "platformVersion": null,
    "score": 84,
    "organicScore": 68,
    "earnedPoints": 560,
    "maxPoints": 671,
    "isScaffolded": false,
    "passed": 196,
    "failed": 34,
    "skipped": 28,
    "checkCount": 258,
    "stacks": [
      { "key": "node", "label": "Node.js" }
    ],
    "topNextActions": [
      {
        "key": "verificationLoop",
        "name": "Verification criteria in CLAUDE.md",
        "impact": "critical",
        "fix": "Add test/lint/build commands to CLAUDE.md so Claude can verify its own work."
      }
    ],
    "results": [
      {
        "key": "claudeMd",
        "name": "CLAUDE.md project instructions",
        "impact": "critical",
        "category": "memory",
        "passed": true
      }
    ]
  },
  "meta": {
    "version": "1.30.0",
    "timestamp": "2026-04-09T12:00:00.000Z"
  }
}

GET /api/harmony

Runs cross-platform drift analysis and returns the canonical model, detected drift, and recommendations.

Field	Value
Method	GET
Path	`/api/harmony`
Request body	None. Harmony is read-only and query-string driven.

Param	Required	Description
`dir`	No	Directory to inspect for active platform surfaces. Relative paths resolve from the server base directory; defaults to `.`.

Error code	When it happens
400	Directory not found.
405	Method not allowed when a non-GET method is used.
500	Unexpected harmony analysis failure.

Request

cURL example

bash

curl "http://127.0.0.1:3000/api/harmony?dir=."

JSON

Response body example

json

{
  "data": {
    "harmonyScore": 91,
    "platformScores": {
      "claude": 90,
      "codex": 83
    },
    "drift": {
      "drifts": [],
      "summary": {
        "total": 0,
        "critical": 0,
        "high": 0,
        "medium": 0,
        "low": 0
      },
      "harmonyScore": 92
    },
    "recommendations": [
      {
        "priority": "medium",
        "category": "tooling",
        "message": "Use harmony sync when MCP or instruction surfaces drift across platforms."
      }
    ],
    "activePlatforms": [
      { "platform": "claude", "label": "Claude Code" },
      { "platform": "codex", "label": "Codex" }
    ]
  },
  "meta": {
    "version": "1.30.0",
    "timestamp": "2026-04-09T12:00:00.000Z"
  }
}

GET /api/catalog

Returns the unified check catalog for UI rendering, ranking, search, and internal tooling.

Field	Value
Method	GET
Path	`/api/catalog`
Request body	None. The catalog is exposed as a read-only JSON array.

Param	Required	Description
`None`	No query parameters.	Returns the full merged catalog.

Error code	When it happens
405	Method not allowed when a non-GET method is used.
500	Unexpected catalog generation failure.

Request

cURL example

bash

curl http://127.0.0.1:3000/api/catalog

JSON

Response body example

json

{
  "data": [
    {
      "platform": "claude",
      "id": "CL-A01",
      "name": "CLAUDE.md project instructions",
      "category": "memory",
      "impact": "critical",
      "fix": "Create CLAUDE.md with project-specific instructions, build commands, and coding conventions.",
      "sourceUrl": "https://code.claude.com/docs/en/memory",
      "confidence": 0.7
    }
  ],
  "meta": {
    "version": "1.30.0",
    "timestamp": "2026-04-09T12:00:00.000Z"
  }
}

Quick Client Example

Because every endpoint returns plain JSON, the browser, Node, and internal tooling integrations all stay simple.

JavaScript

Browser fetch

const res = await fetch(
  "http://127.0.0.1:3000/api/audit?platform=claude&dir=."
);

if (!res.ok) {
  const error = await res.json();
  throw new Error(error.error);
}

const payload = await res.json();
console.log(payload.data.score);

Usage

Operational note

Use /api/openapi.json for generated clients and Swagger imports, /api/health for local readiness probes, /api/audit inside repo dashboards, /api/harmony for cross-platform reporting, and /api/catalog when the UI needs the full check dictionary.