openapi: 3.2.0 info: title: Pipeshub Toolset Instances API version: 1.0.0 contact: name: API Support email: support@pipeshub.com description: 'Operations tagged Toolset Instances across 2 of this provider''s published API definitions: pipeshub-openapi.yaml, pipeshub-openapi.yml. Each path carries the servers of the definition it was published in.' 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 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 /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 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 /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 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 /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 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 /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 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 /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 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 /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 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 /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 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 /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 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 /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 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 /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 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 /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 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 /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 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 /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 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 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 x-refined-from: - pipeshub-openapi.yaml - pipeshub-openapi.yml