> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vigolium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vigolium API Reference, Overview

> Base URL, authentication, project scoping, health checks, and common endpoints for the Vigolium API server.

Base URL: `http://localhost:9002` (default)

## Starting the Server

```bash theme={null}
# No authentication (development)
vigolium server -A

# With API key
export VIGOLIUM_API_KEY="my-secret-key"
vigolium server -A

# Custom host/port
vigolium server -A --host 127.0.0.1 --service-port 8080
```

## Authentication

`/api/*` routes require a Bearer token when the server is started with `VIGOLIUM_API_KEY` or `server.auth_api_key` set.

```bash theme={null}
curl -H "Authorization: Bearer my-secret-key" http://localhost:9002/api/stats
```

Public endpoints (no auth required): `GET /`, `GET /health`, `GET /server-info`, `GET /swagger/*`, `GET /metrics`, and `POST /api/auth/login`.

Demo-only and view-only modes (`cfg.DemoOnly` / `cfg.ViewOnly`) further gate mutating routes; admin/operator/viewer roles enforced by `RoleGuard` middleware override the per-route checks.

## Project Scoping

All API operations are scoped to a project via the `X-Project-UUID` request header. If the header is omitted, the default project (`00000000-0000-0000-0000-000000000001`) is used.

```bash theme={null}
# Scope requests to a specific project
curl -H "Authorization: Bearer my-secret-key" \
     -H "X-Project-UUID: a1b2c3d4-..." \
     http://localhost:9002/api/findings
```

This applies to all data endpoints: ingestion, findings, HTTP records, stats, scans, source repos, and OAST interactions. See [Projects](/api-references/projects) for the full multi-tenancy reference.

***

## GET /api/info, App Info

Returns basic application metadata. (`GET /` serves the embedded static UI, not JSON.)

```bash theme={null}
curl -s http://localhost:9002/api/info | jq .
```

```json theme={null}
{
  "name": "vigolium",
  "version": "v0.1.8-alpha",
  "author": "vigolium",
  "docs": "https://docs.vigolium.com",
  "build_time": "2026-05-21T15:22:43Z",
  "commit": "67bdce4"
}
```

***

## GET /health, Health Check

Returns server health status.

```bash theme={null}
curl -s http://localhost:9002/health | jq .
```

```json theme={null}
{
  "status": "healthy",
  "timestamp": "2026-02-16T15:30:00Z"
}
```

***

## GET /server-info, Server Info

Returns detailed server information including uptime, database driver, queue depth, and record/finding totals.

```bash theme={null}
curl -s http://localhost:9002/server-info | jq .
```

```json theme={null}
{
  "name": "vigolium",
  "version": "v0.1.8-alpha",
  "author": "vigolium",
  "docs": "https://docs.vigolium.com",
  "build_time": "2026-05-21T15:22:43Z",
  "commit": "67bdce4",
  "uptime": "5m32s",
  "service_addr": "0.0.0.0:9002",
  "proxy_addr": "",
  "queue_depth": 0,
  "total_records": 1234,
  "total_findings": 42,
  "license_spdx": "AGPL-3.0",
  "source": "https://github.com/vigolium/vigolium"
}
```

***

## GET /swagger/\*, Swagger UI

Interactive API documentation. Open in a browser.

```
http://localhost:9002/swagger/
```

The raw OpenAPI 3.0 spec is available at:

```bash theme={null}
curl -s http://localhost:9002/swagger/doc.json | jq .info
```

***

## GET /metrics, Prometheus Metrics

Returns Prometheus-formatted metrics. The route is always registered and unauthenticated; the handler gates the response on the `EnableMetrics` server flag (CLI `--enable-metrics` / config `server.enable_metrics`).

```bash theme={null}
curl -s http://localhost:9002/metrics
```

***

## CORS

CORS can be enabled via the `cors_allowed_origins` server config:

| Value             | Behavior                                                     |
| ----------------- | ------------------------------------------------------------ |
| `*`               | Allow all origins                                            |
| `reflect-origin`  | Reflect the request's `Origin` header (allows credentials)   |
| `origin1,origin2` | Allow specific origins (comma-separated, allows credentials) |
| *(empty/omitted)* | CORS disabled                                                |

Allowed methods: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `OPTIONS`. Allowed headers: `Content-Type`, `Authorization`, `X-Project-UUID`, `X-User-Email`.

***

## Error Responses

All errors follow a consistent format:

```json theme={null}
{
  "error": "error message",
  "code": 400,
  "details": "optional additional details"
}
```

**Common error codes:**

| Code | Meaning                                        |
| ---- | ---------------------------------------------- |
| 400  | Bad request (invalid JSON, missing fields)     |
| 401  | Unauthorized (missing or invalid Bearer token) |
| 404  | Not found (e.g. agent run ID not found)        |
| 409  | Conflict (scan or agent already running)       |
| 500  | Internal server error                          |
| 503  | Database not available                         |