Client Endpoints

Common parameters

dc:By default, the datacenter of the agent is queried ; however, the dc can be provided.
watch:Performs a blocking query. Value can be a ObjectIndex, or a Tuple[ObjectIndex, timedelta].
consistency:Change client behavior about consistency.
session:A session Object.
index:An index Object.
token:A token Object.

Most of endpoints that returns ConsulValue supports blocking queries and consistency modes.


Create, update, destroy, and query ACL tokens.

Most of the operations relies on ACL token with sufficant rights. Here is the way aioconsul manage tokens:

token = {"Name": "my-app-token"}
token_id = await client.acl.create(token)
token.update({"Rules": """
    key "" {
        policy = "read"
    key "private/" {
        policy = "deny"
token_id = await client.acl.update(token)

token, meta = await
clone_id, meta = await client.acl.clone(token_id)

destroyed = await client.acl.destroy(token_id)

tokens, meta = await client.acl.items()
info = await client.acl.replication()


Interact with the local Consul agent.


obj = await
disabled = await client.agent.disable(reason="migrating")
enabled = await client.agent.enable(reason="migration done")

Agent’s Checks

Manage local checks.


check = {
    "ID": "mem",
    "Name": "Memory utilization",
    "TTL": "15s"
    "Interval": "10s"
registered = await client.checks.register(check)
mapping = await client.checks.items()
marked = await client.checks.critical(check, note="Fatal")
marked = await client.checks.warning(check, note="Warning")
marked = await client.checks.passing(check, note="Back to normal")
deregistered = await client.checks.deregister(check)

Agent’s Members

Manage local serf agent cluster


joined = await client.checks.join("", wan=True)
members = await client.members.items()
leaving = await client.checks.force_leave("my-node")

Agent’s Services

Manage local services.


service = {
    "ID": "redis1",
    "Name": "redis",
    "Tags": [
registered = await
services = await
disabled = await, reason="migrating")
enabled = await, reason="migration done")
deregistered = await


Manage catalog.


definitions = {
  "Node": "foobar",
  "Address": "",
  "Service": {
    "ID": "redis1",
    "Service": "redis",
    "Tags": [ "master", "v1" ],
    "Address": "",
    "Port": 8000
  "Check": {
    "Node": "foobar",
    "CheckID": "service:redis1",
    "Name": "Redis health check",
    "Notes": "Script based health check",
    "Status": "passing",
    "ServiceID": "redis1"

registered = await client.catalog.register(definitions)
datacenters = await client.catalog.datacenters()
nodes, meta = await client.catalog.nodes(near="_self")
services, meta = await client.catalog.node("foobar", watch=(meta, "30s"))
services, meta = await"stale")
nodes, meta = await client.catalog.service("redis1", tag="prod")
deregistered = await client.catalog.deregister({
    "Node": "foobar",
    "Address": ""


Manage events.


id = await"my-event", service="my-service")
collection, meta = await client.event.items("my-event")

Health Checks

Consult health.


collection, meta = await"my-node")
collection, meta = await"my-service")
collection, meta = await"passing", near="_self")

Key/Value Store

Manage kv store.

Common operations example:

keys, meta = await client.kv.keys("my/key", separator="/")
setted = await client.kv.set("my/key", b"my value")
obj, meta = await client.kv.get("my/key")
deleted = await client.kv.delete("my/key")

Tree operations example:

collection, meta = await client.kv.get_tree("my/key", separator="/")
deleted = await client.kv.delete_tree("my/key", separator="/")

CAS operations example:

setted = await client.kv.cas("my/key", b"my value", index=meta)
deleted = await client.kv.delete_cas("my/key", index=meta)

Locked operations example:

locked = await client.kv.lock("my/key", b"my value", session=session_id)
unlocked = await client.kv.unlock("my/key", b"my value", session=session_id)

Key/Value Transactions

These same operations can be done in a transactional way:

results, meta = await client.kv.prepare()\
                        .set("my/key", b"my value")\

Network Coordinates

Consult network coordinates.


datacenters = await client.coordinate.datacenters()
collection, meta = await client.coordinate.nodes()


Manage raft.


obj = await client.operator.configuration()
obj = await client.operator.peer_delete("")

Prepared Queries

Manage prepared queries.


collection = await client.query.items()
obj = await client.query.create({""})
obj = await{""})
obj = await client.query.explain({""})
updated = await client.query.update({""})
deleted = await client.query.delete({""})
results = await client.query.execute({""})


Manage sessions.


obj = await client.session.create({""})
destroyed = await client.session.destroy({""})
obj, meta = await{""})
obj, meta = await client.session.renew({""})
collection, meta = await client.session.node("my-node")
collection, meta = await client.session.items()


Consult status.


addr = await client.status.leader()
addrs = await client.status.peers()