api daemon endpoints

Daemon endpoints

The daemon endpoint implementation lives in src/lode/daemon.py. The OpenAPI source is openapi/loded.openapi.yml, and generated docs are stored in docs/api/loded.md.

Endpoint table

Endpoint	Method	Request shape	Response purpose
/health	GET	none	Confirms the service is running.
/metrics	GET	none	Prometheus-style request counters when metrics are enabled.
/status	GET	none	Lists indexed repositories.
/search	GET	query params q or query, optional repo, limit	Searches indexed nodes.
/search	POST	JSON query, optional repo, limit	Searches indexed nodes.
/index	POST	JSON path	Indexes a repository path.
/context	POST	JSON query, optional repo, budget, limit	Builds an agent context pack.
/impact	GET	query params target or q, optional traversal controls	Builds an impact report.
/impact	POST	JSON target, optional traversal controls	Builds an impact report.

Request lifecycle

sequenceDiagram
    participant Client
    participant Handler as LodeHandler
    participant Core as Lode core
    participant DB as SQLite

    Client->>Handler: HTTP request
    Handler->>Handler: parse path/body/query
    Handler->>Core: call search, context, index, or impact
    Core->>DB: read or write facts
    Handler-->>Client: JSON response with x-request-id

Loading

Error behavior

LodeHandler.do_POST() in src/lode/daemon.py catches invalid files, JSON parsing errors, SQLite errors, type errors, and value errors, then returns status 400 with an error payload. Unknown routes return status 404.

Keeping docs fresh

When endpoint behavior changes, update openapi/loded.openapi.yml and run:

uv run python scripts/generate_openapi_docs.py --check

Use the generator in scripts/generate_openapi_docs.py to keep docs/api/loded.md aligned.

Related pages

• Local daemon API
• Logging
• Configuration