canonical: https://jentic.com/apis/graylog.org/graylog

# Graylog REST API

Jentic publishes the only available OpenAPI specification for Graylog REST API, keeping it validated and agent-ready. The Graylog REST API gives programmatic access to a Graylog 6.x cluster - searches, streams, inputs, dashboards, alerts, pipelines, content packs, lookup tables, roles, sessions, indices, and system configuration - across roughly 98 endpoints. Authentication can be a session token via X-Requested-By, HTTP basic auth, or a bearer token, all against a self-hosted host and port.

## For AI agents

Run searches across log streams, manage Graylog inputs, streams, dashboards, alerts, and pipelines, and administer users and content packs.

## Scope

Does not host the underlying Elasticsearch or MongoDB stores, ship log shippers, or process traces and metrics - use for searching and managing Graylog log data and configuration only.

## Capabilities

- Run a relative, absolute, or keyword universal search across the cluster's log data
- Inspect and manage the cluster's nodes via `/system/cluster/nodes`
- Create or list Graylog inputs that feed messages into the cluster
- Build and modify streams that route messages to dashboards and alerts
- Manage processing pipelines and lookup tables that enrich incoming events
- Administer users, roles, and sessions for the Graylog tenant

## Use cases

### Incident Triage with Saved Searches

On-call engineers run keyword and absolute time-range searches against `/search/universal` endpoints to pinpoint the first occurrence of an error during an incident. Streams and pipelines pre-filter the relevant data so search latency stays low even on a busy cluster.

Example prompt: POST to `/search/universal/keyword` with query='error 500' and a 30-minute relative range, then summarize the top 10 source hosts

### Ingestion Pipeline Management

Platform teams use the Inputs and Pipelines surfaces to provision new ingestion paths, attach processing rules, and verify lookup tables in production without touching the Graylog UI. The `/system/inputs` endpoints let automation create a syslog or beats input for a new application as part of an onboarding workflow.

Example prompt: POST a new GELF UDP input to `/system/inputs` and verify it appears in the response of GET `/system/inputs`

### Cluster Health Monitoring

SREs monitor cluster health by polling `/system/cluster/nodes` and comparing returned node states against the expected fleet. Changes in node count or node state feed alerts that wake the on-call rotation before user-visible search performance degrades.

Example prompt: GET `/system/cluster/nodes` and raise an alert if any node's state is not 'CONNECTED'

### Agent-Driven Observability Assistant via Jentic

An AI observability assistant uses Jentic to discover the right Graylog operation when an engineer asks 'what errors did we see in the last hour?' or 'is the kafka input still up?'. Jentic injects the configured auth scheme so the agent never holds the bearer token or session cookie.

Example prompt: Search Jentic for 'search graylog logs', load the schema for `/search/universal/relative`, and execute it with the user's query and time range

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/search/universal/relative` | Search with a rolling time range |
| POST | `/search/universal/absolute` | Search with absolute start and end timestamps |
| POST | `/search/universal/keyword` | Search with a Graylog time keyword |
| GET | `/system/cluster/nodes` | List nodes in the cluster |
| GET | `/system/inputs` | List configured inputs |
| POST | `/system/inputs` | Create a new input |

## Key resources

- **Search** — Universal relative, absolute, and keyword searches against indexed logs
- **System** — Cluster, node, input, and configuration management
- **Streams** — Define routing rules that send messages to dashboards and alerts
- **Pipelines** — Manage processing pipelines and rules that transform incoming events
- **LookupTables** — Configure and query lookup tables used to enrich messages
- **Users** — Administer users, roles, and sessions
- **Dashboards** — Create and manage dashboards built from saved searches

## Why Jentic

- **Setup:** Wiring the Graylog REST API by hand means picking among its basic, bearer, and session-token schemes, pointing at your own {graylog_host}:{port} install, and mapping dozens of search, stream, and system-input endpoints yourself. Through Jentic you install once, import the Graylog REST API from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** Graylog puts the stream and input ids in the URL path (`/streams/{streamId}`, `/system/inputs/{inputId}`), so a rule can pin your agent to one stream: it can search and read that stream and nothing else. You choose the operations it may call, so ones like pausing a stream or stopping an input are not included unless you add them.
- **Credential handling:** Your Graylog credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'search logs over the last hour' or 'list configured streams', and Jentic returns the matching Graylog operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Elastic Kibana** — Search and dashboarding on top of Elasticsearch as an alternative log platform
- **Splunk** — Commercial log analytics with broader SIEM features
- **Sumo Logic** — Cloud-hosted log analytics platform
- **Outlook Calendar** — Schedule incident review meetings after a Graylog alert fires

## FAQ

### Why is there no official OpenAPI spec for Graylog REST API?

Graylog publishes a Swagger description through its admin UI but does not ship an externally maintained OpenAPI 3 file for automation use. Jentic generates and maintains this spec so that AI agents and developers can call Graylog REST API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Graylog REST API use?

Graylog supports three schemes on these endpoints: HTTP basic auth with a username and password, a bearer token from a session, or a session token paired with the X-Requested-By header. Through Jentic the chosen credential is stored in the vault and the X-Requested-By header is added automatically when needed.

### Can I run a time-range search across all my logs?

Yes. POST to `/search/universal/relative` for a rolling window such as the last 15 minutes, `/search/universal/absolute` for a fixed start and end timestamp, or `/search/universal/keyword` for a Graylog-style time keyword like 'yesterday'. Each accepts a query string, optional stream filters, and a result limit.

### What are the rate limits for the Graylog REST API?

Graylog is typically self-hosted, so there is no vendor-imposed rate limit. Practical limits come from the cluster's compute and storage capacity. For automation, restrict expensive search calls to narrow time ranges and use streams to pre-filter data rather than running broad universal searches.

### How do I create a new input through Jentic?

Search Jentic for 'create graylog input', load the operation that maps to POST `/system/inputs`, and execute it with the input type, configuration, and global flag. The response includes the new input id, which you can then read back via GET `/system/inputs/{inputId}` to confirm it started.

### Does the API expose alert definitions and event notifications?

Yes. The Events tag covers alert definitions and notifications, and the Streams tag exposes the streams those alerts evaluate. Use these surfaces to script alert lifecycle changes during deployments and to automate exporting alert configuration into version control.

### Can I limit what my agent is allowed to do with the Graylog REST API?

Yes. Because you run Jentic One yourself, your own rules decide which Graylog operations and which credential the agent may use. Since Graylog puts stream and input ids directly in the URL path, such as `/streams/{streamId}` and `/system/inputs/{inputId}`, you can pin the agent to a single stream so it only searches and reads that stream and nothing else. You pick the exact operations it may call, so actions like pausing a stream or stopping an input are excluded unless you add them.