WSO2 MCP Server Documents API

openapi: 3.2.0
info:
  title: WSO2 API Manager - Developer Portal MCP Server Documents 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: MCP Server Documents
paths:
  /mcp-servers/{mcpServerId}/documents:
    get:
      tags:
      - MCP Server Documents
      summary: Get a List of Documents of a MCP Server
      description: 'This operation can be used to retrieve a list of documents belonging to a MCP Server by providing the id of the

        MCP Server.


        `X-WSO2-Tenant` header can be used to retrieve documents of a MCP Server that belongs to a different tenant

        domain. If not specified super tenant will be used. If Authorization header is present in the request, the

        user''s tenant associated with the access token will be used.


        **NOTE:**

        * This operation does not require an Authorization header by default. But in order to see a restricted MCP

        Server''s documents, you need to provide Authorization header.'
      parameters:
      - $ref: '#/components/parameters/mcpServerId'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/requestedTenant'
      - $ref: '#/components/parameters/If-None-Match'
      responses:
        200:
          description: 'OK.

            Document list is 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/DocumentList'
        304:
          description: 'Not Modified.

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

            '
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
        406:
          $ref: '#/components/responses/NotAcceptable'
      security:
      - OAuth2Security: []
      x-code-samples:
      - lang: Curl
        source: curl -k "https://localhost:9443/api/am/devportal/v3/mcp-servers/c43a325c-260b-4302-81cb-768eafaa3aed/documents"
      operationId: getMCPServerDocuments
  /mcp-servers/{mcpServerId}/documents/{documentId}:
    get:
      tags:
      - MCP Server Documents
      summary: Get a Document of a MCP Server
      description: 'This operation can be used to retrieve a particular document''s metadata associated with a MCP Server.


        `X-WSO2-Tenant` header can be used to retrieve a document of a MCP Server that belongs to a different tenant

        domain. If not specified super tenant will be used. If Authorization header is present in the request, the

        user''s tenant associated with the access token will be used.


        **NOTE:**

        * This operation does not require an Authorization header by default. But in order to see a restricted MCP

        Server''s document, you need to provide Authorization header.'
      parameters:
      - $ref: '#/components/parameters/mcpServerId'
      - $ref: '#/components/parameters/documentId'
      - $ref: '#/components/parameters/requestedTenant'
      - $ref: '#/components/parameters/If-None-Match'
      responses:
        200:
          description: 'OK.

            Document 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/Document'
        304:
          description: 'Not Modified.

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

            '
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
        406:
          $ref: '#/components/responses/NotAcceptable'
      security:
      - OAuth2Security: []
      x-code-samples:
      - lang: Curl
        source: curl -k "https://localhost:9443/api/am/devportal/v3/mcp-servers/c43a325c-260b-4302-81cb-768eafaa3aed/documents/850a4f34-db2c-4d23-9d85-3f95fbfb082c"
      operationId: getMCPServerDocument
  /mcp-servers/{mcpServerId}/documents/{documentId}/content:
    get:
      tags:
      - MCP Server Documents
      summary: Get the Content of a MCP Server Document
      description: 'This operation can be used to retrieve the content of a MCP Server''s document.


        The document can be of 3 types. In each cases responses are different.


        1. **Inline type**:

        The content of the document will be retrieved in `text/plain` content type

        2. **FILE type**:

        The file will be downloaded with the related content type (eg. `application/pdf`)

        3. **URL type**:

        The client will recieve the URL of the document as the Location header with the response with - `303 See Other`


        `X-WSO2-Tenant` header can be used to retrieve the content of a document of a MCP Server that belongs to a

        different tenant domain. If not specified super tenant will be used. If Authorization header is present in the

        request, the user''s tenant associated with the access token will be used.


        **NOTE:**

        * This operation does not require an Authorization header by default. But in order to see a restricted MCP

        Server''s document content, you need to provide Authorization header.'
      parameters:
      - $ref: '#/components/parameters/mcpServerId'
      - $ref: '#/components/parameters/documentId'
      - $ref: '#/components/parameters/requestedTenant'
      - $ref: '#/components/parameters/If-None-Match'
      responses:
        200:
          description: 'OK.

            File or inline content 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 modified the last time.

                Used by caches, or in conditional requests.

                '
              schema:
                type: string
          content: {}
        303:
          description: 'See Other.

            Source can be retrieved from the URL specified at the Location header.

            '
          headers:
            Location:
              description: 'The Source URL of the document.

                '
              schema:
                type: string
          content: {}
        304:
          description: 'Not Modified.

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

            '
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
        406:
          $ref: '#/components/responses/NotAcceptable'
      security:
      - OAuth2Security: []
      x-code-samples:
      - lang: Curl
        source: curl -k "https://localhost:9443/api/am/devportal/v3/mcp-servers/890a4f4d-09eb-4877-a323-57f6ce2ed79b/documents/0bcb7f05-599d-4e1a-adce-5cb89bfe58d5/content"
      operationId: getMCPServerDocumentContent
components:
  parameters:
    documentId:
      name: documentId
      in: path
      description: 'Document Identifier

        '
      required: true
      schema:
        type: string
    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
    mcpServerId:
      name: mcpServerId
      in: path
      description: '**MCP Server ID** consisting of the **UUID** of the MCP Server.

        '
      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
    offset:
      name: offset
      in: query
      description: 'Starting point within the complete list of items qualified.

        '
      schema:
        type: integer
        default: 0
  schemas:
    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: ''
    DocumentList:
      title: Document List
      type: object
      properties:
        count:
          type: integer
          description: 'Number of Documents returned.

            '
          example: 1
        list:
          type: array
          items:
            $ref: '#/components/schemas/Document'
        pagination:
          $ref: '#/components/schemas/Pagination'
    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'
    Document:
      title: Document
      required:
      - name
      - sourceType
      - type
      type: object
      properties:
        documentId:
          type: string
          example: 01234567-0123-0123-0123-012345678901
        name:
          type: string
          example: CalculatorDoc
        type:
          type: string
          example: HOWTO
          enum:
          - HOWTO
          - SAMPLES
          - PUBLIC_FORUM
          - SUPPORT_FORUM
          - API_MESSAGE_FORMAT
          - SWAGGER_DOC
          - OTHER
        summary:
          type: string
          example: Summary of Calculator Documentation
        sourceType:
          type: string
          example: INLINE
          enum:
          - INLINE
          - MARKDOWN
          - URL
          - FILE
        sourceUrl:
          type: string
          example: ''
        otherTypeName:
          type: string
          example: ''
    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

            '
  responses:
    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: []
    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: []
  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