APIs.io Engineering Platform Amazon API Gateway — Usageplans

naftiko: 1.0.0-alpha2
info:
  label: APIs.io Engineering Platform Amazon API Gateway — Usageplans
  description: 'APIs.io Engineering Platform Amazon API Gateway — Usageplans. 11 operations. Lead operation: Usageplans. Self-contained
    Naftiko capability covering one Engineering Platform business surface.'
  tags:
  - Engineering Platform
  - Usageplans
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    ENGINEERING_PLATFORM_API_KEY: ENGINEERING_PLATFORM_API_KEY
capability:
  consumes:
  - type: http
    namespace: aws-api-gateway-usageplans
    baseUri: http://apigateway.{region}.amazonaws.com
    description: APIs.io Engineering Platform Amazon API Gateway — Usageplans business capability. Self-contained, no shared
      references.
    resources:
    - name: usageplans
      path: /usageplans
      operations:
      - name: createusageplan
        method: POST
        description: Creates a usage plan with the throttle and quota limits, as well as the associated API stages, specified
          in the payload.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: getusageplans
        method: GET
        description: Gets all the usage plans of the caller's account.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: position
          in: query
          type: string
          description: The current pagination position in the paged result set.
        - name: keyId
          in: query
          type: string
          description: The identifier of the API key associated with the usage plans.
        - name: limit
          in: query
          type: integer
          description: The maximum number of returned results per page. The default value is 25 and the maximum value is 500.
    - name: usageplans-usageplanId
      path: /usageplans/{usageplanId}
      operations:
      - name: deleteusageplan
        method: DELETE
        description: Deletes a usage plan of a given plan Id.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: usageplanId
          in: path
          type: string
          description: The Id of the to-be-deleted usage plan.
          required: true
      - name: getusageplan
        method: GET
        description: Gets a usage plan of a given plan identifier.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: usageplanId
          in: path
          type: string
          description: The identifier of the UsagePlan resource to be retrieved.
          required: true
      - name: updateusageplan
        method: PATCH
        description: Updates a usage plan of a given plan Id.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: usageplanId
          in: path
          type: string
          description: The Id of the to-be-updated usage plan.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: usageplans-usageplanId-keys
      path: /usageplans/{usageplanId}/keys
      operations:
      - name: createusageplankey
        method: POST
        description: Creates a usage plan key for adding an existing API key to a usage plan.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: usageplanId
          in: path
          type: string
          description: The Id of the UsagePlan resource representing the usage plan containing the to-be-created UsagePlanKey
            resource representing a plan customer.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: getusageplankeys
        method: GET
        description: Gets all the usage plan keys representing the API keys added to a specified usage plan.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: usageplanId
          in: path
          type: string
          description: The Id of the UsagePlan resource representing the usage plan containing the to-be-retrieved UsagePlanKey
            resource representing a plan customer.
          required: true
        - name: position
          in: query
          type: string
          description: The current pagination position in the paged result set.
        - name: limit
          in: query
          type: integer
          description: The maximum number of returned results per page. The default value is 25 and the maximum value is 500.
        - name: name
          in: query
          type: string
          description: A query parameter specifying the name of the to-be-returned usage plan keys.
    - name: usageplans-usageplanId-keys-keyId
      path: /usageplans/{usageplanId}/keys/{keyId}
      operations:
      - name: deleteusageplankey
        method: DELETE
        description: Deletes a usage plan key and remove the underlying API key from the associated usage plan.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: usageplanId
          in: path
          type: string
          description: The Id of the UsagePlan resource representing the usage plan containing the to-be-deleted UsagePlanKey
            resource representing a plan customer.
          required: true
        - name: keyId
          in: path
          type: string
          description: The Id of the UsagePlanKey resource to be deleted.
          required: true
      - name: getusageplankey
        method: GET
        description: Gets a usage plan key of a given key identifier.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: usageplanId
          in: path
          type: string
          description: The Id of the UsagePlan resource representing the usage plan containing the to-be-retrieved UsagePlanKey
            resource representing a plan customer.
          required: true
        - name: keyId
          in: path
          type: string
          description: The key Id of the to-be-retrieved UsagePlanKey resource representing a plan customer.
          required: true
    - name: usageplans-usageplanId-keys-keyId-usage
      path: /usageplans/{usageplanId}/keys/{keyId}/usage
      operations:
      - name: updateusage
        method: PATCH
        description: Grants a temporary extension to the remaining quota of a usage plan associated with a specified API key.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: usageplanId
          in: path
          type: string
          description: The Id of the usage plan associated with the usage data.
          required: true
        - name: keyId
          in: path
          type: string
          description: The identifier of the API key associated with the usage plan in which a temporary extension is granted
            to the remaining quota.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: usageplans-usageplanId-usage#startDate&endDate
      path: /usageplans/{usageplanId}/usage#startDate&endDate
      operations:
      - name: getusage
        method: GET
        description: Gets the usage data of a usage plan in a specified time interval.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: usageplanId
          in: path
          type: string
          description: The Id of the usage plan associated with the usage data.
          required: true
        - name: keyId
          in: query
          type: string
          description: The Id of the API key associated with the resultant usage data.
        - name: startDate
          in: query
          type: string
          description: The starting date (e.g., 2016-01-01) of the usage data.
          required: true
        - name: endDate
          in: query
          type: string
          description: The ending date (e.g., 2016-12-31) of the usage data.
          required: true
        - name: position
          in: query
          type: string
          description: The current pagination position in the paged result set.
        - name: limit
          in: query
          type: integer
          description: The maximum number of returned results per page. The default value is 25 and the maximum value is 500.
    authentication:
      type: apikey
      key: Authorization
      value: '{{env.ENGINEERING_PLATFORM_API_KEY}}'
      placement: header
  exposes:
  - type: rest
    namespace: aws-api-gateway-usageplans-rest
    port: 8080
    description: REST adapter for APIs.io Engineering Platform Amazon API Gateway — Usageplans. One Spectral-compliant resource
      per consumed operation, prefixed with /v1.
    resources:
    - path: /v1/usageplans
      name: usageplans
      description: REST surface for usageplans.
      operations:
      - method: POST
        name: createusageplan
        description: Creates a usage plan with the throttle and quota limits, as well as the associated API stages, specified
          in the payload.
        call: aws-api-gateway-usageplans.createusageplan
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: getusageplans
        description: Gets all the usage plans of the caller's account.
        call: aws-api-gateway-usageplans.getusageplans
        with:
          position: rest.position
          keyId: rest.keyId
          limit: rest.limit
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/usageplans/{usageplanid}
      name: usageplans-usageplanid
      description: REST surface for usageplans-usageplanId.
      operations:
      - method: DELETE
        name: deleteusageplan
        description: Deletes a usage plan of a given plan Id.
        call: aws-api-gateway-usageplans.deleteusageplan
        with:
          usageplanId: rest.usageplanId
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: getusageplan
        description: Gets a usage plan of a given plan identifier.
        call: aws-api-gateway-usageplans.getusageplan
        with:
          usageplanId: rest.usageplanId
        outputParameters:
        - type: object
          mapping: $.
      - method: PATCH
        name: updateusageplan
        description: Updates a usage plan of a given plan Id.
        call: aws-api-gateway-usageplans.updateusageplan
        with:
          usageplanId: rest.usageplanId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/usageplans/{usageplanid}/keys
      name: usageplans-usageplanid-keys
      description: REST surface for usageplans-usageplanId-keys.
      operations:
      - method: POST
        name: createusageplankey
        description: Creates a usage plan key for adding an existing API key to a usage plan.
        call: aws-api-gateway-usageplans.createusageplankey
        with:
          usageplanId: rest.usageplanId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: getusageplankeys
        description: Gets all the usage plan keys representing the API keys added to a specified usage plan.
        call: aws-api-gateway-usageplans.getusageplankeys
        with:
          usageplanId: rest.usageplanId
          position: rest.position
          limit: rest.limit
          name: rest.name
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/usageplans/{usageplanid}/keys/{keyid}
      name: usageplans-usageplanid-keys-keyid
      description: REST surface for usageplans-usageplanId-keys-keyId.
      operations:
      - method: DELETE
        name: deleteusageplankey
        description: Deletes a usage plan key and remove the underlying API key from the associated usage plan.
        call: aws-api-gateway-usageplans.deleteusageplankey
        with:
          usageplanId: rest.usageplanId
          keyId: rest.keyId
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: getusageplankey
        description: Gets a usage plan key of a given key identifier.
        call: aws-api-gateway-usageplans.getusageplankey
        with:
          usageplanId: rest.usageplanId
          keyId: rest.keyId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/usageplans/{usageplanid}/keys/{keyid}/usage
      name: usageplans-usageplanid-keys-keyid-usage
      description: REST surface for usageplans-usageplanId-keys-keyId-usage.
      operations:
      - method: PATCH
        name: updateusage
        description: Grants a temporary extension to the remaining quota of a usage plan associated with a specified API key.
        call: aws-api-gateway-usageplans.updateusage
        with:
          usageplanId: rest.usageplanId
          keyId: rest.keyId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/usageplans/{usageplanid}/usage-startdate-enddate
      name: usageplans-usageplanid-usage-startdate-enddate
      description: REST surface for usageplans-usageplanId-usage#startDate&endDate.
      operations:
      - method: GET
        name: getusage
        description: Gets the usage data of a usage plan in a specified time interval.
        call: aws-api-gateway-usageplans.getusage
        with:
          usageplanId: rest.usageplanId
          keyId: rest.keyId
          startDate: rest.startDate
          endDate: rest.endDate
          position: rest.position
          limit: rest.limit
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: aws-api-gateway-usageplans-mcp
    port: 9090
    transport: http
    description: MCP adapter for APIs.io Engineering Platform Amazon API Gateway — Usageplans. One tool per consumed operation,
      routed inline through this capability's consumes block.
    tools:
    - name: creates-usage-plan-throttle-and
      description: Creates a usage plan with the throttle and quota limits, as well as the associated API stages, specified
        in the payload.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: aws-api-gateway-usageplans.createusageplan
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: gets-all-usage-plans-caller-s
      description: Gets all the usage plans of the caller's account.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: aws-api-gateway-usageplans.getusageplans
      with:
        position: tools.position
        keyId: tools.keyId
        limit: tools.limit
      outputParameters:
      - type: object
        mapping: $.
    - name: deletes-usage-plan-given-plan
      description: Deletes a usage plan of a given plan Id.
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: aws-api-gateway-usageplans.deleteusageplan
      with:
        usageplanId: tools.usageplanId
      outputParameters:
      - type: object
        mapping: $.
    - name: gets-usage-plan-given-plan
      description: Gets a usage plan of a given plan identifier.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: aws-api-gateway-usageplans.getusageplan
      with:
        usageplanId: tools.usageplanId
      outputParameters:
      - type: object
        mapping: $.
    - name: updates-usage-plan-given-plan
      description: Updates a usage plan of a given plan Id.
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: aws-api-gateway-usageplans.updateusageplan
      with:
        usageplanId: tools.usageplanId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: creates-usage-plan-key-adding
      description: Creates a usage plan key for adding an existing API key to a usage plan.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: aws-api-gateway-usageplans.createusageplankey
      with:
        usageplanId: tools.usageplanId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: gets-all-usage-plan-keys
      description: Gets all the usage plan keys representing the API keys added to a specified usage plan.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: aws-api-gateway-usageplans.getusageplankeys
      with:
        usageplanId: tools.usageplanId
        position: tools.position
        limit: tools.limit
        name: tools.name
      outputParameters:
      - type: object
        mapping: $.
    - name: deletes-usage-plan-key-and
      description: Deletes a usage plan key and remove the underlying API key from the associated usage plan.
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: aws-api-gateway-usageplans.deleteusageplankey
      with:
        usageplanId: tools.usageplanId
        keyId: tools.keyId
      outputParameters:
      - type: object
        mapping: $.
    - name: gets-usage-plan-key-given
      description: Gets a usage plan key of a given key identifier.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: aws-api-gateway-usageplans.getusageplankey
      with:
        usageplanId: tools.usageplanId
        keyId: tools.keyId
      outputParameters:
      - type: object
        mapping: $.
    - name: grants-temporary-extension-remaining-quota
      description: Grants a temporary extension to the remaining quota of a usage plan associated with a specified API key.
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: aws-api-gateway-usageplans.updateusage
      with:
        usageplanId: tools.usageplanId
        keyId: tools.keyId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: gets-usage-data-usage-plan
      description: Gets the usage data of a usage plan in a specified time interval.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: aws-api-gateway-usageplans.getusage
      with:
        usageplanId: tools.usageplanId
        keyId: tools.keyId
        startDate: tools.startDate
        endDate: tools.endDate
        position: tools.position
        limit: tools.limit
      outputParameters:
      - type: object
        mapping: $.