Skip to content

API User Guide: Overview

Logster exposes a small, stable REST API on port 8080 for listing alerts, transitioning alert state, recording analyst verdicts, and querying per-endpoint summaries. This guide is for analysts using curl or Postman, and for integrators wiring Logster into ticketing systems, SIEMs, SOARs, or notification pipelines.

What this guide covers

Page You'll learn how to...
Overview (this page) Understand the API's purpose, base URL, authentication posture, and interactive docs.
API Usage Work end-to-end with common workflows: listing alerts, transitioning state, recording verdicts, and handling errors. Includes full curl examples.
Reference Look up every endpoint, its parameters, its response schema, and its error codes.

Base URL

http://<host>:8080

The host and port come from api.host / api.port in deploy/service-config.yaml. In the default Docker Compose stack, the API is published to localhost:8080.

FastAPI also serves its interactive documentation automatically:

The OpenAPI JSON is usable by SDK generators (openapi-generator, swagger-codegen) if you want a typed client in your language of choice.

Authentication

The default build has no API authentication. create_app() in services/api/src/logster_api/app.py wires only CORS middleware. There is no token validation, no identity check, and no audit log of who transitioned which alert.

[!WARNING] Do not expose port 8080 to any untrusted network without putting an authenticating reverse proxy in front of it. See Admin Guide: Authentication and Security Guide: Configuration for the recommended pattern.

CORS

The API uses fastapi.middleware.cors.CORSMiddleware with the origins listed under api.cors_origins in service-config.yaml. The default is ["*"] — which accepts any origin. Tighten this in production to only the origin(s) you actually serve the dashboard from.

See Admin Guide: Installation Parameters for how to change api.cors_origins.

API at a glance

Method Path Purpose
GET /health Service health check
GET /alerts List alerts (filtered, paginated)
GET /alerts/{alert_id} Fetch one alert
PATCH /alerts/{alert_id} Update status and notes
POST /feedback Submit analyst verdict
GET /endpoints Per-endpoint alert summary

Each endpoint is documented in full in the Reference. For common workflows, see API Usage.

Quick health check

The simplest way to verify the API is reachable and wired correctly:

curl http://localhost:8080/health

A healthy response:

{
  "status": "ok",
  "service": "logster-api",
  "uptime_seconds": 1234.56,
  "alerts_count": 42
}

If you get a connection error, the API container is probably not running. Check docker compose ps api and docker compose logs api.

A note on the alert store

By default, the API is wired to an in-memory alert store:

# services/api/src/logster_api/main.py
store = InMemoryAlertStore()
app = create_app(alert_store=store, cors_origins=cors_origins)

This means alerts are lost on API restart. A PostgreSQL-backed store exists in the alerts package and can be swapped in for production.

[!IMPORTANT] Until you swap the store, treat /alerts as an ephemeral working set rather than a system of record. Do not rely on data surviving a container restart. See Admin Guide: Important Considerations.

Where to go next