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

# Broker API Reference

> REST API for querying kguardian telemetry data

## Overview

The kguardian Broker exposes a REST API for querying collected telemetry data. The CLI uses this API internally, but you can also integrate directly with it for custom workflows.

## Base URL

```
http://kguardian-broker.kguardian.svc.cluster.local:9090
```

For external access, use port-forwarding:

```bash theme={null}
kubectl port-forward -n kguardian svc/kguardian-broker 9090:9090
```

## Authentication

<Warning>
  The broker currently has **no authentication**. The API should only be accessible within the cluster network. For production deployments, consider using NetworkPolicies, service mesh, or an API gateway with authentication.
</Warning>

For the broker's current released version, see
[`broker/VERSION`](https://github.com/kguardian-dev/kguardian/blob/main/broker/VERSION)
— component versions evolve independently per the
[release strategy](https://github.com/kguardian-dev/kguardian/blob/main/RELEASES.md).

## API Endpoints

<CardGroup cols={2}>
  <Card title="Pods" icon="cube" href="/api-reference/endpoints/pods">
    Add and retrieve pod metadata
  </Card>

  <Card title="Traffic" icon="arrow-right-arrow-left" href="/api-reference/endpoints/traffic">
    Query network traffic data
  </Card>

  <Card title="Syscalls" icon="terminal" href="/api-reference/endpoints/syscalls">
    Retrieve syscall observations
  </Card>

  <Card title="Services" icon="cloud" href="/api-reference/endpoints/services">
    Service IP to metadata mapping
  </Card>

  <Card title="Audit Verdicts" icon="shield-check" href="/api-reference/endpoints/audit-verdicts">
    Query Would-Deny / Allow verdicts from the audit evaluator
  </Card>
</CardGroup>

## Response Format

All responses are JSON with standard HTTP status codes:

* `200 OK` - Success
* `400 Bad Request` - Invalid parameters
* `404 Not Found` - Resource not found
* `500 Internal Server Error` - Server error

## Common Patterns

### Pagination

Most endpoints return all matching rows without paging — fine for
small / medium clusters but unbounded on busy ones. `/audit/verdicts`
is the exception: it supports a `limit` query parameter (default 100,
max 500) and orders by `(observed_at DESC, id DESC)` for stable
cursor-style traversal. The `/pod/info`, `/svc/info`, `/pod/traffic`
and `/pod/traffic/{name}` endpoints have stable ordering too — see
each page for the sort key — but no LIMIT yet.

### Filtering

`/audit/verdicts` supports server-side filtering by policy,
namespace, verdict, and direction (index-backed; see the endpoint
page for the full contract).

The pod-name- and IP-scoped GETs already filter at the URL: prefer
`GET /pod/traffic/{name}` over `GET /pod/traffic` + client-side
filter on any non-trivial cluster.

### Rate Limiting

No rate limiting is currently enforced at the broker. The audit
forwarder bounds concurrent in-flight `/evaluate` calls via the
`AUDIT_INFLIGHT_PERMITS` semaphore (default 16) and exposes the
gauge as `broker_audit_inflight_available` on `/metrics` so
operators can spot saturation.