list.yaml

openapi: 3.1.0
info:
  title: OpenSearch List API
  description: OpenSearch List API.
  version: 1.0.0
paths:
  /_list:
    get:
      operationId: list.help.0
      x-operation-group: list.help
      x-version-added: '2.18'
      description: Returns help for the List APIs.
      externalDocs:
        url: https://opensearch.org/docs/latest/api-reference/list/index/
      responses:
        '200':
          $ref: '#/components/responses/list.help@200'
  /_list/indices:
    get:
      operationId: list.indices.0
      x-operation-group: list.indices
      x-version-added: '2.18'
      description: Returns paginated information about indexes including number of primaries and replicas, document counts, disk size.
      externalDocs:
        url: https://opensearch.org/docs/latest/api-reference/list/list-indices/
      parameters:
        - $ref: '#/components/parameters/list.indices::query.bytes'
        - $ref: '#/components/parameters/list.indices::query.cluster_manager_timeout'
        - $ref: '#/components/parameters/list.indices::query.expand_wildcards'
        - $ref: '#/components/parameters/list.indices::query.format'
        - $ref: '#/components/parameters/list.indices::query.h'
        - $ref: '#/components/parameters/list.indices::query.health'
        - $ref: '#/components/parameters/list.indices::query.help'
        - $ref: '#/components/parameters/list.indices::query.include_unloaded_segments'
        - $ref: '#/components/parameters/list.indices::query.local'
        - $ref: '#/components/parameters/list.indices::query.master_timeout'
        - $ref: '#/components/parameters/list.indices::query.next_token'
        - $ref: '#/components/parameters/list.indices::query.pri'
        - $ref: '#/components/parameters/list.indices::query.s'
        - $ref: '#/components/parameters/list.indices::query.size'
        - $ref: '#/components/parameters/list.indices::query.sort'
        - $ref: '#/components/parameters/list.indices::query.time'
        - $ref: '#/components/parameters/list.indices::query.v'
      responses:
        '200':
          $ref: '#/components/responses/list.indices@200'
  /_list/indices/{index}:
    get:
      operationId: list.indices.1
      x-operation-group: list.indices
      x-version-added: '2.18'
      description: Returns paginated information about indexes including number of primaries and replicas, document counts, disk size.
      externalDocs:
        url: https://opensearch.org/docs/latest/api-reference/list/list-indices/
      parameters:
        - $ref: '#/components/parameters/list.indices::path.index'
        - $ref: '#/components/parameters/list.indices::query.bytes'
        - $ref: '#/components/parameters/list.indices::query.cluster_manager_timeout'
        - $ref: '#/components/parameters/list.indices::query.expand_wildcards'
        - $ref: '#/components/parameters/list.indices::query.format'
        - $ref: '#/components/parameters/list.indices::query.h'
        - $ref: '#/components/parameters/list.indices::query.health'
        - $ref: '#/components/parameters/list.indices::query.help'
        - $ref: '#/components/parameters/list.indices::query.include_unloaded_segments'
        - $ref: '#/components/parameters/list.indices::query.local'
        - $ref: '#/components/parameters/list.indices::query.master_timeout'
        - $ref: '#/components/parameters/list.indices::query.next_token'
        - $ref: '#/components/parameters/list.indices::query.pri'
        - $ref: '#/components/parameters/list.indices::query.s'
        - $ref: '#/components/parameters/list.indices::query.size'
        - $ref: '#/components/parameters/list.indices::query.sort'
        - $ref: '#/components/parameters/list.indices::query.time'
        - $ref: '#/components/parameters/list.indices::query.v'
      responses:
        '200':
          $ref: '#/components/responses/list.indices@200'
  /_list/shards:
    get:
      operationId: list.shards.0
      x-operation-group: list.shards
      x-version-added: '2.18'
      description: Returns paginated details of shard allocation on nodes.
      externalDocs:
        url: https://opensearch.org/docs/latest/api-reference/list/list-shards/
      parameters:
        - $ref: '#/components/parameters/list.shards::query.bytes'
        - $ref: '#/components/parameters/list.shards::query.cluster_manager_timeout'
        - $ref: '#/components/parameters/list.shards::query.format'
        - $ref: '#/components/parameters/list.shards::query.h'
        - $ref: '#/components/parameters/list.shards::query.help'
        - $ref: '#/components/parameters/list.shards::query.local'
        - $ref: '#/components/parameters/list.shards::query.master_timeout'
        - $ref: '#/components/parameters/list.shards::query.next_token'
        - $ref: '#/components/parameters/list.shards::query.s'
        - $ref: '#/components/parameters/list.shards::query.size'
        - $ref: '#/components/parameters/list.shards::query.sort'
        - $ref: '#/components/parameters/list.shards::query.time'
        - $ref: '#/components/parameters/list.shards::query.v'
      responses:
        '200':
          $ref: '#/components/responses/list.shards@200'
  /_list/shards/{index}:
    get:
      operationId: list.shards.1
      x-operation-group: list.shards
      x-version-added: '2.18'
      description: Returns paginated details of shard allocation on nodes.
      externalDocs:
        url: https://opensearch.org/docs/latest/api-reference/list/list-shards/
      parameters:
        - $ref: '#/components/parameters/list.shards::path.index'
        - $ref: '#/components/parameters/list.shards::query.bytes'
        - $ref: '#/components/parameters/list.shards::query.cluster_manager_timeout'
        - $ref: '#/components/parameters/list.shards::query.format'
        - $ref: '#/components/parameters/list.shards::query.h'
        - $ref: '#/components/parameters/list.shards::query.help'
        - $ref: '#/components/parameters/list.shards::query.local'
        - $ref: '#/components/parameters/list.shards::query.master_timeout'
        - $ref: '#/components/parameters/list.shards::query.next_token'
        - $ref: '#/components/parameters/list.shards::query.s'
        - $ref: '#/components/parameters/list.shards::query.size'
        - $ref: '#/components/parameters/list.shards::query.sort'
        - $ref: '#/components/parameters/list.shards::query.time'
        - $ref: '#/components/parameters/list.shards::query.v'
      responses:
        '200':
          $ref: '#/components/responses/list.shards@200'
components:
  responses:
    list.help@200:
      content:
        text/plain:
          schema:
            type: string
    list.indices@200:
      content:
        text/plain:
          schema:
            type: string
        application/json:
          schema:
            type: object
            properties:
              next_token:
                type: ['null', string]
              indices:
                type: array
                items:
                  $ref: '../schemas/cat.indices.yaml#/components/schemas/IndicesRecord'
        application/yaml:
          schema:
            type: object
            properties:
              next_token:
                type: ['null', string]
              indices:
                type: array
                items:
                  $ref: '../schemas/cat.indices.yaml#/components/schemas/IndicesRecord'
        application/cbor:
          schema:
            type: object
            properties:
              next_token:
                type: ['null', string]
              indices:
                type: array
                items:
                  $ref: '../schemas/cat.indices.yaml#/components/schemas/IndicesRecord'
        application/smile:
          schema:
            type: object
            properties:
              next_token:
                type: ['null', string]
              indices:
                type: array
                items:
                  $ref: '../schemas/cat.indices.yaml#/components/schemas/IndicesRecord'
    list.shards@200:
      content:
        text/plain:
          schema:
            type: string
        application/json:
          schema:
            type: object
            properties:
              next_token:
                type: ['null', string]
              shards:
                type: array
                items:
                  $ref: '../schemas/cat.shards.yaml#/components/schemas/ShardsRecord'
        application/yaml:
          schema:
            type: object
            properties:
              next_token:
                type: ['null', string]
              shards:
                type: array
                items:
                  $ref: '../schemas/cat.shards.yaml#/components/schemas/ShardsRecord'
        application/cbor:
          schema:
            type: object
            properties:
              next_token:
                type: ['null', string]
              shards:
                type: array
                items:
                  $ref: '../schemas/cat.shards.yaml#/components/schemas/ShardsRecord'
        application/smile:
          schema:
            type: object
            properties:
              next_token:
                type: ['null', string]
              shards:
                type: array
                items:
                  $ref: '../schemas/cat.shards.yaml#/components/schemas/ShardsRecord'
  parameters:
    list.indices::path.index:
      in: path
      name: index
      description: |-
        Comma-separated list of data streams, indexes, and aliases used to limit the request.
        Supports wildcards (`*`). To target all data streams and indexes, omit this parameter or use `*` or `_all`.
      required: true
      schema:
        $ref: '../schemas/_common.yaml#/components/schemas/Indices'
      style: simple
    list.indices::query.bytes:
      in: query
      name: bytes
      description: The unit used to display byte values.
      schema:
        $ref: '../schemas/_common.yaml#/components/schemas/ByteUnit'
      style: form
    list.indices::query.cluster_manager_timeout:
      name: cluster_manager_timeout
      in: query
      description: Operation timeout for connection to cluster-manager node.
      schema:
        $ref: '../schemas/_common.yaml#/components/schemas/Duration'
      x-version-added: '2.0'
    list.indices::query.expand_wildcards:
      in: query
      name: expand_wildcards
      description: The type of index that wildcard patterns can match.
      schema:
        $ref: '../schemas/_common.yaml#/components/schemas/ExpandWildcards'
      style: form
    list.indices::query.format:
      name: format
      in: query
      description: A short version of the Accept header, such as `JSON`, `YAML`.
      schema:
        type: string
        description: A short version of the Accept header, such as `JSON`, `YAML`.
    list.indices::query.h:
      name: h
      in: query
      description: Comma-separated list of column names to display.
      style: form
      schema:
        type: array
        items:
          type: string
        description: Comma-separated list of column names to display.
      explode: true
    list.indices::query.health:
      in: query
      name: health
      description: The health status used to limit returned indexes. By default, the response includes indexes of any health status.
      schema:
        $ref: '../schemas/_common.yaml#/components/schemas/HealthStatus'
      style: form
    list.indices::query.help:
      name: help
      in: query
      description: Return help information.
      schema:
        type: boolean
        default: false
        description: Return help information.
    list.indices::query.include_unloaded_segments:
      in: query
      name: include_unloaded_segments
      description: If `true`, the response includes information from segments that are not loaded into memory.
      schema:
        type: boolean
        default: false
      style: form
    list.indices::query.local:
      name: local
      in: query
      description: Return local information, do not retrieve the state from cluster-manager node.
      schema:
        type: boolean
        default: false
        description: Return local information, do not retrieve the state from cluster-manager node.
    list.indices::query.master_timeout:
      name: master_timeout
      in: query
      description: Operation timeout for connection to cluster-manager node.
      schema:
        $ref: '../schemas/_common.yaml#/components/schemas/Duration'
      x-version-deprecated: '2.0'
      x-deprecation-message: To promote inclusive language, use `cluster_manager_timeout` instead.
      deprecated: true
    list.indices::query.pri:
      in: query
      name: pri
      description: If `true`, the response only includes information from primary shards.
      schema:
        type: boolean
        default: false
      style: form
    list.indices::query.s:
      name: s
      in: query
      description: Comma-separated list of column names or column aliases to sort by.
      style: form
      schema:
        type: array
        items:
          type: string
        description: Comma-separated list of column names or column aliases to sort by.
      explode: true
    list.indices::query.time:
      in: query
      name: time
      description: The unit used to display time values.
      schema:
        $ref: '../schemas/_common.yaml#/components/schemas/TimeUnit'
      style: form
    list.indices::query.v:
      name: v
      in: query
      description: Verbose mode. Display column headers.
      schema:
        type: boolean
        default: false
        description: Verbose mode. Display column headers.
    list.indices::query.next_token:
      name: next_token
      in: query
      description: Token to retrieve next page of indexes.
      schema:
        type: ['null', string]
        description: Token to retrieve next page of indexes.
    list.indices::query.size:
      name: size
      in: query
      description: Maximum number of indexes to be displayed in a page.
      schema:
        type: integer
        format: int32 
    list.indices::query.sort:
      name: sort
      in: query
      description: Defines order in which indexes will be displayed. Accepted values are `asc` and `desc`. If `desc`, most recently created indexes would be displayed first.
      schema:
        type: string
        enum:
          - asc
          - desc
    list.shards::path.index:
      in: path
      name: index
      description: |-
        A comma-separated list of data streams, indexes, and aliases used to limit the request.
        Supports wildcards (`*`).
        To target all data streams and indexes, omit this parameter or use `*` or `_all`.
      required: true
      schema:
        $ref: '../schemas/_common.yaml#/components/schemas/Indices'
      style: simple
    list.shards::query.bytes:
      in: query
      name: bytes
      description: The unit used to display byte values.
      schema:
        $ref: '../schemas/_common.yaml#/components/schemas/ByteUnit'
      style: form
    list.shards::query.cluster_manager_timeout:
      name: cluster_manager_timeout
      in: query
      description: Operation timeout for connection to cluster-manager node.
      schema:
        $ref: '../schemas/_common.yaml#/components/schemas/Duration'
      x-version-added: '2.0'
    list.shards::query.format:
      name: format
      in: query
      description: A short version of the Accept header, such as `JSON`, `YAML`.
      schema:
        type: string
        description: A short version of the Accept header, such as `JSON`, `YAML`.
    list.shards::query.h:
      name: h
      in: query
      description: Comma-separated list of column names to display.
      style: form
      schema:
        type: array
        items:
          type: string
        description: Comma-separated list of column names to display.
      explode: true
    list.shards::query.help:
      name: help
      in: query
      description: Return help information.
      schema:
        type: boolean
        default: false
        description: Return help information.
    list.shards::query.local:
      name: local
      in: query
      description: Return local information, do not retrieve the state from cluster-manager node.
      schema:
        type: boolean
        default: false
        description: Return local information, do not retrieve the state from cluster-manager node.
    list.shards::query.master_timeout:
      name: master_timeout
      in: query
      description: Operation timeout for connection to cluster-manager node.
      schema:
        $ref: '../schemas/_common.yaml#/components/schemas/Duration'
      x-version-deprecated: '2.0'
      x-deprecation-message: To promote inclusive language, use `cluster_manager_timeout` instead.
      deprecated: true
    list.shards::query.s:
      name: s
      in: query
      description: Comma-separated list of column names or column aliases to sort by.
      style: form
      schema:
        type: array
        items:
          type: string
        description: Comma-separated list of column names or column aliases to sort by.
      explode: true
    list.shards::query.time:
      name: time
      in: query
      description: The unit in which to display time values.
      schema:
        $ref: '../schemas/_common.yaml#/components/schemas/TimeUnit'
    list.shards::query.v:
      name: v
      in: query
      description: Verbose mode. Display column headers.
      schema:
        type: boolean
        default: false
        description: Verbose mode. Display column headers.
    list.shards::query.next_token:
      name: next_token
      in: query
      description: Token to retrieve next page of shards.
      schema:
        type: ['null', string]
        description: Token to retrieve next page of shards.
    list.shards::query.size:
      name: size
      in: query
      description: Maximum number of shards to be displayed in a page.
      schema:
        type: integer
        format: int32 
    list.shards::query.sort:
      name: sort
      in: query
      description: Defines order in which shards will be displayed. Accepted values are `asc` and `desc`. If `desc`, most recently created shards would be displayed first.
      schema:
        type: string
        enum:
          - asc
          - desc