etcd HTTP Gateway API

openapi: 3.1.0
info:
  title: etcd HTTP Gateway API
  description: >-
    The etcd HTTP/JSON gateway translates HTTP requests into gRPC calls, enabling
    clients without gRPC support to interact with the etcd v3 key-value store. The
    gateway exposes the full etcd v3 API surface including key-value operations
    (put, get, delete, range queries), watch streams for change notifications,
    lease management for TTL-based key expiration, cluster membership management,
    maintenance operations such as snapshots and defragmentation, and authentication
    and authorization controls. The gateway is served on port 2379 by default and
    accepts JSON-encoded request bodies that mirror the protobuf message structures
    of the underlying gRPC API.
  version: '3.5'
  contact:
    name: etcd Community
    url: https://etcd.io/community/
  termsOfService: https://github.com/etcd-io/etcd/blob/main/LICENSE
externalDocs:
  description: etcd gRPC Gateway Documentation
  url: https://etcd.io/docs/v3.5/dev-guide/api_grpc_gateway/
servers:
  - url: http://{host}:{port}/v3
    description: etcd gRPC Gateway
    variables:
      host:
        default: localhost
      port:
        default: '2379'
tags:
  - name: Auth
    description: Authentication and authorization management for users and roles
  - name: Cluster
    description: Cluster membership management including member add, remove, and list
  - name: KV
    description: Key-value store operations including put, get, delete, and range queries
  - name: Lease
    description: Lease management for TTL-based key expiration
  - name: Maintenance
    description: Maintenance operations including snapshots, defragmentation, and status
  - name: Watch
    description: Watch operations for streaming key change notifications
security:
  - bearerAuth: []
paths:
  /kv/put:
    post:
      operationId: kvPut
      summary: Etcd Put a key-value pair
      description: >-
        Stores a key-value pair in the etcd cluster. If the key already exists,
        the value is updated. Supports setting a lease ID to associate the key
        with a TTL-based lease that will delete the key when it expires. The
        prev_kv option returns the previous key-value pair before the update.
      tags:
        - KV
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutRequest'
      responses:
        '200':
          description: Key-value pair stored successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /kv/range:
    post:
      operationId: kvRange
      summary: Etcd Get a range of key-value pairs
      description: >-
        Retrieves key-value pairs from the etcd cluster. A single key can be
        fetched by specifying only the key field. A range of keys can be fetched
        by specifying both key and range_end. Setting range_end to the key plus
        one byte fetches all keys with the given prefix. The limit parameter
        controls the maximum number of results returned, and the revision
        parameter enables point-in-time queries against a specific store revision.
      tags:
        - KV
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RangeRequest'
      responses:
        '200':
          description: Key-value pairs retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RangeResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /kv/deleterange:
    post:
      operationId: kvDeleteRange
      summary: Etcd Delete a range of key-value pairs
      description: >-
        Deletes one or more key-value pairs from the etcd cluster. A single key
        can be deleted by specifying only the key field. A range of keys is deleted
        by specifying both key and range_end. The prev_kv option returns the deleted
        key-value pairs before deletion. The count-only option returns only the count
        of deleted keys without performing the actual deletion.
      tags:
        - KV
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteRangeRequest'
      responses:
        '200':
          description: Key-value pairs deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteRangeResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /kv/txn:
    post:
      operationId: kvTxn
      summary: Etcd Execute a transaction
      description: >-
        Executes an atomic compare-and-swap transaction against the etcd key-value
        store. A transaction consists of a set of compare conditions, a success
        branch of operations executed if all conditions are true, and a failure
        branch executed if any condition is false. Transactions are atomic and
        isolated, providing strong consistency guarantees within the etcd cluster.
      tags:
        - KV
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TxnRequest'
      responses:
        '200':
          description: Transaction executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TxnResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /kv/compaction:
    post:
      operationId: kvCompact
      summary: Etcd Compact the event history
      description: >-
        Compacts the etcd event history up to the given revision. All superseded
        keys with revisions less than the compaction revision are removed from the
        store, and watch operations cannot be made against compacted revisions. The
        physical option triggers a physical deletion of compacted keys immediately
        rather than deferring to the next compaction cycle.
      tags:
        - KV
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompactionRequest'
      responses:
        '200':
          description: Compaction completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompactionResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /watch:
    post:
      operationId: watchEvents
      summary: Etcd Watch for key change events
      description: >-
        Opens a streaming watch connection to receive notifications of key-value
        changes in the etcd cluster. Clients send WatchCreateRequest messages to
        subscribe to key ranges and WatchCancelRequest messages to unsubscribe.
        The server streams WatchResponse messages containing events that describe
        each key change including the event type (PUT or DELETE) and the updated
        key-value pair. Watches can be started from a specific revision to receive
        historical events.
      tags:
        - Watch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchRequest'
      responses:
        '200':
          description: Watch stream established
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /lease/grant:
    post:
      operationId: leaseGrant
      summary: Etcd Grant a lease
      description: >-
        Creates a new lease with the specified TTL in seconds. The returned lease
        ID can be attached to key-value pairs so they are automatically deleted
        when the lease expires. Clients must periodically renew the lease using
        the keepalive endpoint to prevent expiration. The ID field can be set to
        0 to allow etcd to assign a lease ID automatically.
      tags:
        - Lease
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeaseGrantRequest'
      responses:
        '200':
          description: Lease granted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaseGrantResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /lease/revoke:
    post:
      operationId: leaseRevoke
      summary: Etcd Revoke a lease
      description: >-
        Revokes an existing lease identified by its lease ID. When a lease is
        revoked, all keys attached to that lease are automatically deleted from
        the etcd cluster. This is useful for releasing distributed locks or
        invalidating all session-scoped keys at once.
      tags:
        - Lease
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeaseRevokeRequest'
      responses:
        '200':
          description: Lease revoked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaseRevokeResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /lease/keepalive:
    post:
      operationId: leaseKeepAlive
      summary: Etcd Renew a lease
      description: >-
        Renews an existing lease to prevent it from expiring. Clients must call
        this endpoint periodically with an interval shorter than the lease TTL to
        maintain the lease. The response returns the remaining TTL of the lease
        after the renewal. If the lease has already expired, an error is returned
        and a new lease must be granted.
      tags:
        - Lease
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeaseKeepAliveRequest'
      responses:
        '200':
          description: Lease renewed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaseKeepAliveResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /lease/timetolive:
    post:
      operationId: leaseTimeToLive
      summary: Etcd Get lease time to live
      description: >-
        Returns the remaining time-to-live and other information about a lease
        identified by its lease ID. When the keys option is set to true, the
        response also includes all keys attached to the lease. This endpoint is
        useful for monitoring lease health and understanding which keys will be
        deleted when the lease expires.
      tags:
        - Lease
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeaseTimeToLiveRequest'
      responses:
        '200':
          description: Lease TTL information retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaseTimeToLiveResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /lease/leases:
    post:
      operationId: leaseLeases
      summary: Etcd List all leases
      description: >-
        Returns a list of all active leases in the etcd cluster. The response
        includes the lease IDs of all leases but does not include detailed
        information such as TTL or attached keys. Use the timetolive endpoint
        to retrieve detailed information about a specific lease.
      tags:
        - Lease
      responses:
        '200':
          description: Lease list retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaseLeasesResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /cluster/member/add:
    post:
      operationId: clusterMemberAdd
      summary: Etcd Add a member to the cluster
      description: >-
        Adds a new member to the etcd cluster. The peer URLs of the new member
        must be provided. The new member starts in an unstarted state and is
        considered a learner until it catches up with the cluster's Raft log.
        The isLearner field can be set to true to explicitly add the member as
        a non-voting learner member.
      tags:
        - Cluster
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemberAddRequest'
      responses:
        '200':
          description: Member added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberAddResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /cluster/member/remove:
    post:
      operationId: clusterMemberRemove
      summary: Etcd Remove a member from the cluster
      description: >-
        Removes an existing member from the etcd cluster identified by its member
        ID. The removed member is immediately excluded from the cluster's Raft
        quorum. Removing a member that holds the leadership will trigger a new
        leader election. Care must be taken to maintain quorum when removing
        members from small clusters.
      tags:
        - Cluster
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemberRemoveRequest'
      responses:
        '200':
          description: Member removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberRemoveResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /cluster/member/update:
    post:
      operationId: clusterMemberUpdate
      summary: Etcd Update a cluster member
      description: >-
        Updates the peer URLs of an existing cluster member identified by its
        member ID. This is used when a cluster member's network address changes.
        The member must be reachable at the new URLs for the update to succeed.
        All other member properties are read-only and cannot be updated through
        this endpoint.
      tags:
        - Cluster
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemberUpdateRequest'
      responses:
        '200':
          description: Member updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberUpdateResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /cluster/member/list:
    post:
      operationId: clusterMemberList
      summary: Etcd List cluster members
      description: >-
        Returns a list of all members in the etcd cluster including their member
        IDs, names, peer URLs, client URLs, and whether they are learner members.
        The linearizable option controls whether the response is read from the
        cluster leader for the most up-to-date view of membership.
      tags:
        - Cluster
      responses:
        '200':
          description: Cluster member list retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /cluster/member/promote:
    post:
      operationId: clusterMemberPromote
      summary: Etcd Promote a learner member
      description: >-
        Promotes a learner (non-voting) member to a full voting member of the
        etcd cluster. The learner must be caught up with the cluster's Raft log
        before it can be promoted. This two-phase approach (add as learner, then
        promote) provides a safer way to grow clusters without temporarily
        reducing quorum availability.
      tags:
        - Cluster
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemberPromoteRequest'
      responses:
        '200':
          description: Learner member promoted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberPromoteResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maintenance/snapshot:
    post:
      operationId: maintenanceSnapshot
      summary: Etcd Stream a database snapshot
      description: >-
        Streams a point-in-time snapshot of the etcd database as a binary blob.
        The snapshot can be used to create a backup of the etcd data or to
        restore a cluster to a previous state. The snapshot is streamed in
        chunks to support large database sizes. This operation should be performed
        on a healthy cluster member to ensure consistency.
      tags:
        - Maintenance
      responses:
        '200':
          description: Database snapshot stream
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maintenance/defragment:
    post:
      operationId: maintenanceDefragment
      summary: Etcd Defragment a member's backend
      description: >-
        Defragments the storage backend of the etcd member that receives the
        request, reclaiming disk space from deleted keys. Defragmentation is an
        expensive operation that blocks the member from serving requests during
        the process. It should be performed during maintenance windows on
        individual members rather than on all cluster members simultaneously.
      tags:
        - Maintenance
      responses:
        '200':
          description: Defragmentation completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefragmentResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maintenance/status:
    post:
      operationId: maintenanceStatus
      summary: Etcd Get member status
      description: >-
        Returns the status of the etcd member that receives the request, including
        the cluster ID, member ID, Raft index, Raft term, Raft applied index, and
        whether the member is a learner. The leader field contains the member ID
        of the current cluster leader. This endpoint is useful for monitoring the
        health and state of individual cluster members.
      tags:
        - Maintenance
      responses:
        '200':
          description: Member status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maintenance/alarm:
    post:
      operationId: maintenanceAlarm
      summary: Etcd Manage cluster alarms
      description: >-
        Manages cluster-level alarms that indicate error conditions such as
        insufficient storage space (NOSPACE). Supports activating alarms,
        deactivating (disarming) alarms, and listing all active alarms. When
        a NOSPACE alarm is active, the cluster becomes read-only to prevent
        data loss. After addressing the underlying issue, the alarm must be
        explicitly deactivated to restore write access.
      tags:
        - Maintenance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlarmRequest'
      responses:
        '200':
          description: Alarm operation completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlarmResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /maintenance/hash:
    post:
      operationId: maintenanceHash
      summary: Etcd Get member backend hash
      description: >-
        Returns a hash of the etcd member's backend database. This hash can be
        used to verify data consistency across cluster members. If members report
        different hashes, it may indicate a data corruption issue. This endpoint
        is primarily used for debugging and consistency verification.
      tags:
        - Maintenance
      responses:
        '200':
          description: Backend hash retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HashResponse'
  /maintenance/transfer-leadership:
    post:
      operationId: maintenanceTransferLeadership
      summary: Etcd Transfer cluster leadership
      description: >-
        Transfers the Raft leadership from the current leader to the specified
        target member. This operation is useful during maintenance to gracefully
        move leadership away from a member that needs to be taken offline. The
        target member must be a healthy voting member of the cluster for the
        transfer to succeed.
      tags:
        - Maintenance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveLeaderRequest'
      responses:
        '200':
          description: Leadership transfer initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MoveLeaderResponse'
  /auth/enable:
    post:
      operationId: authEnable
      summary: Etcd Enable authentication
      description: >-
        Enables authentication on the etcd cluster. Before enabling authentication,
        a root user with root role must be created. Once authentication is enabled,
        all requests must include valid credentials. The root user has full access
        to all resources and can manage users and roles.
      tags:
        - Auth
      responses:
        '200':
          description: Authentication enabled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthEnableResponse'
  /auth/disable:
    post:
      operationId: authDisable
      summary: Etcd Disable authentication
      description: >-
        Disables authentication on the etcd cluster, allowing all clients to
        access the cluster without credentials. This operation requires root
        user authentication when auth is currently enabled. Disabling authentication
        removes all access controls and should only be performed in trusted
        network environments.
      tags:
        - Auth
      responses:
        '200':
          description: Authentication disabled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthDisableResponse'
  /auth/authenticate:
    post:
      operationId: authAuthenticate
      summary: Etcd Authenticate a user
      description: >-
        Authenticates a user with their username and password and returns a JWT
        token that can be used for subsequent authenticated requests. The token
        must be included in the Authorization header as a Bearer token. Tokens
        expire based on the cluster's configured token TTL and must be refreshed
        by calling this endpoint again.
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateRequest'
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticateResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /auth/user/add:
    post:
      operationId: authUserAdd
      summary: Etcd Add a user
      description: >-
        Creates a new user in the etcd authentication system with the specified
        username and password. Users can be assigned to roles which grant them
        permissions to access specific key ranges. The hashedPassword field can
        be used to provide a pre-hashed bcrypt password instead of a plaintext
        password.
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthUserAddRequest'
      responses:
        '200':
          description: User added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthUserAddResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /auth/user/get:
    post:
      operationId: authUserGet
      summary: Etcd Get user details
      description: >-
        Returns details about a specific user including their assigned roles.
        This endpoint requires root or appropriate administrative privileges.
        The password hash is not returned for security reasons.
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthUserGetRequest'
      responses:
        '200':
          description: User details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthUserGetResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /auth/user/delete:
    post:
      operationId: authUserDelete
      summary: Etcd Delete a user
      description: >-
        Deletes a user from the etcd authentication system. Deleting a user
        removes all of their role assignments. The root user cannot be deleted
        while authentication is enabled.
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthUserDeleteRequest'
      responses:
        '200':
          description: User deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthUserDeleteResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /auth/user/list:
    post:
      operationId: authUserList
      summary: Etcd List all users
      description: >-
        Returns a list of all usernames registered in the etcd authentication
        system. This endpoint requires root or administrative privileges. Use
        the user/get endpoint to retrieve detailed information including role
        assignments for a specific user.
      tags:
        - Auth
      responses:
        '200':
          description: User list retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthUserListResponse'
  /auth/user/changepw:
    post:
      operationId: authUserChangePassword
      summary: Etcd Change a user's password
      description: >-
        Changes the password of an existing user in the etcd authentication
        system. Non-root users can change their own password. Root or administrative
        users can change the password of any user. The hashedPassword field can
        be used to provide a pre-hashed bcrypt password.
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthUserChangePasswordRequest'
      responses:
        '200':
          description: Password changed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthUserChangePasswordResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /auth/user/grant:
    post:
      operationId: authUserGrantRole
      summary: Etcd Gran

# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/etcd/refs/heads/main/openapi/etcd-http-gateway-openapi.yml