openapi: 3.0.1
info:
title: WSO2 API Manager - Admin Advanced Policy (Collection) Advanced Policy (Collection) MCP Servers API
description: "This document specifies a **RESTful API** for WSO2 **API Manager** - **Admin Portal**.\nPlease see [full OpenAPI Specification](https://raw.githubusercontent.com/wso2/carbon-apimgt/master/components/apimgt/org.wso2.carbon.apimgt.rest.api.admin.v1/src/main/resources/admin-api.yaml) of the API which is written using [OAS 3.0](http://swagger.io/) specification.\n\n# Authentication\nThe Admin REST API is protected using OAuth2 and access control is achieved through scopes. Before you start invoking\nthe the API you need to obtain an access token with the required scopes. This guide will walk you through the steps\nthat you will need to follow to obtain an access token.\nFirst you need to obtain the consumer key/secret key pair by calling the dynamic client registration (DCR) endpoint. You can add your preferred grant types\nin the payload. A sample payload is shown below.\n```\n {\n \"callbackUrl\":\"www.example.com\",\n \"clientName\":\"rest_api_admin\",\n \"owner\":\"admin\",\n \"grantType\":\"client_credentials password refresh_token\",\n \"saasApp\":true\n }\n```\nCreate a file (payload.json) with the above sample payload, and use the cURL shown bellow to invoke the DCR endpoint. Authorization header of this should contain the\nbase64 encoded admin username and password.\n**Format of the request**\n```\n curl -X POST -H \"Authorization: Basic Base64(admin_username:admin_password)\" -H \"Content-Type: application/json\"\n \\ -d @payload.json https://<host>:<servlet_port>/client-registration/v0.17/register\n```\n**Sample request**\n```\n curl -X POST -H \"Authorization: Basic YWRtaW46YWRtaW4=\" -H \"Content-Type: application/json\"\n \\ -d @payload.json https://localhost:9443/client-registration/v0.17/register\n```\nFollowing is a sample response after invoking the above curl.\n```\n{\n\"clientId\": \"fOCi4vNJ59PpHucC2CAYfYuADdMa\",\n\"clientName\": \"rest_api_admin\",\n\"callBackURL\": \"www.example.com\",\n\"clientSecret\": \"a4FwHlq0iCIKVs2MPIIDnepZnYMa\",\n\"isSaasApplication\": true,\n\"appOwner\": \"admin\",\n\"jsonString\": \"{\\\"grant_types\\\":\\\"client_credentials password refresh_token\\\",\\\"redirect_uris\\\":\\\"www.example.com\\\",\\\"client_name\\\":\\\"rest_api_admin\\\"}\",\n\"jsonAppAttribute\": \"{}\",\n\"tokenType\": null\n}\n```\nNote that in a distributed deployment or IS as KM separated environment to invoke RESTful APIs (product APIs), users must generate tokens through API-M Control Plane's token endpoint.\nThe tokens generated using third party key managers, are to manage end-user authentication when accessing APIs.\n\nNext you must use the above client id and secret to obtain the access token.\nWe will be using the password grant type for this, you can use any grant type you desire.\nYou also need to add the proper **scope** when getting the access token. All possible scopes for Admin REST API can be viewed in **OAuth2 Security** section\nof this document and scope for each resource is given in **authorizations** section of resource documentation.\nFollowing is the format of the request if you are using the password grant type.\n```\ncurl -k -d \"grant_type=password&username=<admin_username>&password=<admin_passowrd>&scope=<scopes seperated by space>\"\n\\ -H \"Authorization: Basic base64(cliet_id:client_secret)\"\n\\ https://<host>:<server_port>/oauth2/token\n```\n**Sample request**\n```\ncurl https://localhost:9443/oauth2/token -k \\\n-H \"Authorization: Basic Zk9DaTR2Tko1OVBwSHVjQzJDQVlmWXVBRGRNYTphNEZ3SGxxMGlDSUtWczJNUElJRG5lcFpuWU1h\" \\\n-d \"grant_type=password&username=admin&password=admin&scope=apim:admin apim:tier_view\"\n```\nShown below is a sample response to the above request.\n```\n{\n\"access_token\": \"e79bda48-3406-3178-acce-f6e4dbdcbb12\",\n\"refresh_token\": \"a757795d-e69f-38b8-bd85-9aded677a97c\",\n\"scope\": \"apim:admin apim:tier_view\",\n\"token_type\": \"Bearer\",\n\"expires_in\": 3600\n}\n```\nNow you have a valid access token, which you can use to invoke an API.\nNavigate through the API descriptions to find the required API, obtain an access token as described above and invoke the API with the authentication header.\nIf you use a different authentication mechanism, this process may change.\n\n# Try out in Postman\nIf you want to try-out the embedded postman collection with \"Run in Postman\" option, please follow the guidelines listed below.\n* All of the OAuth2 secured endpoints have been configured with an Authorization Bearer header with a parameterized access token. Before invoking any REST API resource make sure you run the `Register DCR Application` and `Generate Access Token` requests to fetch an access token with all required scopes.\n* Make sure you have an API Manager instance up and running.\n* Update the `basepath` parameter to match the hostname and port of the APIM instance.\n\n[](https://app.getpostman.com/run-collection/32294946-71bea2bc-f808-4208-a4f6-861ede6f0434)\n"
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: v4
servers:
- url: https://apis.wso2.com/api/am/admin/v4
tags:
- name: MCP Servers
paths:
/mcp-servers:
get:
tags:
- MCP Servers
summary: 'Retrieve/Search MCP Servers
'
description: "This operation provides you a list of available MCP servers qualifying under a given search condition.\n\nEach retrieved MCP Server is represented with a minimal amount of attributes. If you want to get complete \ndetails of a MCP server, you need to use **Get details of a MCP** operation.\n\nThis operation supports retrieving MCP servers of other tenants. The required tenant domain need to be \nspecified as a header `X-WSO2-Tenant`. If not specified super tenant's MCP servers will be retrieved. If you \nused an Authorization header, the user's tenant associated with the access token will be used.\n\n**NOTE:**\n* By default, this operation retrieves Published MCP Server. \n* This operation does not require an Authorization header by default. But if it is provided, it will be validated and checked for permissions of the user, hence you may be able to see APIs which are restricted for special permissions/roles.\n"
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/requestedTenant'
- name: query
in: query
description: '**Search condition**.
You can search in attributes by using an **"<attribute>:"** modifier.
Eg.
"provider:wso2" will match an MCP Server if the provider of the MCP Server is exactly "wso2".
Additionally you can use wildcards.
Eg.
"provider:wso2*" will match a MCP Server if the provider of the MCP Server starts with "wso2".
Supported attribute modifiers are [**version, context, status,
description, doc, provider, tag**]
To search by Properties provide the query in below format.
**property_name:property_value**
Eg.
"environment:test" where environment is the property name and test is the propert value.
If no advanced attribute modifier has been specified, search will match the
given query string against API Name.
'
schema:
type: string
- $ref: '#/components/parameters/If-None-Match'
responses:
200:
description: 'OK.
List of qualifying MCP Servers is returned.
'
content:
application/json:
schema:
$ref: '#/components/schemas/APIList'
406:
$ref: '#/components/responses/NotAcceptable'
security:
- OAuth2Security: []
x-code-samples:
- lang: Curl
source: curl -k "https://localhost:9443/api/am/devportal/v3/mcp-servers"
operationId: getAllMCPServers
/mcp-servers/{mcpServerId}:
get:
tags:
- MCP Servers
summary: 'Get Details of a MCP Server
'
description: "Using this operation, you can retrieve complete details of a single MCP Server. You need to provide the Id of \nthe MCP Server to retrieve it.\n\n`X-WSO2-Tenant` header can be used to retrieve a MCP Server of a different tenant domain. If not specified \nsuper tenant will be used. If Authorization header is present in the request, the user's tenant associated \nwith the access token will be used.\n\n**NOTE:**\n* This operation does not require an Authorization header by default. But if it is provided, it will be \nvalidated and checked for permissions of the user, hence you may be able to see APIs which are restricted for\nspecial permissions/roles. \\n\n"
parameters:
- $ref: '#/components/parameters/mcpServerId'
- $ref: '#/components/parameters/requestedTenant'
- $ref: '#/components/parameters/If-None-Match'
responses:
200:
description: 'OK.
Requested API is 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:
application/json:
schema:
$ref: '#/components/schemas/API'
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"
operationId: getMCPServer
/mcp-servers/{mcpServerId}/thumbnail:
get:
tags:
- MCP Servers
summary: Get Thumbnail Image
description: "This operation can be used to download a thumbnail image of a MCP Server.\n\n`X-WSO2-Tenant` header can be used to retrieve a thumbnail of a MCP Server that belongs to a different tenant \ndomain. If not specified super tenant will be used. If Authorization header is present in the request, the \nuser's tenant associated with the access token will be used.\n\n**NOTE:**\n* This operation does not require an Authorization header by default. But in order to see a restricted \nMCP Server's thumbnail, you need to provide Authorization header.\n"
parameters:
- $ref: '#/components/parameters/mcpServerId'
- $ref: '#/components/parameters/requestedTenant'
- $ref: '#/components/parameters/If-None-Match'
responses:
200:
description: 'OK.
Thumbnail image 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 (Will be supported in future).
'
schema:
type: string
Content-Type:
description: 'The content type of the body.
'
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/e93fb282-b456-48fc-8981-003fb89086ae/thumbnail" > image.jpeg
operationId: getMCPServerThumbnail
/mcp-servers/{mcpServerId}/subscription-policies:
get:
tags:
- MCP Servers
summary: 'Get Details of the Subscription Throttling Policies of a MCP Server
'
description: "This operation can be used to retrieve details of the subscription throttling policy of a MCP Server by \nspecifying the MCP Server Id.\n\n`X-WSO2-Tenant` header can be used to retrieve MCP Server subscription throttling policies that belongs to a \ndifferent tenant domain. If not specified super tenant will be used. If Authorization header is present in the \nrequest, the user's tenant associated with the access token will be used.\n"
parameters:
- $ref: '#/components/parameters/mcpServerId'
- $ref: '#/components/parameters/requestedTenant'
- $ref: '#/components/parameters/If-None-Match'
responses:
200:
description: 'OK.
Throttling Policy 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:
application/json:
schema:
$ref: '#/components/schemas/ThrottlingPolicy'
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/268c9e55-3dc1-4f47-82e7-977e5343d077/subscription-policies"
operationId: getMCPServerSubscriptionPolicies
components:
schemas:
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
'
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'
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
ThrottlingPolicyPermissionInfo:
title: Throttling Policy Permission info object with throttling policy permission details
type: object
properties:
type:
type: string
enum:
- allow
- deny
roles:
type: array
description: roles for this permission
example:
- manager
- developer
items:
type: string
ScopeInfo:
title: API Scope info object with scope details
type: object
properties:
key:
type: string
example: admin_scope
name:
type: string
example: admin scope
roles:
type: array
description: Allowed roles for the scope
example:
- manager
- developer
items:
type: string
description:
type: string
description: Description of the scope
APIOperations:
title: Operation
type: object
properties:
id:
type: string
example: apioperation
target:
type: string
verb:
type: string
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: ''
APIList:
title: API List
type: object
properties:
count:
type: integer
description: 'Number of APIs returned.
'
example: 1
list:
type: array
items:
$ref: '#/components/schemas/APIInfo'
pagination:
$ref: '#/components/schemas/Pagination'
example:
count: 2
list:
- id: 01234567-0123-0123-0123-012345678901
name: CalculatorAPI
description: A calculator API that supports basic operations
context: /CalculatorAPI
version: 1.0.0
type: HTTP
provider: admin
lifeCycleStatus: PUBLISHED
thumbnailUri: /apis/01234567-0123-0123-0123-012345678901/thumbnail
avgRating: 4.3
throttlingPolicies:
- Unlimited
advertiseInfo:
advertised: false,
apiExternalProductionEndpoint: null,
apiExternalSandboxEndpoint: null,
originalDevPortalUrl: null,
apiOwner: null
businessInformation:
businessOwner: Jane Roe
businessOwnerEmail: businessowner@wso2.com
technicalOwner: John Doe
technicalOwnerEmail: technicalowner@wso2.com
isSubscriptionAvailable: true
monetizationLabel: null
- id: 01123567-1233-5453-0212-12353678901
name: PizzaShackAPI
description: A Pizza ordering API
context: /PizzaShackAPI
version: 1.0.0
type: HTTP
provider: admin
lifeCycleStatus: PUBLISHED
thumbnailUri: /apis/01123567-1233-5453-0212-12353678901/thumbnail
avgRating: 4.3
throttlingPolicies:
- Unlimited
advertiseInfo:
advertised: false,
apiExternalProductionEndpoint: null,
apiExternalSandboxEndpoint: null,
originalDevPortalUrl: null,
apiOwner: null
businessInformation:
businessOwner: Jane Roe
businessOwnerEmail: businessowner@wso2.com
technicalOwner: John Doe
technicalOwnerEmail: technicalowner@wso2.com
isSubscriptionAvailable: true
monetizationLabel: null
pagination:
offset: 2
limit: 2
total: 10
next: /apis?limit=2&offset=4
previous: /apis?limit=2&offset=0
API:
title: API object
required:
- context
- lifeCycleStatus
- name
- provider
- version
type: object
properties:
id:
type: string
description: 'UUID of the api
'
example: 01234567-0123-0123-0123-012345678901
name:
type: string
description: Name of the API
example: CalculatorAPI
displayName:
description: Human-friendly name shown in UI. Length limited to DB column size.
type: string
example: Pizza Shack API
description:
type: string
description: A brief description about the API
example: A calculator API that supports basic operations
context:
type: string
description: A string that represents thecontext of the user's request
example: CalculatorAPI
version:
type: string
description: The version of the API
example: 1.0.0
provider:
type: string
description: 'If the provider value is not given user invoking the api will be used as the provider.
'
example: admin
apiDefinition:
type: string
description: 'Swagger definition of the API which contains details about URI templates and scopes
'
example: '{"paths":{"\/substract":{"get":{"x-auth-type":"Application & Application User","x-throttling-tier":"Unlimited","parameters":[{"name":"x","required":true,"type":"string","in":"query"},{"name":"y","required":true,"type":"string","in":"query"}],"responses":{"200":{}}}},"\/add":{"get":{"x-auth-type":"Application & Application User","x-throttling-tier":"Unlimited","parameters":[{"name":"x","required":true,"type":"string","in":"query"},{"name":"y","required":true,"type":"string","in":"query"}],"responses":{"200":{}}}}},"swagger":"2.0","info":{"title":"CalculatorAPI","version":"1.0.0"}}'
wsdlUri:
type: string
description: 'WSDL URL if the API is based on a WSDL endpoint
'
example: http://www.webservicex.com/globalweather.asmx?wsdl
lifeCycleStatus:
type: string
description: This describes in which status of the lifecycle the API is.
example: PUBLISHED
isDefaultVersion:
type: boolean
example: false
type:
type: string
description: This describes the transport type of the API
example: HTTP
transport:
type: array
example:
- http
- https
items:
type: string
description: 'Supported transports for the API (http and/or https).
'
operations:
type: array
example: []
items:
$ref: '#/components/schemas/APIOperations'
authorizationHeader:
type: string
description: 'Name of the Authorization header used for invoking the API. If it is not set, Authorization header name specified
in tenant or system level will be used.
'
example: Authorization
apiKeyHeader:
type: string
description: 'Name of the API key header used for invoking the API. If it is not set, default value `apiKey` will be used.
'
example: ApiKey
securityScheme:
type: array
description: 'Types of API security, the current API secured with. It can be either OAuth2 or mutual SSL or both. If
it is not set OAuth2 will be set as the security for the current API.
'
example:
- oauth2
- oauth_basic_auth_api_key_mandatory
items:
type: string
tags:
type: array
description: Search keywords related to the API
example:
- substract
- add
items:
type: string
tiers:
type: array
description: The subscription tiers selected for the particular API
items:
type: object
properties:
tierName:
type: string
example: Gold
tierPlan:
type: string
example: COMMERCIAL
monetizationAttributes:
type: object
properties:
fixedPrice:
type: string
example: '10'
pricePerRequest:
type: string
example: '1'
currencyType:
type: string
example: USD
billingCycle:
type: string
example: month
hasThumbnail:
type: boolean
example: true
default: false
additionalProperties:
type: array
items:
type: object
properties:
name:
type: string
value:
type: string
display:
type: boolean
description: 'Custom(user defined) properties of API
'
example: {}
monetization:
$ref: '#/components/schemas/APIMonetizationInfo'
endpointURLs:
type: array
items:
type: object
properties:
environmentName:
type: string
example: Default
environmentDisplayName:
type: string
example: Default
environmentType:
type: string
example: hybrid
URLs:
type: object
properties:
http:
type: string
description: HTTP environment URL
example: http://localhost:8280/phoneverify/1.0.0
https:
type: string
description: HTTPS environment URL
example: https://localhost:8243/phoneverify/1.0.0
ws:
type: string
description: WS environment URL
example: ws://localhost:9099/phoneverify/1.0.0
wss:
type: string
description: WSS environment URL
example: wss://localhost:9099/phoneverify/1.0.0
defaultVersionURLs:
type: object
properties:
http:
type: string
description: HTTP environment default URL
example: http://localhost:8280/phoneverify/
https:
type: string
description: HTTPS environment default URL
example: https://localhost:8243/phoneverify/
ws:
type: string
description: WS environment default URL
example: ws://localhost:9099/phoneverify/
wss:
type: string
description: WSS environment default URL
example: wss://localhost:9099/phoneverify/
businessInformation:
$ref: '#/components/schemas/APIBusinessInformation'
environmentList:
type: array
description: The environment list configured with non empty endpoint URLs for the particular API.
example:
- PRODUCTION
- SANDBOX
items:
type: string
scopes:
type: array
items:
$ref: '#/components/schemas/ScopeInfo'
avgRating:
type: string
description: The average rating of the API
example: '4.5'
subscriptions:
type: integer
format: int64
description: The number of subscriptions for the API
example: 10
advertiseInfo:
$ref: '#/components/schemas/AdvertiseInfo'
isSubscriptionAvailable:
type: boolean
example: false
initiatedFromGateway:
type: boolean
description: Flag indicating this API was discovered/initiated via the gateway (federated discovery) rather than created in the Control Plane.
example: false
categories:
type: array
description: 'API categories
'
items:
type: string
example: Marketing
keyManagers:
type: object
properties: {}
description: 'API Key Managers
'
example:
- all
createdTime:
type: string
example: 2020-10-31 13:57:16.229000
lastUpdatedTime:
type: string
example: 2020-10-31 13:57:16.229000
gatewayType:
title: Gateway type of the API
type: string
example: solace
gatewayVendor:
title: Gateway vendor of the API
type: string
example: wso2
asyncTransportProtocols:
type: array
description: 'Supported transports for the aync API.
'
example:
- http
- mqtt
items:
type: string
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
MonetizationInfo:
title: Monetization
type: object
properties:
billingType:
type: string
example: fixedPrice
enum:
- fixedPrice
- dynamicRate
billingCycle:
type: string
example: month
fixedPrice:
type: string
example: '10'
pricePerRequest:
type: string
example: '1'
currencyType:
type: string
example: USD
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
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
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wso2/refs/heads/main/openapi/wso2-mcp-servers-api-openapi.yml