WSO2 Subscriptions API

openapi: 3.2.0
info:
  title: WSO2 API Manager - Developer Portal Subscriptions API
  description: This document specifies a **RESTful API** for WSO2 **API Manager** - **Developer Portal**.
  contact:
    name: WSO2
    url: https://wso2.com/api-manager/
    email: architecture@wso2.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: v3
servers:
- url: https://apis.wso2.com/api/am/devportal/v3
tags:
- name: Subscriptions
paths:
  /subscriptions:
    get:
      tags:
      - Subscriptions
      summary: Get All Subscriptions
      description: 'This operation can be used to retrieve a list of subscriptions of the user associated with the provided access token. This operation is capable of


        1. Retrieving applications which are subscribed to a specific API.

        `GET https://localhost:9443/api/am/devportal/v3/subscriptions?apiId=c43a325c-260b-4302-81cb-768eafaa3aed`


        2. Retrieving APIs which are subscribed by a specific application.

        `GET https://localhost:9443/api/am/devportal/v3/subscriptions?applicationId=c43a325c-260b-4302-81cb-768eafaa3aed`


        If application sharing is enabled, the **groupId** can be used to include subscriptions associated with the

        specified **groupId** in the results, provided the application is shared within the group.


        **IMPORTANT:**

        * It is mandatory to provide either **apiId** or **applicationId**.'
      parameters:
      - $ref: '#/components/parameters/apiId-Q'
      - $ref: '#/components/parameters/applicationId-Q'
      - $ref: '#/components/parameters/groupId'
      - $ref: '#/components/parameters/requestedTenant'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/If-None-Match'
      responses:
        200:
          description: 'OK.

            Subscription list returned.

            '
          headers:
            ETag:
              description: 'Entity Tag of the response resource.

                Used by caches, or in conditional requests.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionList'
        304:
          description: 'Not Modified.

            Empty body because the client has already the latest version of the requested resource.

            '
          content: {}
        406:
          $ref: '#/components/responses/NotAcceptable'
      security:
      - OAuth2Security:
        - apim:subscribe
        - apim:sub_manage
      x-code-samples:
      - lang: Curl
        source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8" "https://localhost:9443/api/am/devportal/v3/subscriptions?apiId=02e658e7-71c7-4b1d-a623-be145b789340"'
      operationId: getSubscriptions
      x-operation-id-source: derived
    post:
      tags:
      - Subscriptions
      summary: Add a New Subscription
      description: This operation can be used to add a new subscription providing the id of the API and the application.
      parameters:
      - $ref: '#/components/parameters/requestedTenant'
      requestBody:
        description: 'Subscription object that should to be added

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subscription'
            example:
              applicationId: bbcc3be9-e29c-4ba2-a756-d922a5bd6c4d
              apiId: abcff4cf-24c5-4298-a7b4-39a1fbd34693
              throttlingPolicy: Unlimited
        required: true
      responses:
        201:
          description: 'Created.

            Successful response with the newly created object as entity in the body.

            Location header contains URL of newly created entity.

            '
          headers:
            ETag:
              description: 'Entity Tag of the response resource. Used by caches, or in conditional request.

                '
              schema:
                type: string
            Location:
              description: 'Location to the newly created subscription.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        202:
          description: 'Accepted.

            The request has been accepted.

            '
          headers:
            Location:
              description: 'Location of the newly created subscription.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        415:
          $ref: '#/components/responses/UnsupportedMediaType'
      security:
      - OAuth2Security:
        - apim:subscribe
        - apim:sub_manage
      x-code-samples:
      - lang: Curl
        source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8" -H "Content-Type: application/json" -X POST -d @data.json "https://localhost:9443/api/am/devportal/v3/subscriptions"'
      operationId: postSubscriptions
      x-operation-id-source: derived
  /subscriptions/multiple:
    post:
      tags:
      - Subscriptions
      summary: Add New Subscriptions
      description: This operation can be used to add a new subscriptions providing the ids of the APIs and the applications.
      parameters:
      - $ref: '#/components/parameters/requestedTenant'
      requestBody:
        description: 'Subscription objects that should to be added

          '
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Subscription'
            example:
            - applicationId: bbcc3be9-e29c-4ba2-a756-d922a5bd6c4d
              apiId: abcff4cf-24c5-4298-a7b4-39a1fbd34693
              throttlingPolicy: Unlimited
            - applicationId: 67543be9-e29c-4ba2-7856-d922a5bd6c4d
              apiId: abcff4cf-24c5-4298-a7b4-39a1f7896693
              throttlingPolicy: Bronze
        required: true
      responses:
        200:
          description: 'OK.

            Successful response with the newly created objects as entity in the body.

            '
          headers:
            ETag:
              description: 'Entity Tag of the response resource. Used by caches, or in conditional requests (Will be supported in future).

                '
              schema:
                type: string
            Content-Type:
              description: 'The content type of the body.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Subscription'
        400:
          $ref: '#/components/responses/BadRequest'
        415:
          $ref: '#/components/responses/UnsupportedMediaType'
      security:
      - OAuth2Security:
        - apim:subscribe
        - apim:sub_manage
      x-code-samples:
      - lang: Curl
        source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8" -H "Content-Type: application/json" -X POST -d @data.json "https://localhost:9443/api/am/devportal/v3/subscriptions/multiple"'
      operationId: postSubscriptionsMultiple
      x-operation-id-source: derived
  /subscriptions/{apiId}/additionalInfo:
    get:
      tags:
      - Subscriptions
      summary: Get Additional Information of subscriptions attached to an API
      description: This operation can be used to retrieve all additional Information of subscriptions attached to an API by providing the API id.
      operationId: getAdditionalInfoOfAPISubscriptions
      parameters:
      - $ref: '#/components/parameters/apiId'
      - $ref: '#/components/parameters/groupId'
      - $ref: '#/components/parameters/requestedTenant'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/If-None-Match'
      responses:
        200:
          description: 'OK.

            Types and fields returned successfully.

            '
          headers:
            Content-Type:
              description: 'The content of the body.

                '
              schema:
                type: string
                default: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdditionalSubscriptionInfoList'
        404:
          description: 'Not Found.

            Retrieving types and fields failed.

            '
          content: {}
      security:
      - OAuth2Security: []
      x-code-samples:
      - lang: Curl
        source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8" "https://localhost:9443/api/am/devportal/v3/subscriptions/e93fb282-b456-48fc-8981-003fb89086ae/additionalInfo"'
  /subscriptions/{subscriptionId}:
    get:
      tags:
      - Subscriptions
      summary: Get Details of a Subscription
      description: This operation can be used to get details of a single subscription.
      parameters:
      - $ref: '#/components/parameters/subscriptionId'
      - $ref: '#/components/parameters/If-None-Match'
      responses:
        200:
          description: 'OK.

            Subscription returned

            '
          headers:
            ETag:
              description: Entity Tag of the response resource. Used by caches, or in conditional requests.
              schema:
                type: string
            Last-Modified:
              description: Date and time the resource has been modifed the last time. Used by caches, or in conditional reuquests.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        304:
          description: 'Not Modified.

            Empty body because the client has already the latest version of the requested resource.

            '
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
      security:
      - OAuth2Security:
        - apim:subscribe
        - apim:sub_manage
      x-code-samples:
      - lang: Curl
        source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8" "https://localhost:9443/api/am/devportal/v3/subscriptions/5b65808c-cdf2-43e1-a695-de63e3ad0ae9"'
      operationId: getSubscriptionsBySubscriptionId
      x-operation-id-source: derived
    put:
      tags:
      - Subscriptions
      summary: Update Existing Subscription
      description: This operation can be used to update a subscription providing the subscription id, api id, application Id, status and updated throttling policy tier.
      parameters:
      - $ref: '#/components/parameters/requestedTenant'
      - $ref: '#/components/parameters/subscriptionId'
      requestBody:
        description: 'Subscription object that should to be added

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subscription'
        required: true
      responses:
        200:
          description: 'Subscription Updated.

            Successful response with the updated object as entity in the body.

            Location header contains URL of newly updates entity.

            '
          headers:
            ETag:
              description: 'Entity Tag of the response resource. Used by caches, or in conditional request.

                '
              schema:
                type: string
            Location:
              description: 'Location to the updated subscription.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        202:
          description: 'Accepted.

            The request has been accepted.

            '
          headers:
            Location:
              description: 'Location of the updated subscription.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponse'
        304:
          description: 'Not Modified.

            Empty body because the client has already the latest version of the requested resource.

            '
          content: {}
        400:
          $ref: '#/components/responses/BadRequest'
        404:
          description: 'Not Found.

            Requested Subscription does not exist.

            '
          content: {}
        415:
          description: 'Unsupported media type.

            The entity of the request was in a not supported format.

            '
          content: {}
      security:
      - OAuth2Security:
        - apim:subscribe
        - apim:sub_manage
      x-code-samples:
      - lang: Curl
        source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8" -H "Content-Type: application/json" -X PUT -d @data.json "https://localhost:9443/api/am/devportal/v3/subscriptions/80369180-7d90-4ee8-99a1-19fa68512aa5"'
      operationId: putSubscriptionsBySubscriptionId
      x-operation-id-source: derived
    delete:
      tags:
      - Subscriptions
      summary: Remove a Subscription
      description: This operation can be used to remove a subscription.
      parameters:
      - $ref: '#/components/parameters/subscriptionId'
      - $ref: '#/components/parameters/If-Match'
      responses:
        200:
          description: 'OK.

            Resource successfully deleted.

            '
          content: {}
        202:
          description: 'Accepted.

            The request has been accepted.

            '
          headers:
            Location:
              description: 'Location of the existing subscription.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponse'
        404:
          $ref: '#/components/responses/NotFound'
        412:
          $ref: '#/components/responses/PreconditionFailed'
      security:
      - OAuth2Security:
        - apim:subscribe
        - apim:sub_manage
      x-code-samples:
      - lang: Curl
        source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8" -H "Content-Type: application/json" -X DELETE "https://localhost:9443/api/am/devportal/v3/subscriptions/80369180-7d90-4ee8-99a1-19fa68512aa5"'
      operationId: deleteSubscriptionsBySubscriptionId
      x-operation-id-source: derived
components:
  parameters:
    limit:
      name: limit
      in: query
      description: 'Maximum size of resource array to return.

        '
      schema:
        type: integer
        default: 25
    If-None-Match:
      name: If-None-Match
      in: header
      description: 'Validator for conditional requests; based on the ETag of the formerly retrieved

        variant of the resourec.

        '
      schema:
        type: string
    If-Match:
      name: If-Match
      in: header
      description: 'Validator for conditional requests; based on ETag.

        '
      schema:
        type: string
    subscriptionId:
      name: subscriptionId
      in: path
      description: 'Subscription Id

        '
      required: true
      schema:
        type: string
    groupId:
      name: groupId
      in: query
      description: 'Application Group Id

        '
      schema:
        type: string
    apiId-Q:
      name: apiId
      in: query
      description: '**API ID** consisting of the **UUID** of the API.

        '
      schema:
        type: string
    offset:
      name: offset
      in: query
      description: 'Starting point within the complete list of items qualified.

        '
      schema:
        type: integer
        default: 0
    applicationId-Q:
      name: applicationId
      in: query
      description: '**Application Identifier** consisting of the UUID of the Application.

        '
      schema:
        type: string
    apiId:
      name: apiId
      in: path
      description: '**API ID** consisting of the **UUID** of the API.

        '
      required: true
      schema:
        type: string
    requestedTenant:
      name: X-WSO2-Tenant
      in: header
      description: "For cross-tenant invocations, this is used to specify the tenant domain, where the resource need to be\n  retrieved from.\n"
      schema:
        type: string
  schemas:
    SubscriptionList:
      title: Subscription List
      type: object
      properties:
        count:
          type: integer
          description: 'Number of Subscriptions returned.

            '
          example: 1
        list:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
        pagination:
          $ref: '#/components/schemas/Pagination'
    AdvertiseInfo:
      title: API Advertise info object with advertise details
      type: object
      properties:
        advertised:
          type: boolean
          example: true
        apiExternalProductionEndpoint:
          type: string
          example: https://localhost:9443/devportal
        apiExternalSandboxEndpoint:
          type: string
          example: https://localhost:9443/devportal
        originalDevPortalUrl:
          type: string
          example: https://localhost:9443/devportal
        apiOwner:
          type: string
          example: admin
        vendor:
          type: string
          default: WSO2
          enum:
          - WSO2
          - AWS
    ErrorListItem:
      title: Description of individual errors that may have occurred during a request.
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: string
        message:
          type: string
          description: 'Description about individual errors occurred

            '
    AdditionalSubscriptionInfoList:
      title: Additional Subscription Info List
      type: object
      properties:
        count:
          type: integer
          description: 'Number of additional information sets of subscription returned.

            '
          example: 1
        list:
          type: array
          items:
            $ref: '#/components/schemas/AdditionalSubscriptionInfo'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Pagination:
      title: Pagination
      type: object
      properties:
        offset:
          type: integer
          example: 0
        limit:
          type: integer
          example: 10
        total:
          type: integer
          example: 1
        next:
          type: string
          description: 'Link to the next subset of resources qualified.

            Empty if no more resources are to be returned.

            '
          example: ''
        previous:
          type: string
          description: 'Link to the previous subset of resources qualified.

            Empty if current subset is the first subset returned.

            '
          example: ''
    APIInfo:
      title: API Info object with basic API details.
      type: object
      properties:
        id:
          type: string
          example: 01234567-0123-0123-0123-012345678901
        name:
          type: string
          example: CalculatorAPI
        displayName:
          type: string
          example: Calculator API
          description: 'Display name of the API.

            This is the name that will be displayed in the Publisher and DevPortal.

            If not provided, the name will be used as the display name.

            '
        description:
          type: string
          example: A calculator API that supports basic operations
        context:
          type: string
          example: CalculatorAPI
        version:
          type: string
          example: 1.0.0
        type:
          type: string
          example: WS
        createdTime:
          type: string
          example: 1614020559444
        provider:
          type: string
          description: 'If the provider value is not given, the user invoking the API will be used as the provider.

            '
          example: admin
        lifeCycleStatus:
          type: string
          example: PUBLISHED
        thumbnailUri:
          type: string
          example: /apis/01234567-0123-0123-0123-012345678901/thumbnail
        avgRating:
          type: string
          description: Average rating of the API
          example: '4.5'
        throttlingPolicies:
          type: array
          description: List of throttling policies of the API
          example:
          - Unlimited
          - Bronze
          items:
            type: string
        advertiseInfo:
          $ref: '#/components/schemas/AdvertiseInfo'
        businessInformation:
          $ref: '#/components/schemas/APIBusinessInformation'
        isSubscriptionAvailable:
          type: boolean
          example: false
        monetizationLabel:
          type: string
          example: Free
        gatewayType:
          type: string
          example: solace
        gatewayVendor:
          type: string
          example: WSO2
        additionalProperties:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: string
              display:
                type: boolean
          description: 'Custom(user defined) properties of API

            '
          example: {}
        monetizedInfo:
          type: boolean
          example: true
        egress:
          type: boolean
          description: Whether the API is Egress or not
          default: false
          example: true
        subtype:
          type: string
          description: Subtype of the API.
          default: DEFAULT
          example: AIAPI
          readOnly: true
    APIBusinessInformation:
      type: object
      properties:
        businessOwner:
          type: string
          example: businessowner
        businessOwnerEmail:
          type: string
          example: businessowner@wso2.com
        technicalOwner:
          type: string
          example: technicalowner
        technicalOwnerEmail:
          type: string
          example: technicalowner@wso2.com
    AdditionalSubscriptionInfo:
      title: Additional Information of subscriptions related to an API
      type: object
      properties:
        subscriptionId:
          type: string
          description: The UUID of the subscription
          readOnly: true
          example: faae5fcc-cbae-40c4-bf43-89931630d313
        applicationId:
          type: string
          description: The UUID of the application
          example: b3ade481-30b0-4b38-9a67-498a40873a6d
        applicationName:
          type: string
          description: The name of the application
          example: Sample Application
        apiId:
          type: string
          description: The unique identifier of the API.
          example: 2962f3bb-8330-438e-baee-0ee1d6434ba4
        isSolaceAPI:
          type: boolean
          example: false
        solaceOrganization:
          type: string
          example: SolaceWso2
        solaceDeployedEnvironments:
          type: array
          items:
            type: object
            properties:
              environmentName:
                type: string
              environmentDisplayName:
                type: string
              organizationName:
                type: string
              solaceURLs:
                type: array
                items:
                  type: object
                  properties:
                    protocol:
                      type: string
                      example: Defalt
                    endpointURL:
                      type: string
                      example: Default
              SolaceTopicsObject:
                type: object
                properties:
                  defaultSyntax:
                    $ref: '#/components/schemas/SolaceTopics'
                  mqttSyntax:
                    $ref: '#/components/schemas/SolaceTopics'
    Subscription:
      title: Subscription
      required:
      - applicationId
      - throttlingPolicy
      type: object
      properties:
        subscriptionId:
          type: string
          description: The UUID of the subscription
          readOnly: true
          example: faae5fcc-cbae-40c4-bf43-89931630d313
        applicationId:
          type: string
          description: The UUID of the application
          example: b3ade481-30b0-4b38-9a67-498a40873a6d
        apiId:
          type: string
          description: The unique identifier of the API.
          example: 2962f3bb-8330-438e-baee-0ee1d6434ba4
        apiInfo:
          $ref: '#/components/schemas/APIInfo'
        applicationInfo:
          $ref: '#/components/schemas/ApplicationInfo'
        throttlingPolicy:
          type: string
          example: Unlimited
        requestedThrottlingPolicy:
          type: string
          example: Unlimited
        status:
          type: string
          example: UNBLOCKED
          enum:
          - BLOCKED
          - PROD_ONLY_BLOCKED
          - UNBLOCKED
          - ON_HOLD
          - REJECTED
          - TIER_UPDATE_PENDING
          - DELETE_PENDING
        redirectionParams:
          type: string
          description: A url and other parameters the subscriber can be redirected.
          readOnly: true
          example: ''
    WorkflowResponse:
      title: workflow Response
      required:
      - workflowStatus
      type: object
      properties:
        workflowStatus:
          type: string
          description: 'This attribute declares whether this workflow task is approved or rejected.

            '
          example: APPROVED
          enum:
          - CREATED
          - APPROVED
          - REJECTED
          - REGISTERED
        jsonPayload:
          type: string
          description: 'Attributes that returned after the workflow execution

            '
    Error:
      title: Error object returned with 4XX HTTP status
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: integer
          format: int64
        message:
          type: string
          description: Error message.
        description:
          type: string
          description: 'A detail description about the error message.

            '
        moreInfo:
          type: string
          description: 'Preferably an url with more details about the error.

            '
        error:
          type: array
          description: 'If there are more than one error list them out.

            For example, list out validation errors by each field.

            '
          items:
            $ref: '#/components/schemas/ErrorListItem'
    ApplicationInfo:
      title: Application info object with basic application details
      type: object
      properties:
        applicationId:
          type: string
          example: 01234567-0123-0123-0123-012345678901
        name:
          type: string
          example: CalculatorApp
        throttlingPolicy:
          type: string
          example: Unlimited
        description:
          type: string
          example: Sample calculator application
        status:
          type: string
          example: APPROVED
          default: ''
        groups:
          type: array
          example: ''
          items:
            type: string
        subscriptionCount:
          type: integer
        attributes:
          type: object
          properties: {}
          example: External Reference ID, Billing Tier
        owner:
          type: string
          example: admin
        tokenType:
          type: string
          example: JWT
        createdTime:
          type: string
          readOnly: true
          example: 1651555310208
        updatedTime:
          type: string
          readOnly: true
          example: 1651555310208
    SolaceTopics:
      title: SolaceTopics
      type: object
      properties:
        publishTopics:
          type: array
          items:
            type: string
        subscribeTopics:
          type: array
          items:
            type: string
  responses:
    UnsupportedMediaType:
      description: Unsupported Media Type. The entity of the request was not in a supported format.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 415
            message: Unsupported media type
            description: The entity of the request was not in a supported format
            moreInfo: ''
            error: []
    BadRequest:
      description: Bad Request. Invalid request or validation error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 400
            message: Bad Request
            description: Invalid request or validation error
            moreInfo: ''
            error: []
    NotAcceptable:
      description: Not Acceptable. The requested media type is not supported.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 406
            message: Not Acceptable
            description: The requested media type is not supported
            moreInfo: ''
            error: []
    PreconditionFailed:
      description: Precondition Failed. The request has not been performed because one of the preconditions is not met.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 412
            message: Precondition Failed
            description: The request has not been performed because one of the preconditions is not met
            moreInfo: ''
            error: []
    NotFound:
      description: Not Found. The specified resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 404
            message: Not Found
            description: The specified resource does not exist
            moreInfo: ''
            error: []
  securitySchemes:
    OAuth2Security:
      type: oauth2
      flows:
        password:
          tokenUrl: https://localhost:9443/oauth2/token
          scopes:
            openid: Authorize access to user details
            apim:subscribe: Subscribe API
            apim:api_key: Generate API Keys
            apim:app_manage: Retrieve, Manage and Import, Export applications
            apim:sub_manage: Retrieve, Manage subscriptions
            apim:store_settings: Retrieve Developer Portal settings
            apim:sub_alert_manage: Retrieve, subscribe and configure Developer Portal alert types
            apim:app_import_export: Import and export applications related operations
            apim:admin: Manage all admin operations