openapi: 3.2.0
info:
  title: HasMCP Manager Providers API
  version: 1.0.0
  description: API for managing HasMCP components like Variables, Providers, MCP Servers, Resources, and Prompts.
security:
- bearerAuth: []
tags:
- name: Providers
paths:
  /providers:
    get:
      summary: List Providers
      operationId: listProviders
      security:
      - oauth2:
        - provider:list
      parameters:
      - name: nameContains
        in: query
        schema:
          type: string
      - name: baseURLContains
        in: query
        schema:
          type: string
      - name: apiType
        in: query
        schema:
          type: string
      - name: visibility
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
      - name: token
        in: query
        schema:
          type: string
      responses:
        '200':
          description: A list of providers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProvidersResponse'
      tags:
      - Providers
    post:
      summary: Create Provider
      operationId: createProvider
      security:
      - oauth2:
        - provider:create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProviderRequest'
      responses:
        '201':
          description: Provider created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateProviderResponse'
      tags:
      - Providers
  /providers/{id}:
    get:
      summary: Get Provider
      operationId: getProvider
      security:
      - oauth2:
        - provider:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Provider ID
      responses:
        '200':
          description: Provider details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetProviderResponse'
      tags:
      - Providers
    patch:
      summary: Update Provider
      operationId: updateProvider
      security:
      - oauth2:
        - provider:update
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Provider ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProviderRequest'
      responses:
        '200':
          description: Provider updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateProviderResponse'
      tags:
      - Providers
    delete:
      summary: Delete Provider
      operationId: deleteProvider
      security:
      - oauth2:
        - provider:delete
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Provider ID
      responses:
        '204':
          description: Provider deleted
      tags:
      - Providers
  /providers/{id}/tools:
    get:
      summary: List Provider Tools
      operationId: listProviderTools
      security:
      - oauth2:
        - provider:list
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Provider ID
      responses:
        '200':
          description: A list of provider tools
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProviderToolsResponse'
      tags:
      - Providers
    post:
      summary: Create Provider Tool
      operationId: createProviderTool
      security:
      - oauth2:
        - provider:create
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Provider ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProviderToolRequest'
      responses:
        '201':
          description: Tool created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateProviderToolResponse'
      tags:
      - Providers
  /providers/{id}/tools/{toolID}:
    get:
      summary: Get Provider Tool
      operationId: getProviderTool
      security:
      - oauth2:
        - provider:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Provider ID
      - name: toolID
        in: path
        required: true
        schema:
          type: string
          description: Tool ID
      responses:
        '200':
          description: Tool details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetProviderToolResponse'
      tags:
      - Providers
    patch:
      summary: Update Provider Tool
      operationId: updateProviderTool
      security:
      - oauth2:
        - provider:update
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Provider ID
      - name: toolID
        in: path
        required: true
        schema:
          type: string
          description: Tool ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProviderToolRequest'
      responses:
        '200':
          description: Tool updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateProviderToolResponse'
      tags:
      - Providers
    delete:
      summary: Delete Provider Tool
      operationId: deleteProviderTool
      security:
      - oauth2:
        - provider:delete
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Provider ID
      - name: toolID
        in: path
        required: true
        schema:
          type: string
          description: Tool ID
      responses:
        '204':
          description: Tool deleted
      tags:
      - Providers
  /providers/{id}/resources:
    get:
      summary: List Provider Resources
      operationId: listProviderResources
      security:
      - oauth2:
        - provider:list
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Provider ID
      responses:
        '200':
          description: A list of provider resources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProviderResourcesResponse'
      tags:
      - Providers
    post:
      summary: Create Provider Resource
      operationId: createProviderResource
      security:
      - oauth2:
        - provider:create
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Provider ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProviderResourceRequest'
      responses:
        '201':
          description: Provider Resource created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateProviderResourceResponse'
      tags:
      - Providers
  /providers/{id}/resources/{resourceID}:
    get:
      summary: Get Provider Resource
      operationId: getProviderResource
      security:
      - oauth2:
        - provider:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Provider ID
      - name: resourceID
        in: path
        required: true
        schema:
          type: string
          description: Resource ID
      responses:
        '200':
          description: Provider Resource details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetProviderResourceResponse'
      tags:
      - Providers
    patch:
      summary: Update Provider Resource
      operationId: updateProviderResource
      security:
      - oauth2:
        - provider:update
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Provider ID
      - name: resourceID
        in: path
        required: true
        schema:
          type: string
          description: Resource ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProviderResourceRequest'
      responses:
        '200':
          description: Provider Resource updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateProviderResourceResponse'
      tags:
      - Providers
    delete:
      summary: Delete Provider Resource
      operationId: deleteProviderResource
      security:
      - oauth2:
        - provider:delete
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Provider ID
      - name: resourceID
        in: path
        required: true
        schema:
          type: string
          description: Resource ID
      responses:
        '204':
          description: Provider Resource deleted
      tags:
      - Providers
  /providers/{id}/prompts:
    get:
      summary: List Provider Prompts
      operationId: listProviderPrompts
      security:
      - oauth2:
        - provider:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Provider ID
      responses:
        '200':
          description: A list of provider prompts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProviderPromptsResponse'
      tags:
      - Providers
    post:
      summary: Create Provider Prompt
      operationId: createProviderPrompt
      security:
      - oauth2:
        - provider:update
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Provider ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProviderPromptRequest'
      responses:
        '201':
          description: Provider Prompt created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateProviderPromptResponse'
      tags:
      - Providers
  /providers/{id}/prompts/{promptID}:
    get:
      summary: Get Provider Prompt
      operationId: getProviderPrompt
      security:
      - oauth2:
        - provider:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Provider ID
      - name: promptID
        in: path
        required: true
        schema:
          type: string
          description: Prompt ID
      responses:
        '200':
          description: Provider Prompt details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetProviderPromptResponse'
      tags:
      - Providers
    patch:
      summary: Update Provider Prompt
      operationId: updateProviderPrompt
      security:
      - oauth2:
        - provider:update
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Provider ID
      - name: promptID
        in: path
        required: true
        schema:
          type: string
          description: Prompt ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProviderPromptRequest'
      responses:
        '204':
          description: Provider Prompt updated
      tags:
      - Providers
    delete:
      summary: Delete Provider Prompt
      operationId: deleteProviderPrompt
      security:
      - oauth2:
        - provider:update
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Provider ID
      - name: promptID
        in: path
        required: true
        schema:
          type: string
          description: Prompt ID
      responses:
        '204':
          description: Provider Prompt deleted
      tags:
      - Providers
components:
  schemas:
    ProviderCreate:
      type: object
      properties:
        apiType:
          type: string
          description: '0: INVALID, 1: REST'
          example: REST
        visibilityType:
          type: string
          description: '0: INVALID, 1: INTERNAL, 2: PUBLIC'
          example: PUBLIC
        baseURL:
          type: string
          format: uri
        documentURL:
          type: string
          format: uri
        iconURL:
          type: string
          format: uri
        name:
          type: string
        description:
          type: string
        oauth2Config:
          $ref: '#/components/schemas/ProviderOAuth2Config'
    ProviderResource:
      type: object
      properties:
        id:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        name:
          type: string
        description:
          type: string
        uri:
          type: string
          format: uri
        mimeType:
          type: string
          example: text/plain
        size:
          type: integer
          format: int64
        annotations:
          type: object
          description: A raw JSON message for annotations.
          additionalProperties: true
    CreateProviderPromptResponse:
      type: object
      properties:
        prompt:
          $ref: '#/components/schemas/ProviderPrompt'
    CreateProviderToolRequest:
      type: object
      properties:
        tool:
          $ref: '#/components/schemas/ProviderToolCreate'
    ProviderPromptCreate:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        arguments:
          type: object
          description: A raw JSON message for arguments (e.g., []PromptArgument).
          additionalProperties: true
        messages:
          type: object
          description: A raw JSON message for messages (e.g., []PromptMessage).
          additionalProperties: true
    ListProvidersResponse:
      type: object
      properties:
        providers:
          type: array
          items:
            $ref: '#/components/schemas/Provider'
        matchCount:
          type: integer
        nextToken:
          type: string
    UpdateProviderResourceRequest:
      type: object
      properties:
        resource:
          $ref: '#/components/schemas/ProviderResourceCreate'
    CreateProviderPromptRequest:
      type: object
      properties:
        prompt:
          $ref: '#/components/schemas/ProviderPromptCreate'
    ProviderOAuth2Config:
      type: object
      properties:
        clientID:
          type: string
        clientSecret:
          type: string
        authURL:
          type: string
          format: uri
        tokenURL:
          type: string
          format: uri
    GetProviderResponse:
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/Provider'
    CreateProviderRequest:
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/ProviderCreate'
    CreateProviderResourceRequest:
      type: object
      properties:
        resource:
          $ref: '#/components/schemas/ProviderResourceCreate'
    ListProviderToolsResponse:
      type: object
      properties:
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ProviderTool'
    ProviderToolCreate:
      type: object
      properties:
        providerID:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
          description: This will be ignored, as providerID is taken from the path.
        method:
          type: string
          example: GET
        path:
          type: string
          example: /users/{id}
        name:
          type: string
          description: MCP tool name (camelCase up to 20chars)
          example: makePayment
        title:
          type: string
          description: MCP tool title (Free text up to 64 chars)
          example: Make Payment
        description:
          type: string
        pathArgsJSONSchema:
          type: object
          description: A raw JSON schema.
          additionalProperties: true
        queryArgsJSONSchema:
          type: object
          description: A raw JSON schema.
          additionalProperties: true
        reqBodyJSONSchema:
          type: object
          description: A raw JSON schema.
          additionalProperties: true
        headers:
          type: array
          items:
            $ref: '#/components/schemas/ToolHeader'
        oauth2Scopes:
          type: array
          items:
            type: string
    ListProviderPromptsResponse:
      type: object
      properties:
        prompts:
          type: array
          items:
            $ref: '#/components/schemas/ProviderPrompt'
    CreateProviderResourceResponse:
      type: object
      properties:
        resource:
          $ref: '#/components/schemas/ProviderResource'
    CreateProviderToolResponse:
      type: object
      properties:
        tool:
          $ref: '#/components/schemas/ProviderTool'
    Provider:
      type: object
      properties:
        id:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        version:
          type: integer
          format: int32
          readOnly: true
        apiType:
          type: string
          description: '0: INVALID, 1: REST'
          example: REST
        visibilityType:
          type: string
          description: '0: INVALID, 1: INTERNAL, 2: PUBLIC'
          example: PUBLIC
        baseURL:
          type: string
          format: uri
        documentURL:
          type: string
          format: uri
        iconURL:
          type: string
          format: uri
        secretPrefix:
          type: string
          readOnly: true
        name:
          type: string
        description:
          type: string
        tools:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/ProviderTool'
        oauth2Config:
          $ref: '#/components/schemas/ProviderOAuth2Config'
    ProviderResourceCreate:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        uri:
          type: string
          format: uri
        mimeType:
          type: string
          example: text/plain
        size:
          type: integer
          format: int64
        annotations:
          type: object
          description: A raw JSON message for annotations.
          additionalProperties: true
    UpdateProviderPromptRequest:
      type: object
      properties:
        prompt:
          $ref: '#/components/schemas/ProviderPromptCreate'
    UpdateProviderToolRequest:
      type: object
      properties:
        tool:
          $ref: '#/components/schemas/ProviderToolCreate'
    UpdateProviderResponse:
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/Provider'
    GetProviderPromptResponse:
      type: object
      properties:
        prompt:
          $ref: '#/components/schemas/ProviderPrompt'
    ToolHeader:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
    ListProviderResourcesResponse:
      type: object
      properties:
        resources:
          type: array
          items:
            $ref: '#/components/schemas/ProviderResource'
    GetProviderResourceResponse:
      type: object
      properties:
        resource:
          $ref: '#/components/schemas/ProviderResource'
    CreateProviderResponse:
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/Provider'
    ProviderTool:
      type: object
      properties:
        id:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
          readOnly: true
        providerID:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
        method:
          type: string
          example: GET
        path:
          type: string
          example: /users/{id}
        name:
          type: string
          description: MCP tool name (camelCase up to 20chars)
          example: makePayment
        title:
          type: string
          description: MCP tool title (Free text up to 64 chars)
          example: Make Payment
        description:
          type: string
        pathArgsJSONSchema:
          type: object
          description: A raw JSON schema.
          additionalProperties: true
        queryArgsJSONSchema:
          type: object
          description: A raw JSON schema.
          additionalProperties: true
        reqBodyJSONSchema:
          type: object
          description: A raw JSON schema.
          additionalProperties: true
        headers:
          type: array
          items:
            $ref: '#/components/schemas/ToolHeader'
        oauth2Scopes:
          type: array
          items:
            type: string
    UpdateProviderRequest:
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/ProviderCreate'
    ProviderPrompt:
      type: object
      properties:
        id:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        name:
          type: string
        description:
          type: string
        arguments:
          type: object
          description: A raw JSON message for arguments (e.g., []PromptArgument).
          additionalProperties: true
        messages:
          type: object
          description: A raw JSON message for messages (e.g., []PromptMessage).
          additionalProperties: true
    GetProviderToolResponse:
      type: object
      properties:
        tool:
          $ref: '#/components/schemas/ProviderTool'
    UpdateProviderToolResponse:
      type: object
      properties:
        tool:
          $ref: '#/components/schemas/ProviderTool'
    UpdateProviderResourceResponse:
      type: object
      properties:
        resource:
          $ref: '#/components/schemas/ProviderResource'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Enter 'Bearer' followed by a space and your token (e.g., 'Bearer ${HASMCP_ACCESS_TOKEN}').
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.hasmcp.com/oauth2/auth
          tokenUrl: https://accounts.hasmcp.com/oauth2/token
          scopes:
            gitconnection:list: List Git connections
            gitconnection:delete: Delete Git connection
            variable:list: List variables
            variable:create: Create variable
            variable:update: Update variable
            variable:delete: Delete variable
            provider:list: List providers
            provider:create: Create provider
            provider:read: Get provider
            provider:update: Update provider
            provider:delete: Delete provider
            server:list: List MCP servers
            server:create: Create MCP server
            server:read: Get MCP server
            server:update: Update MCP server
            server:delete: Delete MCP server
            server:create_token: Create MCP server token