AWS Kinesis #X Amz Target=Kinesis 20131202.ListShards API

openapi: 3.2.0
info:
  version: 2013-12-02
  x-release: v4
  title: 'Amazon Kinesis #X Amz Target=Kinesis 20131202.ListShards API'
  description: <fullname>Amazon Kinesis Data Streams Service API Reference</fullname> <p>Amazon Kinesis Data Streams is a managed service that scales elastically for real-time processing of streaming big data.</p>
  x-logo:
    url: https://api.apis.guru/v2/cache/logo/https_twitter.com_awscloud_profile_image.png
    backgroundColor: '#FFFFFF'
  termsOfService: https://aws.amazon.com/service-terms/
  contact:
    name: Mike Ralphson
    email: mike.ralphson@gmail.com
    url: https://github.com/mermade/aws2openapi
    x-twitter: PermittedSoc
  license:
    name: Apache 2.0 License
    url: http://www.apache.org/licenses/
  x-providerName: amazonaws.com
  x-serviceName: kinesis
  x-origin:
  - contentType: application/json
    url: https://raw.githubusercontent.com/aws/aws-sdk-js/master/apis/kinesis-2013-12-02.normal.json
    converter:
      url: https://github.com/mermade/aws2openapi
      version: 1.0.0
    x-apisguru-driver: external
  x-apiClientRegistration:
    url: https://portal.aws.amazon.com/gp/aws/developer/registration/index.html?nc2=h_ct
  x-apisguru-categories:
  - cloud
  x-preferred: true
servers:
- url: http://kinesis.{region}.amazonaws.com
  variables:
    region:
      description: The AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - us-gov-west-1
      - us-gov-east-1
      - ca-central-1
      - eu-north-1
      - eu-west-1
      - eu-west-2
      - eu-west-3
      - eu-central-1
      - eu-south-1
      - af-south-1
      - ap-northeast-1
      - ap-northeast-2
      - ap-northeast-3
      - ap-southeast-1
      - ap-southeast-2
      - ap-east-1
      - ap-south-1
      - sa-east-1
      - me-south-1
      default: us-east-1
  description: The Kinesis multi-region endpoint
- url: https://kinesis.{region}.amazonaws.com
  variables:
    region:
      description: The AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - us-gov-west-1
      - us-gov-east-1
      - ca-central-1
      - eu-north-1
      - eu-west-1
      - eu-west-2
      - eu-west-3
      - eu-central-1
      - eu-south-1
      - af-south-1
      - ap-northeast-1
      - ap-northeast-2
      - ap-northeast-3
      - ap-southeast-1
      - ap-southeast-2
      - ap-east-1
      - ap-south-1
      - sa-east-1
      - me-south-1
      default: us-east-1
  description: The Kinesis multi-region endpoint
- url: http://kinesis.{region}.amazonaws.com.cn
  variables:
    region:
      description: The AWS region
      enum:
      - cn-north-1
      - cn-northwest-1
      default: cn-north-1
  description: The Kinesis endpoint for China (Beijing) and China (Ningxia)
- url: https://kinesis.{region}.amazonaws.com.cn
  variables:
    region:
      description: The AWS region
      enum:
      - cn-north-1
      - cn-northwest-1
      default: cn-north-1
  description: The Kinesis endpoint for China (Beijing) and China (Ningxia)
security:
- hmac: []
tags:
- name: '#X Amz Target=Kinesis 20131202.ListShards'
paths:
  /#X-Amz-Target=Kinesis_20131202.ListShards:
    parameters:
    - $ref: '#/components/parameters/X-Amz-Content-Sha256'
    - $ref: '#/components/parameters/X-Amz-Date'
    - $ref: '#/components/parameters/X-Amz-Algorithm'
    - $ref: '#/components/parameters/X-Amz-Credential'
    - $ref: '#/components/parameters/X-Amz-Security-Token'
    - $ref: '#/components/parameters/X-Amz-Signature'
    - $ref: '#/components/parameters/X-Amz-SignedHeaders'
    post:
      operationId: ListShards
      description: <p>Lists the shards in a stream and provides information about each shard. This operation has a limit of 1000 transactions per second per data stream.</p> <note> <p>When invoking this API, it is recommended you use the <code>StreamARN</code> input parameter rather than the <code>StreamName</code> input parameter.</p> </note> <p>This action does not list expired shards. For information about expired shards, see <a href="https://docs.aws.amazon.com/streams/latest/dev/kinesis-using-sdk-java-after-resharding.html#kinesis-using-sdk-java-resharding-data-routing">Data Routing, Data Persistence, and Shard State after a Reshard</a>. </p> <important> <p>This API is a new operation that is used by the Amazon Kinesis Client Library (KCL). If you have a fine-grained IAM policy that only allows specific operations, you must update your policy to allow calls to this API. For more information, see <a href="https://docs.aws.amazon.com/streams/latest/dev/controlling-access.html">Controlling Access to Amazon Kinesis Data Streams Resources Using IAM</a>.</p> </important>
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListShardsOutput'
        '480':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '481':
          description: InvalidArgumentException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgumentException'
        '482':
          description: LimitExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitExceededException'
        '483':
          description: ExpiredNextTokenException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpiredNextTokenException'
        '484':
          description: ResourceInUseException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceInUseException'
        '485':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListShardsInput'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - Kinesis_20131202.ListShards
      tags:
      - '#X Amz Target=Kinesis 20131202.ListShards'
components:
  schemas:
    ResourceNotFoundException: {}
    ShardId:
      type: string
      pattern: '[a-zA-Z0-9_.-]+'
      minLength: 1
      maxLength: 128
    SequenceNumberRange:
      type: object
      required:
      - StartingSequenceNumber
      properties:
        StartingSequenceNumber:
          allOf:
          - $ref: '#/components/schemas/SequenceNumber'
          - description: The starting sequence number for the range.
        EndingSequenceNumber:
          allOf:
          - $ref: '#/components/schemas/SequenceNumber'
          - description: The ending sequence number for the range. Shards that are in the OPEN state have an ending sequence number of <code>null</code>.
      description: The range of possible sequence numbers for the shard.
    ShardFilterType:
      type: string
      enum:
      - AFTER_SHARD_ID
      - AT_TRIM_HORIZON
      - FROM_TRIM_HORIZON
      - AT_LATEST
      - AT_TIMESTAMP
      - FROM_TIMESTAMP
    ExpiredNextTokenException: {}
    StreamName:
      type: string
      pattern: '[a-zA-Z0-9_.-]+'
      minLength: 1
      maxLength: 128
    AccessDeniedException: {}
    NextToken:
      type: string
      minLength: 1
      maxLength: 1048576
    ResourceInUseException: {}
    ListShardsInputLimit:
      type: integer
      minimum: 1
      maximum: 10000
    InvalidArgumentException: {}
    ShardFilter:
      type: object
      required:
      - Type
      properties:
        Type:
          allOf:
          - $ref: '#/components/schemas/ShardFilterType'
          - description: '<p>The shard type specified in the <code>ShardFilter</code> parameter. This is a required property of the <code>ShardFilter</code> parameter.</p> <p>You can specify the following valid values: </p> <ul> <li> <p> <code>AFTER_SHARD_ID</code> - the response includes all the shards, starting with the shard whose ID immediately follows the <code>ShardId</code> that you provided. </p> </li> <li> <p> <code>AT_TRIM_HORIZON</code> - the response includes all the shards that were open at <code>TRIM_HORIZON</code>.</p> </li> <li> <p> <code>FROM_TRIM_HORIZON</code> - (default), the response includes all the shards within the retention period of the data stream (trim to tip).</p> </li> <li> <p> <code>AT_LATEST</code> - the response includes only the currently open shards of the data stream.</p> </li> <li> <p> <code>AT_TIMESTAMP</code> - the response includes all shards whose start timestamp is less than or equal to the given timestamp and end timestamp is greater than or equal to the given timestamp or still open. </p> </li> <li> <p> <code>FROM_TIMESTAMP</code> - the response incldues all closed shards whose end timestamp is greater than or equal to the given timestamp and also all open shards. Corrected to <code>TRIM_HORIZON</code> of the data stream if <code>FROM_TIMESTAMP</code> is less than the <code>TRIM_HORIZON</code> value.</p> </li> </ul>'
        ShardId:
          allOf:
          - $ref: '#/components/schemas/ShardId'
          - description: The exclusive start <code>shardID</code> speified in the <code>ShardFilter</code> parameter. This property can only be used if the <code>AFTER_SHARD_ID</code> shard type is specified.
        Timestamp:
          allOf:
          - $ref: '#/components/schemas/Timestamp'
          - description: The timestamps specified in the <code>ShardFilter</code> parameter. A timestamp is a Unix epoch date with precision in milliseconds. For example, 2016-04-04T19:58:46.480-00:00 or 1459799926.480. This property can only be used if <code>FROM_TIMESTAMP</code> or <code>AT_TIMESTAMP</code> shard types are specified.
      description: The request parameter used to filter out the response of the <code>ListShards</code> API.
    ListShardsOutput:
      type: object
      properties:
        Shards:
          allOf:
          - $ref: '#/components/schemas/ShardList'
          - description: An array of JSON objects. Each object represents one shard and specifies the IDs of the shard, the shard's parent, and the shard that's adjacent to the shard's parent. Each object also contains the starting and ending hash keys and the starting and ending sequence numbers for the shard.
        NextToken:
          allOf:
          - $ref: '#/components/schemas/NextToken'
          - description: <p>When the number of shards in the data stream is greater than the default value for the <code>MaxResults</code> parameter, or if you explicitly specify a value for <code>MaxResults</code> that is less than the number of shards in the data stream, the response includes a pagination token named <code>NextToken</code>. You can specify this <code>NextToken</code> value in a subsequent call to <code>ListShards</code> to list the next set of shards. For more information about the use of this pagination token when calling the <code>ListShards</code> operation, see <a>ListShardsInput$NextToken</a>.</p> <important> <p>Tokens expire after 300 seconds. When you obtain a value for <code>NextToken</code> in the response to a call to <code>ListShards</code>, you have 300 seconds to use that value. If you specify an expired token in a call to <code>ListShards</code>, you get <code>ExpiredNextTokenException</code>.</p> </important>
    LimitExceededException: {}
    Timestamp:
      type: string
      format: date-time
    Shard:
      type: object
      required:
      - ShardId
      - HashKeyRange
      - SequenceNumberRange
      properties:
        ShardId:
          allOf:
          - $ref: '#/components/schemas/ShardId'
          - description: The unique identifier of the shard within the stream.
        ParentShardId:
          allOf:
          - $ref: '#/components/schemas/ShardId'
          - description: The shard ID of the shard's parent.
        AdjacentParentShardId:
          allOf:
          - $ref: '#/components/schemas/ShardId'
          - description: The shard ID of the shard adjacent to the shard's parent.
        HashKeyRange:
          allOf:
          - $ref: '#/components/schemas/HashKeyRange'
          - description: The range of possible hash key values for the shard, which is a set of ordered contiguous positive integers.
        SequenceNumberRange:
          allOf:
          - $ref: '#/components/schemas/SequenceNumberRange'
          - description: The range of possible sequence numbers for the shard.
      description: A uniquely identified group of data records in a Kinesis data stream.
    HashKeyRange:
      type: object
      required:
      - StartingHashKey
      - EndingHashKey
      properties:
        StartingHashKey:
          allOf:
          - $ref: '#/components/schemas/HashKey'
          - description: The starting hash key of the hash key range.
        EndingHashKey:
          allOf:
          - $ref: '#/components/schemas/HashKey'
          - description: The ending hash key of the hash key range.
      description: The range of possible hash key values for the shard, which is a set of ordered contiguous positive integers.
    ShardList:
      type: array
      items:
        $ref: '#/components/schemas/Shard'
    ListShardsInput:
      type: object
      title: ListShardsInput
      properties:
        StreamName:
          allOf:
          - $ref: '#/components/schemas/StreamName'
          - description: <p>The name of the data stream whose shards you want to list. </p> <p>You cannot specify this parameter if you specify the <code>NextToken</code> parameter.</p>
        NextToken:
          allOf:
          - $ref: '#/components/schemas/NextToken'
          - description: <p>When the number of shards in the data stream is greater than the default value for the <code>MaxResults</code> parameter, or if you explicitly specify a value for <code>MaxResults</code> that is less than the number of shards in the data stream, the response includes a pagination token named <code>NextToken</code>. You can specify this <code>NextToken</code> value in a subsequent call to <code>ListShards</code> to list the next set of shards.</p> <p>Don't specify <code>StreamName</code> or <code>StreamCreationTimestamp</code> if you specify <code>NextToken</code> because the latter unambiguously identifies the stream.</p> <p>You can optionally specify a value for the <code>MaxResults</code> parameter when you specify <code>NextToken</code>. If you specify a <code>MaxResults</code> value that is less than the number of shards that the operation returns if you don't specify <code>MaxResults</code>, the response will contain a new <code>NextToken</code> value. You can use the new <code>NextToken</code> value in a subsequent call to the <code>ListShards</code> operation.</p> <important> <p>Tokens expire after 300 seconds. When you obtain a value for <code>NextToken</code> in the response to a call to <code>ListShards</code>, you have 300 seconds to use that value. If you specify an expired token in a call to <code>ListShards</code>, you get <code>ExpiredNextTokenException</code>.</p> </important>
        ExclusiveStartShardId:
          allOf:
          - $ref: '#/components/schemas/ShardId'
          - description: <p>Specify this parameter to indicate that you want to list the shards starting with the shard whose ID immediately follows <code>ExclusiveStartShardId</code>.</p> <p>If you don't specify this parameter, the default behavior is for <code>ListShards</code> to list the shards starting with the first one in the stream.</p> <p>You cannot specify this parameter if you specify <code>NextToken</code>.</p>
        MaxResults:
          allOf:
          - $ref: '#/components/schemas/ListShardsInputLimit'
          - description: <p>The maximum number of shards to return in a single call to <code>ListShards</code>. The maximum number of shards to return in a single call. The default value is 1000. If you specify a value greater than 1000, at most 1000 results are returned. </p> <p>When the number of shards to be listed is greater than the value of <code>MaxResults</code>, the response contains a <code>NextToken</code> value that you can use in a subsequent call to <code>ListShards</code> to list the next set of shards.</p>
        StreamCreationTimestamp:
          allOf:
          - $ref: '#/components/schemas/Timestamp'
          - description: <p>Specify this input parameter to distinguish data streams that have the same name. For example, if you create a data stream and then delete it, and you later create another data stream with the same name, you can use this input parameter to specify which of the two streams you want to list the shards for.</p> <p>You cannot specify this parameter if you specify the <code>NextToken</code> parameter.</p>
        ShardFilter:
          allOf:
          - $ref: '#/components/schemas/ShardFilter'
          - description: <p>Enables you to filter out the response of the <code>ListShards</code> API. You can only specify one filter at a time. </p> <p>If you use the <code>ShardFilter</code> parameter when invoking the ListShards API, the <code>Type</code> is the required property and must be specified. If you specify the <code>AT_TRIM_HORIZON</code>, <code>FROM_TRIM_HORIZON</code>, or <code>AT_LATEST</code> types, you do not need to specify either the <code>ShardId</code> or the <code>Timestamp</code> optional properties. </p> <p>If you specify the <code>AFTER_SHARD_ID</code> type, you must also provide the value for the optional <code>ShardId</code> property. The <code>ShardId</code> property is identical in fuctionality to the <code>ExclusiveStartShardId</code> parameter of the <code>ListShards</code> API. When <code>ShardId</code> property is specified, the response includes the shards starting with the shard whose ID immediately follows the <code>ShardId</code> that you provided. </p> <p>If you specify the <code>AT_TIMESTAMP</code> or <code>FROM_TIMESTAMP_ID</code> type, you must also provide the value for the optional <code>Timestamp</code> property. If you specify the AT_TIMESTAMP type, then all shards that were open at the provided timestamp are returned. If you specify the FROM_TIMESTAMP type, then all shards starting from the provided timestamp to TIP are returned. </p>
        StreamARN:
          allOf:
          - $ref: '#/components/schemas/StreamARN'
          - description: The ARN of the stream.
    StreamARN:
      type: string
      pattern: arn:aws.*:kinesis:.*:\d{12}:stream/\S+
      minLength: 1
      maxLength: 2048
    SequenceNumber:
      type: string
      pattern: 0|([1-9]\d{0,128})
    HashKey:
      type: string
      pattern: 0|([1-9]\d{0,38})
  parameters:
    X-Amz-Security-Token:
      name: X-Amz-Security-Token
      in: header
      schema:
        type: string
      required: false
    X-Amz-SignedHeaders:
      name: X-Amz-SignedHeaders
      in: header
      schema:
        type: string
      required: false
    X-Amz-Credential:
      name: X-Amz-Credential
      in: header
      schema:
        type: string
      required: false
    X-Amz-Date:
      name: X-Amz-Date
      in: header
      schema:
        type: string
      required: false
    X-Amz-Algorithm:
      name: X-Amz-Algorithm
      in: header
      schema:
        type: string
      required: false
    X-Amz-Signature:
      name: X-Amz-Signature
      in: header
      schema:
        type: string
      required: false
    X-Amz-Content-Sha256:
      name: X-Amz-Content-Sha256
      in: header
      schema:
        type: string
      required: false
  securitySchemes:
    hmac:
      type: apiKey
      name: Authorization
      in: header
      description: Amazon Signature authorization v4
      x-amazon-apigateway-authtype: awsSigv4
externalDocs:
  description: Amazon Web Services documentation
  url: https://docs.aws.amazon.com/kinesis/
x-hasEquivalentPaths: true