--- layout: api page_title: Events - HTTP API description: |- The /event endpoints fire new events and to query the available events in Consul. --- # Event HTTP Endpoint The `/event` endpoints fire new events and to query the available events in Consul. ## Fire Event This endpoint triggers a new user event. | Method | Path | Produces | | ------ | ------------------- | ------------------ | | `PUT` | `/event/fire/:name` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api-docs/features/blocking), [consistency modes](/api-docs/features/consistency), [agent caching](/api-docs/features/caching), and [required ACLs](/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------- | | `NO` | `none` | `none` | `event:write` | The corresponding CLI command is [`consul event`](/commands/event). ### Path Parameters - `name` `(string: <required>)` - Specifies the name of the event to fire. This name must not start with an underscore, since those are reserved for Consul internally. ### Query Parameters - `dc` `(string: "")` - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. - `node` `(string: "")` - Specifies a regular expression to filter by node name. - `service` `(string: "")` - Specifies a regular expression to filter by service name. - `tag` `(string: "")` - Specifies a regular expression to filter by tag. ### Sample Payload The body contents are opaque to Consul and become the "payload" that is passed onto the receiver of the event. ```text Lorem ipsum dolor sit amet, consectetur adipisicing elit... ``` ### Sample Request ```shell-session $ curl \ --request PUT \ --data @payload \ http://127.0.0.1:8500/v1/event/fire/my-event ``` ### Sample Response ```json { "ID": "b54fe110-7af5-cafc-d1fb-afc8ba432b1c", "Name": "deploy", "Payload": null, "NodeFilter": "", "ServiceFilter": "", "TagFilter": "", "Version": 1, "LTime": 0 } ``` - `ID` is a unique identifier the newly fired event ## List Events This endpoint returns the most recent events (up to 256) known by the agent. As a consequence of how the [event command](/commands/event) works, each agent may have a different view of the events. Events are broadcast using the [gossip protocol](/docs/architecture/gossip), so they have no global ordering nor do they make a promise of delivery. @include 'http_api_results_filtered_by_acls.mdx' | Method | Path | Produces | | ------ | ------------- | ------------------ | | `GET` | `/event/list` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api-docs/features/blocking), [consistency modes](/api-docs/features/consistency), [agent caching](/api-docs/features/caching), and [required ACLs](/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `YES` | `none` | `none` | `event:read` | ### Query Parameters - `name` `(string: "")` - Specifies the name of the event to filter. - `node` `(string: "")` - Specifies a regular expression to filter by node name. - `service` `(string: "")` - Specifies a regular expression to filter by service name. - `tag` `(string: "")` - Specifies a regular expression to filter by tag. ### Sample Request ```shell-session $ curl \ http://127.0.0.1:8500/v1/event/list ``` ### Sample Response ```json [ { "ID": "b54fe110-7af5-cafc-d1fb-afc8ba432b1c", "Name": "deploy", "Payload": "MTYwOTAzMA==", "NodeFilter": "", "ServiceFilter": "", "TagFilter": "", "Version": 1, "LTime": 19 } ] ``` ### Caveat The semantics of this endpoint's blocking queries are slightly different. Most blocking queries provide a monotonic index and block until a newer index is available. This can be supported as a consequence of the total ordering of the [consensus protocol](/docs/architecture/consensus). With gossip, there is no ordering, and instead `X-Consul-Index` maps to the newest event that matches the query. In practice, this means the index is only useful when used against a single agent and has no meaning globally. Because Consul defines the index as being opaque, clients should not be expecting a natural ordering either.