PipesHub Toolset Instances API

openapi: 3.2.0
info:
  title: PipesHub Toolset Instances API
  description: Unified API documentation for PipesHub services.
  version: 1.0.0
  contact:
    name: API Support
    email: support@pipeshub.com
servers:
- url: '{instance_url}/api/v1'
  description: Base API URL
  variables:
    instance_url:
      default: https://app.pipeshub.com
      description: Base server URL (without /api/v1)
- url: '{instance_url}'
  description: Root URL (used for MCP endpoints mounted at /mcp)
  variables:
    instance_url:
      default: https://app.pipeshub.com
      description: Base server URL
security:
- bearerAuth: []
- oauth2: []
tags:
- name: Toolset Instances
  description: Create, manage, and configure toolset instances for your organization
paths:
  /toolsets:
    post:
      tags:
      - Toolset Instances
      summary: Create toolset instance
      description: Create a new toolset instance with authentication configuration
      operationId: createToolset
      security:
      - bearerAuth: []
      requestBody:
        required: true
        description: Toolset instance payload including name, type, authentication configuration, and optional base URL.
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - auth
              properties:
                name:
                  type: string
                displayName:
                  type: string
                type:
                  type: string
                auth:
                  type: object
                  required:
                  - type
                  properties:
                    type:
                      type: string
                    clientId:
                      type: string
                    clientSecret:
                      type: string
                    apiToken:
                      type: string
                    oauthAppId:
                      type: string
                    scopes:
                      type: array
                      items:
                        type: string
                baseUrl:
                  type: string
      responses:
        '201':
          description: Toolset created successfully
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /toolsets/configured:
    get:
      tags:
      - Toolset Instances
      summary: List configured toolsets
      description: Get all configured toolsets for the authenticated user
      operationId: listConfiguredToolsets
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Configured toolsets retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  toolsets:
                    type: array
                    items:
                      type: object
        '401':
          description: Unauthorized
  /toolsets/{toolsetId}/status:
    get:
      tags:
      - Toolset Instances
      summary: Check toolset status
      description: Check authentication status of a toolset instance
      operationId: checkToolsetStatus
      security:
      - bearerAuth: []
      parameters:
      - name: toolsetId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Status retrieved successfully
        '401':
          description: Unauthorized
        '404':
          description: Toolset not found
  /toolsets/{toolsetId}/reauthenticate:
    post:
      tags:
      - Toolset Instances
      summary: Reauthenticate toolset
      description: 'Clear toolset OAuth credentials and mark as unauthenticated, requiring re-authentication.


        Only applicable to OAuth-configured toolsets.'
      operationId: reauthenticateToolset
      security:
      - bearerAuth: []
      parameters:
      - name: toolsetId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Reauthentication initiated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
        '404':
          description: Toolset not found
  /toolsets/agents/{agentKey}:
    get:
      tags:
      - Toolset Instances
      summary: List toolsets for an agent with auth status
      description: 'Returns organization toolset instances merged with the specified agent''s authentication status.

        Same response shape as GET /toolsets/my-toolsets (pagination, filterCounts, toolsets), except there is no `authStatus` query filter.'
      operationId: getAgentToolsets
      security:
      - bearerAuth: []
      parameters:
      - name: agentKey
        in: path
        required: true
        schema:
          type: string
      - name: includeRegistry
        in: query
        required: false
        description: When true, include toolsets from the registry that are not yet configured as synthetic, non-configured entries.
        schema:
          type: boolean
      - name: page
        in: query
        required: false
        description: Page number (1-based).
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        required: false
        description: Page size (max 200).
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 20
      - name: toolsetType
        in: query
        required: false
        description: When set, only instances for this toolset type (case-insensitive). Registry merge is limited to this type when includeRegistry is true.
        schema:
          type: string
      - name: search
        in: query
        required: false
        description: Optional search filter applied to instance name, toolset type, and registry display name/description.
        schema:
          type: string
      responses:
        '200':
          description: Agent toolsets retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      total:
                        type: integer
                      totalPages:
                        type: integer
                      hasNext:
                        type: boolean
                      hasPrev:
                        type: boolean
                  filterCounts:
                    type: object
                    properties:
                      all:
                        type: integer
                      authenticated:
                        type: integer
                      notAuthenticated:
                        type: integer
                  toolsets:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        instanceId:
                          type: string
                          description: Empty string for registry-only (synthetic) entries.
                        instanceName:
                          type: string
                        toolsetType:
                          type: string
                        authType:
                          type: string
                          enum:
                          - OAUTH
                          - API_TOKEN
                          - BEARER_TOKEN
                          - USERNAME_PASSWORD
                          - NONE
                        oauthConfigId:
                          type:
                          - string
                          - 'null'
                        displayName:
                          type: string
                        description:
                          type: string
                        iconPath:
                          type: string
                        category:
                          type: string
                          example: app
                        supportedAuthTypes:
                          type: array
                          items:
                            type: string
                        toolCount:
                          type: integer
                        tools:
                          type: array
                          items:
                            type: object
                            additionalProperties: false
                            properties:
                              name:
                                type: string
                              fullName:
                                type: string
                              description:
                                type: string
                        isConfigured:
                          type: boolean
                        isAuthenticated:
                          type: boolean
                        isFromRegistry:
                          type: boolean
                          description: true for registry-only (synthetic) entries.
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Agent not found
  /toolsets/agents/{agentKey}/instances/{instanceId}/authenticate:
    post:
      tags:
      - Toolset Instances
      summary: Authenticate agent toolset instance
      description: Authenticate an agent-bound toolset instance using the provided credentials.
      operationId: authenticateAgentToolset
      security:
      - bearerAuth: []
      parameters:
      - name: agentKey
        in: path
        required: true
        schema:
          type: string
      - name: instanceId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        description: Authentication payload for the agent-bound toolset instance.
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Agent toolset authenticated successfully
        '400':
          description: Invalid auth payload
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Agent or instance not found
  /toolsets/agents/{agentKey}/instances/{instanceId}/credentials:
    put:
      tags:
      - Toolset Instances
      summary: Update agent toolset credentials
      description: Update the stored credentials for an agent-bound toolset instance.
      operationId: updateAgentToolsetCredentials
      security:
      - bearerAuth: []
      parameters:
      - name: agentKey
        in: path
        required: true
        schema:
          type: string
      - name: instanceId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        description: New credentials to apply to the agent-bound toolset instance.
        content:
          application/json:
            schema:
              type: object
              properties:
                auth:
                  type: object
                  properties:
                    email:
                      type: string
                    apiToken:
                      type: string
                    username:
                      type: string
                    password:
                      type: string
      responses:
        '200':
          description: Agent credentials updated successfully
        '400':
          description: Invalid credentials payload
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Agent or instance not found
    delete:
      tags:
      - Toolset Instances
      summary: Remove agent toolset credentials
      description: Delete the stored credentials for an agent-bound toolset instance.
      operationId: removeAgentToolsetCredentials
      security:
      - bearerAuth: []
      parameters:
      - name: agentKey
        in: path
        required: true
        schema:
          type: string
      - name: instanceId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Agent credentials removed successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Agent or instance not found
  /toolsets/agents/{agentKey}/instances/{instanceId}/reauthenticate:
    post:
      tags:
      - Toolset Instances
      summary: Mark agent instance for reauthentication
      description: Flag an agent-bound toolset instance as requiring the user to re-authenticate.
      operationId: reauthenticateAgentToolset
      security:
      - bearerAuth: []
      parameters:
      - name: agentKey
        in: path
        required: true
        schema:
          type: string
      - name: instanceId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Agent reauthentication required
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Agent or instance not found
  /toolsets/instances:
    get:
      tags:
      - Toolset Instances
      summary: List toolset instances
      description: List all toolset instances configured for the organization.
      operationId: getToolsetInstances
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Instances retrieved successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          description: Unauthorized
    post:
      tags:
      - Toolset Instances
      summary: Create toolset instance
      description: Create a new toolset instance (admin only).
      operationId: createToolsetInstance
      security:
      - bearerAuth: []
      requestBody:
        required: true
        description: Toolset instance payload including name, type, auth type, auth configuration, and optional base URL.
        content:
          application/json:
            schema:
              type: object
              required:
              - instanceName
              - toolsetType
              - authType
              properties:
                instanceName:
                  type: string
                toolsetType:
                  type: string
                authType:
                  type: string
                authConfig:
                  type: object
                  additionalProperties: true
                baseUrl:
                  type: string
                oauthConfigId:
                  type: string
                oauthInstanceName:
                  type: string
      responses:
        '201':
          description: Instance created successfully
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /toolsets/instances/{instanceId}:
    get:
      tags:
      - Toolset Instances
      summary: Get toolset instance
      description: Retrieve a single toolset instance by its identifier.
      operationId: getToolsetInstance
      security:
      - bearerAuth: []
      parameters:
      - name: instanceId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Instance retrieved successfully
        '401':
          description: Unauthorized
        '404':
          description: Instance not found
    put:
      tags:
      - Toolset Instances
      summary: Update toolset instance
      description: Update an existing toolset instance's configuration (admin only).
      operationId: updateToolsetInstance
      security:
      - bearerAuth: []
      parameters:
      - name: instanceId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        description: Updated fields for the toolset instance.
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Instance updated successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Instance not found
    delete:
      tags:
      - Toolset Instances
      summary: Delete toolset instance
      description: Delete a toolset instance and its associated configuration (admin only).
      operationId: deleteToolsetInstance
      security:
      - bearerAuth: []
      parameters:
      - name: instanceId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Instance deleted successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Instance not found
  /toolsets/instances/{instanceId}/authenticate:
    post:
      tags:
      - Toolset Instances
      summary: Authenticate toolset instance
      description: Authenticate a toolset instance using the provided credentials.
      operationId: authenticateToolsetInstance
      security:
      - bearerAuth: []
      parameters:
      - name: instanceId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        description: Authentication payload for the toolset instance.
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Instance authenticated successfully
        '400':
          description: Invalid auth payload
        '401':
          description: Unauthorized
        '404':
          description: Instance not found
  /toolsets/instances/{instanceId}/credentials:
    put:
      tags:
      - Toolset Instances
      summary: Update toolset credentials
      description: Update the stored credentials for a toolset instance.
      operationId: updateToolsetCredentials
      security:
      - bearerAuth: []
      parameters:
      - name: instanceId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        description: New credentials to apply to the toolset instance.
        content:
          application/json:
            schema:
              type: object
              properties:
                auth:
                  type: object
                  properties:
                    email:
                      type: string
                    apiToken:
                      type: string
                    username:
                      type: string
                    password:
                      type: string
      responses:
        '200':
          description: Credentials updated successfully
        '400':
          description: Invalid credentials payload
        '401':
          description: Unauthorized
        '404':
          description: Instance not found
    delete:
      tags:
      - Toolset Instances
      summary: Remove toolset credentials
      description: Delete the stored credentials for a toolset instance.
      operationId: removeToolsetCredentials
      security:
      - bearerAuth: []
      parameters:
      - name: instanceId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Credentials removed successfully
        '401':
          description: Unauthorized
        '404':
          description: Instance not found
  /toolsets/instances/{instanceId}/reauthenticate:
    post:
      tags:
      - Toolset Instances
      summary: Mark instance for reauthentication
      description: Flag the toolset instance as requiring the user to re-authenticate.
      operationId: reauthenticateToolsetInstance
      security:
      - bearerAuth: []
      parameters:
      - name: instanceId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Reauthentication required
        '401':
          description: Unauthorized
        '404':
          description: Instance not found
  /toolsets/instances/{instanceId}/status:
    get:
      tags:
      - Toolset Instances
      summary: Get instance authentication status
      description: Report whether the toolset instance is configured and authenticated.
      operationId: getToolsetInstanceStatus
      security:
      - bearerAuth: []
      parameters:
      - name: instanceId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Status retrieved successfully
        '401':
          description: Unauthorized
        '404':
          description: Instance not found
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT Bearer token for authenticated requests.


        A personal access token (see the **Personal Access Tokens** tag) is a

        `phpat_`-prefixed variant of this same JWT — e.g. `phpat_eyJhbGci...`.

        The prefix is display-only, added for secret-scanner detectability; the

        gateway strips it before verifying the token, so send it exactly as

        issued, prefix included.

        '
    scopedToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Scoped JWT token for service-to-service authentication.

        Format: "Bearer {scoped_token}"

        Required scopes vary by endpoint.

        '
    oauth2:
      type: oauth2
      description: 'OAuth 2.0 authentication with fine-grained scopes.

        Supports authorization_code (with PKCE) and client_credentials flows.

        OAuth tokens are Bearer JWTs — use the same Authorization header as regular tokens.

        For **client_credentials**, machine JWTs may use `userId === client_id`; the Node gateway resolves the OAuth app creator — see **OAuth Provider** tag.

        '
      flows:
        authorizationCode:
          authorizationUrl: /api/v1/oauth2/authorize
          tokenUrl: /api/v1/oauth2/token
          refreshUrl: /api/v1/oauth2/token
          scopes:
            openid: OpenID Connect authentication
            profile: User profile information
            email: User email address
            offline_access: Offline access (refresh tokens)
            org:read: Read organization information
            org:write: Update organization settings
            org:admin: Full organization administration
            user:read: Read user profiles
            user:write: Update user profiles
            user:invite: Invite new users
            user:delete: Delete users
            usergroup:read: Read user groups
            usergroup:write: Create and manage user groups
            team:read: Read team information
            team:write: Create and manage teams
            kb:read: Read knowledge bases and records
            kb:write: Create and update knowledge bases
            kb:delete: Delete knowledge bases and records
            kb:upload: Upload files to knowledge bases
            semantic:read: Read semantic search results and history
            semantic:write: Execute semantic search
            semantic:delete: Delete semantic search history
            conversation:read: Read conversations
            conversation:write: Create and manage conversations
            conversation:chat: Send messages in conversations
            project:read: Read projects and their conversations
            project:write: Create and manage projects
            project:delete: Delete projects
            agent:read: Read AI agents
            agent:write: Create and manage AI agents
            agent:execute: Execute AI agents
            connector:read: Read connector configurations
            connector:write: Create and update connectors
            connector:sync: Trigger connector synchronization
            connector:delete: Delete connectors
            config:read: Read system configuration
            config:write: Update system configuration
            crawl:read: Read crawling jobs
            crawl:write: Create and manage crawling jobs
            crawl:delete: Delete crawling jobs
        clientCredentials:
          tokenUrl: /api/v1/oauth2/token
          scopes:
            openid: OpenID Connect authentication
            profile: User profile information
            email: User email address
            offline_access: Offline access (refresh tokens)
            org:read: Read organization information
            org:write: Update organization settings
            org:admin: Full organization administration
            user:read: Read user profiles
            user:write: Update user profiles
            user:invite: Invite new users
            user:delete: Delete users
            usergroup:read: Read user groups
            usergroup:write: Create and manage user groups
            team:read: Read team information
            team:write: Create and manage teams
            kb:read: Read knowledge bases and records
            kb:write: Create and update knowledge bases
            kb:delete: Delete knowledge bases and records
            kb:upload: Upload files to knowledge bases
            semantic:write: Execute semantic search
            semantic:read: Read semantic search results and history
            semantic:delete: Delete semantic search history
            conversation:read: Read conversations
            conversation:write: Create and manage conversations
            conversation:chat: Send messages in conversations
            project:read: Read projects and their conversations
            project:write: Create and manage projects
            project:delete: Delete projects
            agent:read: Read AI agents
            agent:write: Create and manage AI agents
            agent:execute: Execute AI agents
            connector:read: Read connector configurations
            connector:write: Create and update connectors
            connector:sync: Trigger connector synchronization
            connector:delete: Delete connectors
            config:read: Read system configuration
            config:write: Update system configuration
            crawl:read: Read crawling jobs
            crawl:write: Create and manage crawling jobs