API Documentation

This document provides an overview of the Konarr REST API. The API serves both the web UI and external integrations, with separate authentication for users and agents.

Base URL and Versioning

Base URL: http://<konarr-host>:9000/api

Current Version: The API is currently unversioned. Future versions will include version paths.

Content Type: All endpoints expect and return application/json unless otherwise specified.

Authentication

Agent Authentication

Agents authenticate using a Bearer token in the Authorization header:

curl -H "Authorization: Bearer <AGENT_TOKEN>" \
  http://localhost:9000/api/snapshots

The agent token is generated by the server and stored as agent.key in ServerSettings. You can retrieve it from the admin panel or by querying the database.

Session Authentication

Web UI users authenticate via session cookies. Sessions are managed automatically by the frontend and use HTTP-only cookies for security.

Login endpoint: POST /api/auth/login Logout endpoint: POST /api/auth/logout Registration endpoint: POST /api/auth/register

Core Endpoints

Health Check

GET /api

• Description: Server health, status, and configuration
• Authentication: None required
• Response: Server version, commit, configuration, and basic metrics

curl http://localhost:9000/api

Projects

GET /api/projects

• Description: List all projects
• Authentication: Session or Agent
• Response: Array of project objects with metadata

POST /api/projects

• Description: Create a new project
• Authentication: Session or Agent (if auto-create enabled)
• Body: Project name, type, and optional metadata

GET /api/projects/{id}

• Description: Get specific project details
• Authentication: Session or Agent
• Response: Project details with recent snapshots

Snapshots

GET /api/projects/{id}/snapshots

• Description: List snapshots for a project
• Authentication: Session or Agent
• Query Parameters:

POST /api/snapshots

• Description: Upload new snapshot data (agent endpoint)
• Authentication: Agent token required
• Body: Snapshot metadata and SBOM data
• Content-Type: application/json

GET /api/snapshots/{id}

• Description: Get specific snapshot details
• Authentication: Session
• Response: Snapshot metadata, dependencies count, and security summary

Dependencies

GET /api/dependencies

• Description: Search and list dependencies
• Authentication: Session
• Query Parameters:

GET /api/dependencies/{id}

• Description: Get specific dependency details
• Authentication: Session
• Response: Component details, versions, and associated projects

Security Alerts

GET /api/security

• Description: List security alerts and vulnerabilities
• Authentication: Session
• Query Parameters:

GET /api/security/{id}

• Description: Get specific security alert details
• Authentication: Session
• Response: Alert details including affected dependencies and projects

Administration

GET /api/admin

• Description: Administrative settings and server statistics
• Authentication: Admin session
• Response: Server configuration, user statistics, and system information

GET /api/admin/users

• Description: User management (admin only)
• Authentication: Admin session
• Response: List of users with roles and status

Data Models

Project Object

{
  "id": 1,
  "name": "my-application",
  "type": "container",
  "description": "Production web application",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "snapshot_count": 15,
  "latest_snapshot": "2024-01-01T12:00:00Z"
}

Snapshot Object

{
  "id": 1,
  "project_id": 1,
  "sha": "sha256:abc123...",
  "container_image": "nginx:1.21",
  "container_version": "1.21.0",
  "created_at": "2024-01-01T00:00:00Z",
  "component_count": 245,
  "vulnerability_count": 12,
  "has_sbom": true
}

Dependency Object

{
  "id": 1,
  "type": "library",
  "manager": "npm",
  "name": "@types/node",
  "namespace": "@types",
  "version": "18.15.0",
  "purl": "pkg:npm/%40types/node@18.15.0",
  "projects": [
    {"id": 1, "name": "my-application"}
  ]
}

SBOM Upload Format

Agents upload SBOMs in CycloneDX format:

{
  "bomFormat": "CycloneDX",
  "specVersion": "1.6",
  "version": 1,
  "metadata": {
    "timestamp": "2024-01-01T00:00:00Z",
    "tools": [
      {
        "vendor": "anchore",
        "name": "syft",
        "version": "v0.96.0"
      }
    ],
    "component": {
      "type": "container",
      "name": "nginx",
      "version": "1.21"
    }
  },
  "components": [
    {
      "type": "library",
      "name": "openssl",
      "version": "1.1.1",
      "purl": "pkg:deb/debian/openssl@1.1.1"
    }
  ]
}

Error Responses

All API errors follow a consistent format:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Project with ID 999 not found",
    "details": {}
  }
}

Common Error Codes:

Rate Limiting

The API implements rate limiting to prevent abuse:

• Agents: 100 requests per minute per token
• Web sessions: 1000 requests per minute per session
• Health endpoint: No rate limiting

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Client Libraries

Rust Client

The konarr crate includes a client library:

#![allow(unused)]
fn main() {
use konarr::client::KonarrClient;

let client = KonarrClient::new("http://localhost:9000")
    .with_token("your-agent-token");

let projects = client.projects().list().await?;
}

CLI Integration

The konarr-cli tool provides API access:

## CLI Usage Examples

The `konarr-cli` tool provides API access for automation:

```bash
# Upload an SBOM file
konarr-cli upload-sbom --input sbom.json --snapshot-id 123

# Run agent in monitoring mode  
konarr-cli agent --docker-socket /var/run/docker.sock

# Scan a container image
konarr-cli scan --image alpine:latest --output results.json

# List available tools
konarr-cli scan --list

For advanced API usage and integration examples, see the Configuration & Usage guide.