Etcd Lease API

openapi: 3.2.0
info:
  title: etcd HTTP Gateway Auth Lease 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
servers:
- url: http://{host}:{port}/v3
  description: etcd gRPC Gateway
  variables:
    host:
      default: localhost
    port:
      default: '2379'
security:
- bearerAuth: []
tags:
- name: Lease
  description: Lease management for TTL-based key expiration
paths:
  /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'
components:
  schemas:
    Error:
      type: object
      description: Error response from the etcd API
      properties:
        error:
          type: string
          description: Human-readable error message
        code:
          type: integer
          description: gRPC status code for the error
        message:
          type: string
          description: Detailed error message
    LeaseKeepAliveRequest:
      type: object
      description: Request to renew a lease
      required:
      - ID
      properties:
        ID:
          type: string
          description: ID of the lease to renew
    LeaseTimeToLiveResponse:
      type: object
      description: Response from a lease TTL query
      properties:
        header:
          $ref: '#/components/schemas/ResponseHeader'
        ID:
          type: string
          description: ID of the lease
        TTL:
          type: string
          description: Remaining TTL in seconds for the lease
        grantedTTL:
          type: string
          description: Initial TTL in seconds that was granted to the lease
        keys:
          type: array
          description: Keys attached to the lease when the keys option was requested
          items:
            type: string
    LeaseGrantRequest:
      type: object
      description: Request to create a new lease
      required:
      - TTL
      properties:
        TTL:
          type: string
          description: Time-to-live in seconds for the lease
        ID:
          type: string
          description: User-specified lease ID. Set to 0 to let etcd assign the ID automatically.
    LeaseGrantResponse:
      type: object
      description: Response from a lease grant operation
      properties:
        header:
          $ref: '#/components/schemas/ResponseHeader'
        ID:
          type: string
          description: Lease ID assigned to the new lease
        TTL:
          type: string
          description: Actual TTL in seconds granted to the lease
        error:
          type: string
          description: Error message if the lease grant failed
    LeaseKeepAliveResponse:
      type: object
      description: Response from a lease keepalive operation
      properties:
        header:
          $ref: '#/components/schemas/ResponseHeader'
        ID:
          type: string
          description: ID of the renewed lease
        TTL:
          type: string
          description: Remaining TTL in seconds after the renewal
    LeaseRevokeResponse:
      type: object
      description: Response from a lease revoke operation
      properties:
        header:
          $ref: '#/components/schemas/ResponseHeader'
    ResponseHeader:
      type: object
      description: Header included in every etcd response containing cluster metadata and the revision at which the response was generated.
      properties:
        cluster_id:
          type: string
          description: ID of the etcd cluster
        member_id:
          type: string
          description: ID of the member that generated the response
        revision:
          type: string
          description: Key-value store revision at the time of the response
        raft_term:
          type: string
          description: Raft term at the time of the response
    LeaseLeasesResponse:
      type: object
      description: Response from a list leases operation
      properties:
        header:
          $ref: '#/components/schemas/ResponseHeader'
        leases:
          type: array
          description: List of active leases
          items:
            type: object
            description: A lease status entry
            properties:
              ID:
                type: string
                description: Lease ID
    LeaseTimeToLiveRequest:
      type: object
      description: Request to get the TTL of a lease
      required:
      - ID
      properties:
        ID:
          type: string
          description: ID of the lease to query
        keys:
          type: boolean
          description: When true, returns all keys attached to the lease
    LeaseRevokeRequest:
      type: object
      description: Request to revoke an existing lease
      required:
      - ID
      properties:
        ID:
          type: string
          description: ID of the lease to revoke
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from the /auth/authenticate endpoint. Include in the Authorization header as "Bearer {token}".
externalDocs:
  description: etcd gRPC Gateway Documentation
  url: https://etcd.io/docs/v3.5/dev-guide/api_grpc_gateway/