graylog
graylog
contains codeGraylog REST API -- log search (Views/Search + legacy universal), streams, pipelines, inputs, alerts, events, dashboards, users, roles, sidecars, index management, and cluster administration. Targets Graylog 6.x.
Source: Graylog REST API
Coverage
72% (232 of ~320 endpoints)
Focus: Views/Search API (sync, messages, pivot/histogram/stats via composites), legacy relative + keyword search, streams, stream rules, pipelines, pipeline rules, inputs, extractors, events, notifications, dashboards, users, roles, tokens, index sets, indices, grok patterns, lookup tables, sidecars, sidecar configurations, collectors, content packs, outputs, metrics, system info, cluster, processing control, loggers, sources, forensic incident_window composite
Missing: enterprise-only plugins (archives, audit log, reports, license, data lake), Views CRUD (saved views, dashboard widgets), alert callbacks (legacy), message decorators, debug events, codec types, retention/rotation strategy config, LDAP config, async Views/Search (poll-based)
Setup
- 1. Log into your Graylog web interface (default: http://<host>:9000)
- 2. Navigate to System > Users and Teams
- 3. Click your username, then 'Edit Tokens'
- 4. Enter a token name (e.g., 'toolmesh') and click 'Create Token'
- 5. Copy the generated token -- it is shown only once
- 6. Set CREDENTIAL_GRAYLOG_TOKEN to the token string
- 7. Set CREDENTIAL_GRAYLOG_TOKEN_PASSWORD to the literal string 'token'
Environment variable: CREDENTIAL_GRAYLOG_TOKEN, CREDENTIAL_GRAYLOG_TOKEN_PASSWORD
Graylog uses HTTP Basic Auth with access tokens. The username is the token string, the password is the literal word "token". Tokens have configurable TTL (default 30 days). Self-hosted: adjust the url in backends.yaml to match your Graylog server address.
Install
Add to your backends.yaml:
- name: graylog
transport: rest
dadl: graylog.dadl
url: "https://graylog.example.com/api"
Set the credential:
CREDENTIAL_GRAYLOG_TOKEN, CREDENTIAL_GRAYLOG_TOKEN_PASSWORD=your-token-hereTools (230)
GET search_relative Search messages with a relative time range (seconds from now). Query uses Lucene syntax. Returns messages with id, timestamp, source, and all fields. Default limit 150, max 10000. Use filter "streams:STREAM_ID" to scope to a stream.
GET search_keyword Search messages with a Natty-parsed open-ended time range like "last 5 minutes", "last 7 hours", "yesterday", "last week". WARNING: closed/relative phrases like "7 hours ago" are rejected with HTTP 400. For closed absolute windows or aggregation use the views_search_sync / aggregate_pivot composites instead.
POST views_search_sync Execute a Views/Search query synchronously and return results inline. Body shape: { id?, queries: [...], parameters: [], skip_no_streams_check? }. NOTE: there is no top-level "streams" field -- Graylog rejects it with HTTP 400. Scope to streams via query.filter (e.g. { type: "or", filters: [{ type: "stream", id: STREAM_ID }] }) on the individual query object. Each query has id, query.query_string, timerange (absolute / relative / keyword), optional filter, and search_types[] (pivot, messages, events, ...). For everyday forensic work prefer the higher-level composites: aggregate_by_field, aggregate_pivot, histogram_grouped, field_stats, search_messages_compact, incident_window. Server-side timeout via ?timeout=<seconds>, default 60.
GET get_message Retrieve a single message by its ID and index name. Returns all message fields. POST parse_message Parse a raw message string using Graylog's message parsing pipeline. Useful for testing extractors. GET analyze_message_field Analyze a message field value to show how Elasticsearch tokenizes it. GET list_saved_searches List all saved searches. GET get_saved_search Get a saved search by ID. POST create_saved_search Create a saved search. DELETE delete_saved_search Delete a saved search. GET list_streams List all streams. Returns stream id, title, description, rules, matching_type, disabled status, and index_set_id. The Default Stream ID is "000000000000000000000001".
GET get_stream Get a single stream by ID with its configuration and rules. POST create_stream Create a new stream. matching_type: AND (all rules must match) or OR (any rule matches). The stream is created paused -- call resume_stream to start routing messages.
PUT update_stream Update a stream's title, description, matching type, or index set. DELETE delete_stream Delete a stream. The Default Stream cannot be deleted. POST clone_stream Clone a stream including all its rules. POST pause_stream Pause a stream. Messages will no longer be routed to this stream. POST resume_stream Resume a paused stream. Messages will start routing to this stream again. GET list_enabled_streams List only enabled (non-paused) streams. POST test_stream_match Test if a message would match the rules of a stream. GET list_stream_rules List all rules for a stream. Rule types: 1=exact match, 2=regex match, 3=greater than, 4=less than, 5=field presence, 6=contains, 7=always match, 8=match input.
GET get_stream_rule Get a single stream rule. POST create_stream_rule Create a stream rule. type is an integer: 1=exact, 2=regex, 3=greater_than, 4=less_than, 5=field_presence, 6=contains, 7=always_match, 8=match_input.
PUT update_stream_rule Update a stream rule. DELETE delete_stream_rule Delete a stream rule. GET list_stream_outputs List outputs assigned to a stream. POST add_stream_output Add an existing output to a stream. DELETE remove_stream_output Remove an output from a stream. GET list_pipelines List all processing pipelines. Each pipeline has stages with rules. Pipeline source uses Graylog's pipeline rule language.
GET get_pipeline Get a single pipeline by ID, including its source code and stages. POST create_pipeline Create a processing pipeline. The source field contains the pipeline definition in Graylog pipeline language. Validate with parse_pipeline first.
PUT update_pipeline Update a pipeline's source, title, or description. DELETE delete_pipeline Delete a processing pipeline. POST parse_pipeline Parse and validate pipeline source without creating it. Returns parse errors if invalid. POST simulate_pipeline Simulate pipeline processing on a message to see which rules would match and what output would be produced. GET list_pipeline_rules List all pipeline rules. Rules are written in Graylog's rule language. GET get_pipeline_rule Get a single pipeline rule by ID. POST create_pipeline_rule Create a new pipeline rule. Validate with parse_pipeline_rule first. PUT update_pipeline_rule Update a pipeline rule. DELETE delete_pipeline_rule Delete a pipeline rule. POST parse_pipeline_rule Parse and validate a pipeline rule without creating it. GET list_pipeline_functions List all available functions that can be used in pipeline rules. GET list_pipeline_connections List all stream-to-pipeline connections. GET get_stream_pipeline_connections Get pipeline connections for a specific stream. POST connect_pipeline_to_stream Connect pipelines to a stream. POST connect_stream_to_pipeline Connect streams to a pipeline. GET list_inputs List all configured inputs. Each input has a type (e.g. org.graylog2.inputs.syslog.udp.SyslogUDPInput), title, global flag, and configuration.
GET get_input Get a single input by ID. POST create_input Create a new input. Use list_input_types to see available types and their configuration fields. Set global=true for cluster-wide inputs, false for node-local.
PUT update_input Update an input's title, configuration, or global flag. DELETE delete_input Delete an input. This stops ingestion from this source. POST launch_input Start/launch an existing input. POST stop_input Stop a running input. GET list_input_types List all available input types with their configuration schemas. GET get_input_type Get details for a specific input type including all configuration fields. GET list_input_states List input states (running, stopped, failed) for all inputs on this node. GET list_extractors List all extractors configured on an input. GET get_extractor Get a single extractor. POST create_extractor Create an extractor on an input. Types: regex, substring, split_and_index, copy_input, grok, json, lookup_table.
PUT update_extractor Update an extractor. DELETE delete_extractor Delete an extractor from an input. GET list_static_fields List static fields added to all messages from this input. POST create_static_field Add a static field to all messages from this input. DELETE delete_static_field Remove a static field from an input. GET list_event_definitions List all event definitions (alert conditions in Graylog 3.1+). GET get_event_definition Get a single event definition. POST create_event_definition Create an event definition. config contains the condition type and parameters. notification_settings controls which notifications fire.
PUT update_event_definition Update an event definition. DELETE delete_event_definition Delete an event definition. POST execute_event_definition Manually trigger an event definition to check for events now. POST validate_event_definition Validate an event definition without creating it. POST search_events Search for triggered events. Supports filtering by event definition, timerange, and query. Returns events with timestamp, priority, fields, and source.
GET list_event_notifications List all event notifications (email, HTTP, Slack, etc.). GET get_event_notification Get a single event notification. POST create_event_notification Create an event notification. Config varies by type (email, http, slack, etc.). PUT update_event_notification Update an event notification. DELETE delete_event_notification Delete an event notification. POST test_event_notification Send a test notification to verify the notification configuration works. GET list_dashboards List all dashboards. GET get_dashboard Get a single dashboard with all its widgets. POST create_dashboard Create a new dashboard. PUT update_dashboard Update a dashboard's title or description. DELETE delete_dashboard Delete a dashboard and all its widgets. GET list_users List all users including their roles, permissions, and preferences. GET get_user Get a user by username. POST create_user Create a new user. PUT update_user Update a user's details. DELETE delete_user Delete a user. Built-in admin user cannot be deleted. PUT change_user_password Change a user's password. PUT update_user_permissions Update a user's permissions. PUT update_user_preferences Update a user's UI preferences. GET list_user_tokens List all access tokens for a user. Token values are NOT returned -- only name, id, and last_access. POST create_user_token Create a new access token for a user. The token value is returned ONLY in this response. Store it immediately. Used for API auth: username=token_value, password="token".
DELETE delete_user_token Delete/revoke an access token. GET list_roles List all roles with their permissions. GET get_role Get a role by name. POST create_role Create a new role. PUT update_role Update a role. DELETE delete_role Delete a role. Built-in roles (Admin, Reader) cannot be deleted. GET list_role_members List all users assigned to a role. PUT add_role_member Add a user to a role. DELETE remove_role_member Remove a user from a role. GET list_index_sets List all index sets. Each index set defines retention, rotation, and sharding for a group of indices. Every stream maps to one index set.
GET get_index_set Get a single index set. POST create_index_set Create a new index set. PUT update_index_set Update an index set. DELETE delete_index_set Delete an index set. Optionally delete all associated indices. PUT set_default_index_set Set an index set as the default for new streams. GET get_index_set_stats Get statistics for all index sets (document count, size, segments). GET list_indices List all Elasticsearch/OpenSearch indices managed by Graylog. GET list_open_indices List all open (writable/searchable) indices. GET list_closed_indices List all closed indices. GET get_index Get details for a specific index. POST close_index Close an index. Closed indices cannot be searched but retain data. POST reopen_index Reopen a closed index. DELETE delete_index Delete an index. This permanently removes all data in the index. GET list_index_ranges List all index ranges (time boundaries for each index). POST rebuild_all_index_ranges Trigger a rebuild of all index ranges. Long-running operation. POST rebuild_index_range Rebuild index range for a specific index. GET get_deflector Get the current deflector (active write index) status. POST cycle_deflector Cycle the deflector -- close the current write index and create a new one. GET get_deflector_for_index_set Get the deflector for a specific index set. POST cycle_deflector_for_index_set Cycle the deflector for a specific index set. GET get_indexer_overview Get indexing overview with processing rates and counts. GET get_indexer_cluster_health Get Elasticsearch/OpenSearch cluster health (green/yellow/red). GET get_indexer_cluster_name Get the Elasticsearch/OpenSearch cluster name. GET list_indexer_failures List indexer failures (messages that could not be indexed). GET count_indexer_failures Get the total count of indexer failures. GET list_grok_patterns List all grok patterns used for message extraction. GET get_grok_pattern Get a single grok pattern. POST create_grok_pattern Create a new grok pattern. PUT update_grok_pattern Update a grok pattern. DELETE delete_grok_pattern Delete a grok pattern. POST test_grok_pattern Test a grok pattern against a sample string. GET list_lookup_tables List all lookup tables with their data adapter and cache references. GET get_lookup_table Get a lookup table by ID or name. POST create_lookup_table Create a lookup table. PUT update_lookup_table Update a lookup table. DELETE delete_lookup_table Delete a lookup table. GET list_lookup_adapters List all lookup data adapters. GET get_lookup_adapter Get a lookup data adapter by ID or name. POST create_lookup_adapter Create a lookup data adapter. PUT update_lookup_adapter Update a lookup data adapter. DELETE delete_lookup_adapter Delete a lookup data adapter. GET list_lookup_caches List all lookup caches. GET get_lookup_cache Get a lookup cache by ID or name. POST create_lookup_cache Create a lookup cache. PUT update_lookup_cache Update a lookup cache. DELETE delete_lookup_cache Delete a lookup cache. GET list_lookup_adapter_types List available data adapter types. GET list_lookup_cache_types List available cache types. GET list_outputs List all configured outputs. GET get_output Get a single output. POST create_output Create a new output. Use list_output_types to see available types. PUT update_output Update an output. DELETE delete_output Delete an output. GET list_output_types List available output types with their configuration schemas. GET list_content_packs List all content packs (bundles of inputs, streams, dashboards, etc.). GET get_content_pack Get a content pack with all its revisions. POST upload_content_pack Upload/create a content pack. DELETE delete_content_pack Delete a content pack. POST install_content_pack Install a specific revision of a content pack. GET list_content_pack_installations List all installations of a content pack. DELETE uninstall_content_pack Uninstall a content pack installation. GET list_sidecars List all registered sidecars. Sidecars are agents running on hosts that manage log collectors (Filebeat, Winlogbeat, NXLog).
GET get_sidecar Get a single sidecar by ID. GET sidecar_administration Get sidecar administration overview with collector statuses. POST bulk_sidecar_action Perform bulk actions on sidecars (assign configurations, restart collectors). GET list_sidecar_collectors List all collector backends (Filebeat, Winlogbeat, NXLog definitions). GET get_sidecar_collector Get a collector backend definition. POST create_sidecar_collector Create a new collector backend definition. PUT update_sidecar_collector Update a collector backend definition. DELETE delete_sidecar_collector Delete a collector backend definition. GET list_sidecar_configurations List all sidecar configurations (collector config templates). GET get_sidecar_configuration Get a sidecar configuration. POST create_sidecar_configuration Create a sidecar configuration. PUT update_sidecar_configuration Update a sidecar configuration. DELETE delete_sidecar_configuration Delete a sidecar configuration. GET list_blacklist_filters List all message blacklist filters. GET get_blacklist_filter Get a single blacklist filter. POST create_blacklist_filter Create a blacklist filter to drop matching messages. PUT update_blacklist_filter Update a blacklist filter. DELETE delete_blacklist_filter Delete a blacklist filter. GET get_system Get system overview: node ID, hostname, version, lifecycle, LB status, timezone, OS info. GET get_system_stats Get node statistics (JVM memory, OS, process info). GET get_throughput Get current message throughput (messages per second). GET get_total_message_count Get the total number of messages stored. GET list_message_fields List all known message field names across all indices. GET list_system_permissions List all available system permission strings. POST pause_processing Pause message processing on this node. Messages will queue in the journal. POST resume_processing Resume message processing on this node. GET get_message_processor_config Get message processor ordering and configuration. PUT update_message_processor_config Update message processor ordering. GET get_journal Get journal (disk buffer) information: size, segments, uncommitted entries. GET get_lb_status Get the load balancer status (ALIVE or DEAD). Used by LB health checks. PUT override_lb_status Override the load balancer status. status must be ALIVE or DEAD. GET list_metrics List all internal metrics (JVM, processing, indexing, etc.). GET get_metric Get a specific metric by its full name. GET list_metric_names List all metric names. GET get_metrics_by_namespace Get all metrics in a namespace (e.g. org.graylog2.throughput). POST get_multiple_metrics Get multiple metrics at once by their names. GET list_system_notifications List system notifications (warnings about configuration issues, index problems, etc.). DELETE dismiss_system_notification Dismiss a system notification. GET list_loggers List all internal loggers and their current log levels. GET list_logger_subsystems List logger subsystems (high-level components with adjustable levels). PUT set_logger_level Set the log level for a specific logger. Levels: TRACE, DEBUG, INFO, WARN, ERROR. PUT set_subsystem_logger_level Set the log level for a logger subsystem. GET list_system_jobs List all running and completed system jobs. GET get_system_job Get a system job by ID. DELETE cancel_system_job Cancel a running system job. GET list_plugins List all installed plugins with name, version, author, and URL. POST create_session Create a session (login). Returns session_id and valid_until. For session-based auth: username=session_id, password="session".
DELETE terminate_session Terminate a session (logout). GET get_cluster_config Get a cluster-wide configuration by class name. PUT update_cluster_config Update a cluster-wide configuration. DELETE delete_cluster_config Delete a cluster-wide configuration (reset to default). GET get_cluster Get system overview of all cluster nodes. GET list_cluster_input_states Get input states across all cluster nodes. GET list_cluster_jobs List running system jobs across all cluster nodes. POST get_cluster_metrics Get multiple metrics across all cluster nodes. GET get_cluster_node_jvm Get JVM information for a specific cluster node. GET get_cluster_node_journal Get journal info for a specific cluster node. GET get_cluster_node_thread_dump Get a thread dump for a specific cluster node. POST pause_cluster_node_processing Pause message processing on a specific cluster node. POST resume_cluster_node_processing Resume message processing on a specific cluster node. GET list_sources List active message sources with their message counts within the given relative time window. NOTE: requires base_url that ends with /api -- if backends.yaml has url: 'https://host' (no /api), this endpoint returns the web UI HTML instead of JSON. Verify with get_system first when in doubt.
GET list_all_alerts List recent alerts across all streams. GET list_all_alerts_paginated List alerts across all streams with pagination. GET list_stream_alerts List alerts for a specific stream. GET get_alert Get a specific alert. Composites (6) ⚠ contains code
FN aggregate_by_field Top-N values for a single field within a time window. Returns [{key, count}] sorted desc. Server-side replacement for the deprecated search_relative_terms / search_absolute_terms endpoints (removed in Graylog 6.0). time_range is one of:
{type:"absolute", from, to}
{type:"relative", range}
{type:"keyword", keyword}
FN aggregate_pivot Multi-dimensional pivot (e.g. source x level). row_fields and column_fields are arrays of field names. Returns flat array of {row_keys, col_keys, count}. The canonical replacement for the Source x Level forensic matrix workflow.
FN histogram_grouped Time-series histogram, optionally grouped by a field. interval is an ISO-8601 timeunit string (PT30S, PT1M, PT1H, P1D). Returns [{bucket_start, group_key|null, count}].
FN field_stats count, min, max, mean, cardinality for a numeric field. Replaces the removed _stats endpoints. FN search_messages_compact Search returning only {ts, src, lvl, msg} per message -- ~80 bytes/msg instead of ~500. Offset/limit pagination (Graylog's Views API does not support search_after on the messages search-type). Pass the next_offset returned by the previous call to fetch the next page.
FN incident_window Forensic snapshot for a service-incident window. Returns {window, pivot_source_level, top_errors, baseline_pivot}. timestamp is ISO-8601, window_minutes default 6 (i.e. +/- 3 min). baseline_pivot covers the same-length window 1 hour earlier for comparison.