Amazon Systems Manager Systems Manager Parameter API

openapi: 3.2.0
info:
  title: Amazon Simple Systems Manager (SSM) Parameter API
  version: '2014-11-06'
  description: Generated from AWS's published Smithy model for Amazon Simple Systems Manager (SSM). 5 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://ssm.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Parameter
paths:
  /#DeleteParameter:
    post:
      operationId: DeleteParameter
      summary: Delete Parameter
      description: Delete a parameter from the system. After deleting a parameter, wait for at least 30 seconds to create a parameter with the same name.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DeleteParameterResult'
        '500':
          description: InternalServerError
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerError'
        '400':
          description: ParameterNotFound
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ParameterNotFound'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonSSM.DeleteParameter
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DeleteParameterRequest'
      tags:
      - Parameter
  /#DeleteParameters:
    post:
      operationId: DeleteParameters
      summary: Delete Parameters
      description: Delete a list of parameters. After deleting a parameter, wait for at least 30 seconds to create a parameter with the same name.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DeleteParametersResult'
        '500':
          description: InternalServerError
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonSSM.DeleteParameters
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DeleteParametersRequest'
      tags:
      - Parameter
  /#DescribeParameters:
    post:
      operationId: DescribeParameters
      summary: Describe Parameters
      description: Lists the parameters in your Amazon Web Services account or the parameters shared with you when you enable the Shared option. Request results are returned on a best-effort basis. If you specify MaxResults in the request, the response includes information up to the limit specified. The number of items returned, however, can be between zero and the value of MaxResults. If the service reaches an internal limit while processing the results, it stops the operation and returns the matching values up to that point and a NextToken. You can specify the NextToken in a subsequent call to get the next set of results. Parameter names can't contain spaces. The service removes any spaces specified for the beginning or end of a parameter name. If the specified name for a parameter contains spaces between characters, the request fails with a ValidationException error. If you change the KMS key alias for the KMS key used to encrypt a parameter, then you must also update the key alias the parameter uses to reference KMS. Otherwise, DescribeParameters retrieves whatever the original key alias was referencing.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DescribeParametersResult'
        '500':
          description: InternalServerError
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerError'
        '400':
          description: InvalidFilterKey; InvalidFilterOption; InvalidFilterValue; InvalidNextToken
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidFilterKey'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonSSM.DescribeParameters
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DescribeParametersRequest'
      tags:
      - Parameter
  /#GetParameters:
    post:
      operationId: GetParameters
      summary: Get Parameters
      description: Get information about one or more parameters by specifying multiple parameter names. To get information about a single parameter, you can use the GetParameter operation instead. Parameter names can't contain spaces. The service removes any spaces specified for the beginning or end of a parameter name. If the specified name for a parameter contains spaces between characters, the request fails with a ValidationException error. Parameter Store throughput defines the number of API transactions per second (TPS) that Systems Manager can process. This applies to GetParameter, GetParameters, and PutParameter API calls for your Amazon Web Services account and Amazon Web Services Region. By default, Parameter Store is configured with a standard throughput quota suitable for low- to moderate-volume workloads. Applications that retrieve configuration data infrequently or operate at smaller scale can use this default setting without additional cost. For higher-volume workloads, you can enable higher throughput. This increases the maximum number of supported transactions per second for your account and Region. Increased throughput supports applications and workloads that need concurrent access t
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/GetParametersResult'
        '500':
          description: InternalServerError
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerError'
        '400':
          description: InvalidKeyId
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidKeyId'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonSSM.GetParameters
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/GetParametersRequest'
      tags:
      - Parameter
  /#GetParametersByPath:
    post:
      operationId: GetParametersByPath
      summary: Get Parameters By Path
      description: Retrieve information about one or more parameters under a specified level in a hierarchy. Request results are returned on a best-effort basis. If you specify MaxResults in the request, the response includes information up to the limit specified. The number of items returned, however, can be between zero and the value of MaxResults. If the service reaches an internal limit while processing the results, it stops the operation and returns the matching values up to that point and a NextToken. You can specify the NextToken in a subsequent call to get the next set of results. Parameter names can't contain spaces. The service removes any spaces specified for the beginning or end of a parameter name. If the specified name for a parameter contains spaces between characters, the request fails with a ValidationException error.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/GetParametersByPathResult'
        '500':
          description: InternalServerError
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerError'
        '400':
          description: InvalidFilterKey; InvalidFilterOption; InvalidFilterValue; InvalidKeyId; InvalidNextToken
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidFilterKey'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonSSM.GetParametersByPath
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/GetParametersByPathRequest'
      tags:
      - Parameter
components:
  schemas:
    DeleteParametersResult:
      type: object
      properties:
        DeletedParameters:
          type: array
          items:
            type: string
          description: The names of the deleted parameters.
        InvalidParameters:
          type: array
          items:
            type: string
          description: The names of parameters that weren't deleted because the parameters aren't valid.
    DeleteParameterResult:
      type: object
      properties: {}
    DescribeParametersResult:
      type: object
      properties:
        Parameters:
          type: array
          items:
            $ref: '#/components/schemas/ParameterMetadata'
          description: Parameters returned by the request.
        NextToken:
          type: string
          description: The token to use when requesting the next set of items.
    ParameterStringFilter:
      type: object
      properties:
        Key:
          type: string
          description: 'The name of the filter. The ParameterStringFilter object is used by the DescribeParameters and GetParametersByPath API operations. However, not all of the pattern values listed for Key can be used with both operations. For DescribeParameters, all of the listed patterns are valid except Label. For GetParametersByPath, the following patterns listed for Key aren''t valid: tag, DataType, Name, Path, and Tier. For examples of Amazon Web Services CLI commands demonstrating valid parameter filter constructions, see Searching for Systems Manager parameters in the Amazon Web Services Systems Manager Use'
        Option:
          type: string
          description: 'For all filters used with DescribeParameters, valid options include Equals and BeginsWith. The Name filter additionally supports the Contains option. (Exception: For filters using the key Path, valid options include Recursive and OneLevel.) For filters used with GetParametersByPath, valid options include Equals and BeginsWith. (Exception: For filters using Label as the Key name, the only valid option is Equals.)'
        Values:
          type: array
          items:
            type: string
          description: The value you want to search for.
      required:
      - Key
    GetParametersRequest:
      type: object
      properties:
        Names:
          type: array
          items:
            type: string
          description: 'The names or Amazon Resource Names (ARNs) of the parameters that you want to query. For parameters shared with you from another account, you must use the full ARNs. To query by parameter label, use "Name": "name:label". To query by parameter version, use "Name": "name:version". The results for GetParameters requests are listed in alphabetical order in query responses. For information about shared parameters, see Working with shared parameters in the Amazon Web Services Systems Manager User Guide.'
        WithDecryption:
          type: boolean
          description: Return decrypted secure string value. Return decrypted values for secure string parameters. This flag is ignored for String and StringList parameter types.
      required:
      - Names
    GetParametersResult:
      type: object
      properties:
        Parameters:
          type: array
          items:
            $ref: '#/components/schemas/Parameter'
          description: A list of details for a parameter.
        InvalidParameters:
          type: array
          items:
            type: string
          description: A list of parameters that aren't formatted correctly or don't run during an execution.
    InvalidFilterKey:
      type: object
      properties: {}
    Parameter:
      type: object
      properties:
        Name:
          type: string
          description: The name of the parameter.
        Type:
          type: string
          enum:
          - String
          - StringList
          - SecureString
          description: 'The type of parameter. Valid values include the following: String, StringList, and SecureString. If type is StringList, the system returns a comma-separated string with no spaces between commas in the Value field.'
        Value:
          type: string
          description: The parameter value. If type is StringList, the system returns a comma-separated string with no spaces between commas in the Value field.
        Version:
          type: integer
          description: The parameter version.
        Selector:
          type: string
          description: 'Either the version number or the label used to retrieve the parameter value. Specify selectors by using one of the following formats: parameter_name:version parameter_name:label'
        SourceResult:
          type: string
          description: Applies to parameters that reference information in other Amazon Web Services services. SourceResult is the raw result or response from the source.
        LastModifiedDate:
          type: string
          format: date-time
          description: Date the parameter was last changed or updated and the parameter version was created.
        ARN:
          type: string
          description: The Amazon Resource Name (ARN) of the parameter.
        DataType:
          type: string
          description: The data type of the parameter, such as text or aws:ec2:image. The default is text.
    InternalServerError:
      type: object
      properties:
        Message:
          type: string
    ParameterMetadata:
      type: object
      properties:
        Name:
          type: string
          description: The parameter name.
        ARN:
          type: string
          description: The Amazon Resource Name (ARN) of the parameter.
        Type:
          type: string
          enum:
          - String
          - StringList
          - SecureString
          description: 'The type of parameter. Valid parameter types include the following: String, StringList, and SecureString.'
        KeyId:
          type: string
          description: The alias of the Key Management Service (KMS) key used to encrypt the parameter. Applies to SecureString parameters only.
        LastModifiedDate:
          type: string
          format: date-time
          description: Date the parameter was last changed or updated.
        LastModifiedUser:
          type: string
          description: Amazon Resource Name (ARN) of the Amazon Web Services user who last changed the parameter.
        Description:
          type: string
          description: Description of the parameter actions.
        AllowedPattern:
          type: string
          description: A parameter name can include only the following letters and symbols. a-zA-Z0-9_.-
        Version:
          type: integer
          description: The parameter version.
        Tier:
          type: string
          enum:
          - Standard
          - Advanced
          - Intelligent-Tiering
          description: The parameter tier.
        Policies:
          type: array
          items:
            $ref: '#/components/schemas/ParameterInlinePolicy'
          description: A list of policies associated with a parameter.
        DataType:
          type: string
          description: The data type of the parameter, such as text or aws:ec2:image. The default is text.
    DeleteParameterRequest:
      type: object
      properties:
        Name:
          type: string
          description: The name of the parameter to delete. You can't enter the Amazon Resource Name (ARN) for a parameter, only the parameter name itself.
      required:
      - Name
    ParameterInlinePolicy:
      type: object
      properties:
        PolicyText:
          type: string
          description: The JSON text of the policy.
        PolicyType:
          type: string
          description: 'The type of policy. Parameter Store, a tool in Amazon Web Services Systems Manager, supports the following policy types: Expiration, ExpirationNotification, and NoChangeNotification.'
        PolicyStatus:
          type: string
          description: 'The status of the policy. Policies report the following statuses: Pending (the policy hasn''t been enforced or applied yet), Finished (the policy was applied), Failed (the policy wasn''t applied), or InProgress (the policy is being applied now).'
    DeleteParametersRequest:
      type: object
      properties:
        Names:
          type: array
          items:
            type: string
          description: The names of the parameters to delete. After deleting a parameter, wait for at least 30 seconds to create a parameter with the same name. You can't enter the Amazon Resource Name (ARN) for a parameter, only the parameter name itself.
      required:
      - Names
    InvalidKeyId:
      type: object
      properties:
        message:
          type: string
    DescribeParametersRequest:
      type: object
      properties:
        Filters:
          type: array
          items:
            $ref: '#/components/schemas/ParametersFilter'
          description: This data type is deprecated. Instead, use ParameterFilters.
        ParameterFilters:
          type: array
          items:
            $ref: '#/components/schemas/ParameterStringFilter'
          description: Filters to limit the request results.
        MaxResults:
          type: integer
          description: The maximum number of items to return for this call. The call also returns a token that you can specify in a subsequent call to get the next set of results.
        NextToken:
          type: string
          description: The token for the next set of items to return. (You received this token from a previous call.)
        Shared:
          type: boolean
          description: Lists parameters that are shared with you. By default when using this option, the command returns parameters that have been shared using a standard Resource Access Manager Resource Share. In order for a parameter that was shared using the PutResourcePolicy command to be returned, the associated RAM Resource Share Created From Policy must have been promoted to a standard Resource Share using the RAM PromoteResourceShareCreatedFromPolicy API operation. For more information about sharing parameters, see Working with shared parameters in the Amazon Web Services Systems Manager User Guide.
    GetParametersByPathResult:
      type: object
      properties:
        Parameters:
          type: array
          items:
            $ref: '#/components/schemas/Parameter'
          description: A list of parameters found in the specified hierarchy.
        NextToken:
          type: string
          description: The token for the next set of items to return. Use this token to get the next set of results.
    GetParametersByPathRequest:
      type: object
      properties:
        Path:
          type: string
          description: 'The hierarchy for the parameter. Hierarchies start with a forward slash (/). The hierarchy is the parameter name except the last part of the parameter. For the API call to succeed, the last part of the parameter name can''t be in the path. A parameter name hierarchy can have a maximum of 15 levels. Here is an example of a hierarchy: /Finance/Prod/IAD/WinServ2016/license33'
        Recursive:
          type: boolean
          description: Retrieve all parameters within a hierarchy. If a user has access to a path, then the user can access all levels of that path. For example, if a user has permission to access path /a, then the user can also access /a/b. Even if a user has explicitly been denied access in IAM for parameter /a/b, they can still call the GetParametersByPath API operation recursively for /a and view /a/b.
        ParameterFilters:
          type: array
          items:
            $ref: '#/components/schemas/ParameterStringFilter'
          description: 'Filters to limit the request results. The following Key values are supported for GetParametersByPath: Type, KeyId, and Label. The following Key values aren''t supported for GetParametersByPath: tag, DataType, Name, Path, and Tier.'
        WithDecryption:
          type: boolean
          description: Retrieve all parameters in a hierarchy with their value decrypted.
        MaxResults:
          type: integer
          description: The maximum number of items to return for this call. The call also returns a token that you can specify in a subsequent call to get the next set of results.
        NextToken:
          type: string
          description: A token to start the list. Use this token to get the next set of results.
      required:
      - Path
    ParameterNotFound:
      type: object
      properties:
        message:
          type: string
    ParametersFilter:
      type: object
      properties:
        Key:
          type: string
          enum:
          - Name
          - Type
          - KeyId
          description: The name of the filter.
        Values:
          type: array
          items:
            type: string
          description: The filter values.
      required:
      - Key
      - Values
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: ssm
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/ssm/service/2014-11-06/ssm-2014-11-06.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)