consul/website/content/api-docs/event.mdx

---
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](/consul/api-docs/features/blocking),
[consistency modes](/consul/api-docs/features/consistency),
[agent caching](/consul/api-docs/features/caching), and
[required ACLs](/consul/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`](/consul/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](/consul/commands/event) works, each
agent may have a different view of the events. Events are broadcast using the
[gossip protocol](/consul/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](/consul/api-docs/features/blocking),
[consistency modes](/consul/api-docs/features/consistency),
[agent caching](/consul/api-docs/features/caching), and
[required ACLs](/consul/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](/consul/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.