API Reference

Everything the dashboard can do, your scripts can do: start analyses, poll jobs, and read projects and reports over plain HTTPS with an API key.

Authentication

Create a key in Settings → API Keys (it starts with norveth_sk_) and send it as a Bearer token on every request. Keys are scoped to your organization — you only ever see your own projects. The base URL is https://norveth.app/api.

Start an analysis

POST https://norveth.app/api/analyze

curl -X POST https://norveth.app/api/analyze \
  -H "Authorization: Bearer $NORVETH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "GITHUB",
    "sourceUrl": "https://github.com/organization/core-service"
  }'

# → { "success": true, "projectId": "…", "jobId": "…", "status": "QUEUED" }

Poll until it completes

GET https://norveth.app/api/jobs/{jobId}

curl https://norveth.app/api/jobs/$JOB_ID \
  -H "Authorization: Bearer $NORVETH_API_KEY"

# → { "id": "…", "status": "COMPLETED", "projectId": "…",
#     "startedAt": "…", "completedAt": "…", "errorMessage": null }

Endpoints

POST /analyzeStart an analysis of a GitHub repository, website URL, or previously uploaded ZIP. Returns the project and job ids.

GET /jobs/{jobId}Poll an analysis job. Status moves QUEUED → RUNNING → COMPLETED (or FAILED).

GET /projectsList or search the projects in your organization (query params: q, limit).

GET /projects/{id}A single project with its latest analysis summary.

GET /projects/{id}/reportsThe generated reports for a project — executive summary, architecture, security, and more.

Errors are plain JSON: 401 for a missing or invalid key, 404 for resources outside your organization, 429 with a Retry-After header when rate-limited, and 402 with a QUOTA_EXCEEDED code when your plan's monthly analysis quota is used up.

MCP Server

The same key connects Claude, ChatGPT, Gemini, and Cursor to Norveth over the Model Context Protocol. Setup guide →

CLI

@norveth/cli wraps this API for the terminal and CI: analyze, watch a job, and pull the report without writing a script.

GitHub Action & VS Code

Run an analysis on every push with the composite GitHub Action, or analyze the open workspace from the VS Code extension.

Webhooks

Get your API key

API keys are self-serve on every plan: sign in, open Settings → API Keys, and create a norveth_sk_ key.

Create an API key Connect your AI assistant