pipeshub-sdk-go

pipeshub-sdk is the official Go client library for integrating Pipeshub into your product and internal tools

Summary

PipesHub API: Unified API documentation for PipesHub services.

PipesHub is an enterprise-grade platform providing:

• User authentication and management
• Document storage and version control
• Knowledge base management
• Enterprise search and conversational AI
• Third-party integrations via connectors
• System configuration management
• Crawling job scheduling
• Email services

Authentication

Most endpoints require JWT Bearer token authentication. Some internal endpoints use scoped tokens for service-to-service communication.

Base URLs

All endpoints use the /api/v1 prefix unless otherwise noted.

Table of Contents

• pipeshub-sdk-go
  • Authentication
  • Base URLs
  • SDK Installation
  • SDK Example Usage
  • Authentication
  • Available Resources and Operations
  • Server-sent event streaming
  • Retries
  • Error Handling
  • Server Selection
  • Custom HTTP Client

SDK Installation

To add the SDK as a dependency to your project:

go get github.com/pipeshub-ai/pipeshub-sdk-go

SDK Example Usage

Example

package main

import (
	"context"
	pipeshub "github.com/pipeshub-ai/pipeshub-sdk-go"
	"github.com/pipeshub-ai/pipeshub-sdk-go/models/components"
	"log"
)

func main() {
	ctx := context.Background()

	s := pipeshub.New()

	res, err := s.UserAccount.InitAuth(ctx, components.InitAuthRequest{
		Email: "user@example.com",
	})
	if err != nil {
		log.Fatal(err)
	}
	if res.InitAuthResponse != nil {
		// handle response
	}
}

Authentication

Per-Client Security Schemes

This SDK supports the following security schemes globally:

Name	Type	Scheme	Environment Variable
BearerAuth	http	HTTP Bearer	PIPESHUB_BEARER_AUTH
Oauth2	oauth2	OAuth2 token	PIPESHUB_OAUTH2

You can set the security parameters through the WithSecurity option when initializing the SDK client instance. The selected scheme will be used by default to authenticate with the API for all operations that support it. For example:

package main

import (
	"context"
	pipeshub "github.com/pipeshub-ai/pipeshub-sdk-go"
	"github.com/pipeshub-ai/pipeshub-sdk-go/models/components"
	"log"
	"os"
)

func main() {
	ctx := context.Background()

	s := pipeshub.New(
		pipeshub.WithSecurity(components.Security{
			BearerAuth: pipeshub.Pointer(os.Getenv("PIPESHUB_BEARER_AUTH")),
		}),
	)

	res, err := s.UserAccount.InitAuth(ctx, components.InitAuthRequest{
		Email: "user@example.com",
	})
	if err != nil {
		log.Fatal(err)
	}
	if res.InitAuthResponse != nil {
		// handle response
	}
}

Per-Operation Security Schemes

Some operations in this SDK require the security scheme to be specified at the request level. For example:

package main

import (
	"context"
	pipeshub "github.com/pipeshub-ai/pipeshub-sdk-go"
	"github.com/pipeshub-ai/pipeshub-sdk-go/models/components"
	"github.com/pipeshub-ai/pipeshub-sdk-go/models/operations"
	"log"
	"os"
)

func main() {
	ctx := context.Background()

	s := pipeshub.New()

	res, err := s.UserAccount.ResetPasswordWithToken(ctx, components.TokenPasswordResetRequest{
		Password: "H9GEHoL829GXj06",
	}, operations.ResetPasswordWithTokenSecurity{
		ScopedToken: os.Getenv("PIPESHUB_SCOPED_TOKEN"),
	})
	if err != nil {
		log.Fatal(err)
	}
	if res.PasswordResetResponse != nil {
		// handle response
	}
}

Available Resources and Operations

Available methods

AgentConversations

• List - List agent conversations
• CreateConversation - Create agent conversation
• Stream - Create agent conversation with streaming
• Get - Get agent conversation
• Delete - Delete agent conversation
• AddMessage - Add message to agent conversation
• StreamMessage - Add message with streaming
• RegenerateAnswer - Regenerate agent response

Agents

• List - List agents
• Create - Create agent
• ListTools - List available tools
• Get - Get agent
• Update - Update agent
• Delete - Delete agent
• GetPermissions - Get agent permissions
• UpdatePermissions - Update agent permissions
• Share - Share agent
• Unshare - Unshare an agent

AgentTemplates

• List - List agent templates
• Create - Create agent template
• Get - Get agent template
• Update - Update agent template
• Delete - Delete agent template

AiModelsProviders

• GetByType - Get models by type
• GetAvailableModels - Get available models for selection
• Add - Add new AI model provider
• Update - Update AI model provider
• Delete - Delete AI model provider
• SetDefault - Set default AI model

AuthConfig

• SetGoogle - Configure Google authentication

AuthConfigurations

• SetOAuth - Configure generic OAuth provider

AuthenticationConfiguration

• SetAzureAdAuthConfig - Configure Azure AD authentication
• GetAzureAd - Get Azure AD configuration
• SetMicrosoftAuth - Configure Microsoft authentication
• GetMicrosoft - Get Microsoft authentication configuration
• GetGoogleAuthConfig - Get Google authentication configuration
• SetSsoAuthConfig - Configure SAML SSO authentication
• GetSSO - Get SAML SSO configuration
• GetGenericOAuth - Get generic OAuth configuration

ConfigurationManager

• GetSlackBotConfigs - Get Slack bot configurations
• CreateSlackBotConfig - Create Slack bot configuration
• UpdateSlackBotConfig - Update Slack bot configuration
• DeleteSlackBotConfig - Delete Slack bot configuration
• SetMetricsCollectionPushInterval - Set metrics push interval
• SetMetricsServerURL - Set metrics remote server URL
• GetAIModels - Get AI models configuration
• CreateAIModelsConfig - Create AI models configuration
• GetAIModelsProviders - Get AI model providers

Connector

• ReindexRecord - Reindex single record
• ReindexGroup - Reindex record group
• Resync - Resync connector

ConnectorConfiguration

• Get - Get connector configuration
• Update - Update connector configuration
• UpdateAuth - Update authentication configuration
• UpdateFiltersSync - Update filters and sync configuration

ConnectorControl

• Toggle - Toggle connector sync or agent

ConnectorFilters

• Get - Get filter options
• Save - Save filter selections
• GetFilterOptions - Get dynamic filter options

ConnectorInstances

• List - List connector instances
• Create - Create connector instance
• ListActive - List active connector instances
• ListInactive - List inactive connector instances
• ListConfigured - List configured connector instances
• ListActiveAgents - List active agent connectors
• Get - Get connector instance
• Delete - Delete connector instance
• UpdateName - Update connector instance name

ConnectorOAuth

• Authorize - Get OAuth authorization URL
• HandleCallback - OAuth callback handler
• ExchangeLegacyToken - Exchange Google authorization code for tokens ⚠️ Deprecated

ConnectorRegistry

• List - List available connector types
• GetSchemaForType - Get connector configuration schema

Connectors

• GetStats - Get connector statistics

Conversations

• Create - Create a new AI conversation
• Stream - Create conversation with streaming response
• List - List all conversations
• ListArchives - List archived conversations
• Get - Get conversation by ID
• Delete - Delete conversation
• AddMessage - Add message to conversation
• AddMessageStream - Add message with streaming response
• Share - Share conversation with users
• UpdateTitle - Update conversation title
• Archive - Archive conversation
• Unarchive - Unarchive conversation
• Regenerate - Regenerate AI response
• SubmitFeedback - Submit feedback on AI response
• Unshare - Unshare a conversation

CrawlingJobs

• Schedule - Schedule a crawling job
• GetStatus - Get crawling job status
• Remove - Remove a crawling job
• ListAllStatuses - Get all crawling job statuses
• RemoveAll - Remove all crawling jobs
• Pause - Pause a crawling job
• Resume - Resume a crawling job
• GetQueueStats - Get queue statistics

DocumentManagement

• Download - Download document

Folders

• CreateRoot - Create root folder
• GetContents - Get folder contents
• Update - Update folder
• Delete - Delete folder
• GetChildren - Get folder children (alias for folder contents)
• Create - Create subfolder

KnowledgeBases

• Create - Create a new knowledge base
• List - List all knowledge bases
• Get - Get knowledge base by ID
• Update - Update knowledge base
• Delete - Delete knowledge base
• ReindexFailedRecords - Reindex failed records for connector
• MoveRecord - Move record to another location
• GetRootNodes - Get knowledge hub root nodes
• GetChildNodes - Get knowledge hub child nodes

Mcp

• HandleRequest - Handle MCP JSON-RPC request
• Stream - MCP SSE streaming endpoint

MetricsCollection

• Get - Get metrics collection configuration
• Toggle - Enable or disable metrics collection

Oauth

• ExchangeCode - Exchange OAuth authorization code for tokens

OauthApps

• List - List OAuth apps
• Create - Create OAuth app
• ListScopes - List available scopes
• Get - Get OAuth app details
• Update - Update OAuth app
• Delete - Delete OAuth app
• RegenerateSecret - Regenerate client secret
• Suspend - Suspend OAuth app
• Activate - Activate suspended OAuth app
• ListTokens - List app tokens
• RevokeAllTokens - Revoke all app tokens

OauthConfigs

• ListAll - List OAuth configurations
• UpdateByID - Update OAuth configuration

OauthConfiguration

• ListToolsetConfigs - List OAuth configs by toolset type
• DeleteConfig - Delete OAuth config
• List - List OAuth-capable connector types
• GetConnectorTypeDetails - Get OAuth connector type details
• ListConfigsByType - List OAuth configs for connector type
• Create - Create OAuth configuration
• Get - Get OAuth configuration

OauthConfigurations

• Update - Update OAuth config
• Delete - Delete OAuth configuration

OauthProvider

• Authorize - Initiate OAuth authorization flow
• AuthorizeConsent - Submit authorization consent
• ExchangeToken - Exchange authorization code for tokens
• RevokeToken - Revoke an access or refresh token
• IntrospectToken - Introspect a token

OpenIDConnect

• UserInfo - Get authenticated user information
• OauthAuthorizationServerMetadata - OAuth 2.0 Authorization Server Metadata
• Jwks - JSON Web Key Set
• GetProtectedResourceMetadata - OAuth Protected Resource Metadata
• GetConfiguration - OpenID Connect Discovery

OrganizationAuthConfig

• GetAuthMethods - Get organization authentication methods
• UpdateAuthMethod - Update organization authentication methods
• SetUp - Set up auth configuration

Organizations

• CheckExists - Check if organization exists
• Create - Create organization
• GetCurrent - Get current organization
• Update - Update organization
• Delete - Delete organization
• UploadLogo - Upload organization logo
• GetLogo - Get organization logo
• DeleteLogo - Delete organization logo
• GetOnboardingStatus - Get onboarding status
• UpdateOnboardingStatus - Update onboarding status

Permissions

• GrantKBAccess - Grant permissions
• List - List permissions
• Update - Update permissions
• DeleteFromKB - Remove permissions

PlatformSettings

• Update - Update platform settings
• Get - Get platform settings
• ListFeatureFlags - Get available feature flags
• SetCustomSystemPrompt - Update custom system prompt
• GetCustomSystemPrompt - Get custom system prompt

PublicUrls

• SetFrontend - Set frontend public URL
• Set - Set connector public URL
• GetConnector - Get connector public URL

PublicURLs

• GetFrontend - Get frontend public URL

Records

• GetAll - Get all records across knowledge bases
• GetByKB - Get records for a knowledge base
• GetChildren - Get KB children (alias for records)
• GetByID - Get record by ID
• Update - Update record
• Delete - Delete record
• StreamContent - Stream record content

Saml

• SignIn - Initiate SAML sign-in flow
• SignInCallback - SAML sign-in callback

SemanticSearch

• Execute - Perform semantic search
• GetHistory - Get search history
• DeleteAllHistory - Clear all search history
• GetByID - Get search by ID
• Delete - Delete search by ID
• Share - Share a search
• Unshare - Unshare a search
• Archive - Archive a search
• Unarchive - Unarchive a search

SmtpConfiguration

• CreateOrUpdate - Create or update SMTP configuration
• Get - Get SMTP configuration

StorageConfiguration

• Get - Get current storage configuration

Teams

• Create - Create a team
• List - List teams
• GetByID - Get team by ID
• Update - Update team
• Delete - Delete team
• ListUserTeams - Get current user's teams
• GetUsers - Get users in team
• AddUsers - Add users to team
• Remove - Remove user from team
• UpdateUserPermissions - Update team users permissions
• GetUserCreated - Get user created teams

ToolsetConfiguration

• GetConfig - Get toolset configuration
• Update - Update toolset configuration
• Delete - Delete toolset configuration

ToolsetConfigurations

• Save - Save toolset configuration ⚠️ Deprecated

ToolsetInstances

• ListConfigured - List configured toolsets
• CheckStatus - Check toolset status
• ListMine - List my toolsets with auth status
• List - List toolset instances
• Create - Create toolset instance
• Get - Get toolset instance
• Update - Update toolset instance
• Delete - Delete toolset instance
• Authenticate - Authenticate toolset instance
• DeleteCredentials - Remove toolset credentials
• Reauthenticate - Mark instance for reauthentication
• GetStatus - Get instance authentication status

ToolsetOAuth

• Authorize - Get OAuth authorization URL
• Callback - Handle OAuth callback
• GetAuthURL - Get OAuth authorization URL for instance

ToolsetRegistry

• List - List available toolsets
• GetSchema - Get toolset schema

Toolsets

• CreateInstance - Create toolset instance
• ReauthenticateByID - Reauthenticate toolset

Upload

• Files - Upload files to knowledge base
• ToFolder - Upload files to folder
• GetLimits - Get upload limits

UserAccount

• InitAuth - Initialize authentication session
• Authenticate - Authenticate user with credentials
• GenerateLoginOtp - Generate and send OTP for login
• RequestPasswordReset - Request password reset email
• ResetPasswordWithToken - Reset password with email token
• RefreshToken - Refresh access token
• Logout - Logout current session
• ResetPassword - Reset password

UserGroups

• Create - Create user group
• GetAll - Get all user groups
• GetByID - Get user group by ID
• Update - Update user group
• Delete - Delete user group
• AddUsers - Add users to group
• RemoveUsers - Remove users from group
• GetUserGroups - Get groups for a user
• GetInGroup - Get users in group
• GetStatistics - Get group statistics

Users

• GetAll - Get all users
• Create - Create a new user
• Get - Get user by ID
• Update - Update user
• Delete - Delete user
• GetEmail - Get user email by ID
• UpdateEmail - Update user email
• UploadDisplayPicture - Upload display picture
• GetDisplayPicture - Get display picture
• RemoveDisplayPicture - Remove display picture
• BulkInvite - Bulk invite users
• ResendInvite - Resend user invite
• ListGraph - List users (paginated with graph data)
• Unblock - Unblock a user in organization
• GetAllWithGroups - Get all users with groups
• GetByIds - Get users by IDs
• UpdateFullName - Update user full name
• UpdateFirstName - Update user first name
• UpdateLastName - Update user last name
• UpdateDesignation - Update user designation
• CheckAdmin - Check if user is admin
• ListTeams - Get user teams

Server-sent event streaming

Server-sent events are used to stream content from certain operations. These operations will expose the stream as an iterable that can be consumed using a simple for loop. The loop will terminate when the server no longer has any events to send and closes the underlying connection.

package main

import (
	"context"
	pipeshub "github.com/pipeshub-ai/pipeshub-sdk-go"
	"github.com/pipeshub-ai/pipeshub-sdk-go/models/components"
	"log"
	"os"
)

func main() {
	ctx := context.Background()

	s := pipeshub.New(
		pipeshub.WithSecurity(components.Security{
			BearerAuth: pipeshub.Pointer(os.Getenv("PIPESHUB_BEARER_AUTH")),
		}),
	)

	res, err := s.Conversations.Stream(ctx, components.CreateConversationRequest{
		Query: "What are the key findings from our Q4 financial report?",
		RecordIds: []string{
			"507f1f77bcf86cd799439011",
			"507f1f77bcf86cd799439012",
		},
		ModelKey:  pipeshub.Pointer("gpt-4-turbo"),
		ModelName: pipeshub.Pointer("GPT-4 Turbo"),
		ChatMode:  pipeshub.Pointer("balanced"),
	})
	if err != nil {
		log.Fatal(err)
	}
	if res.SSEEvent != nil {
		defer res.SSEEvent.Close()

		for res.SSEEvent.Next() {
			event := res.SSEEvent.Value()
			log.Print(event)
			// Handle the event
		}
	}
}

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a retry.Config object to the call by using the WithRetries option:

package main

import (
	"context"
	pipeshub "github.com/pipeshub-ai/pipeshub-sdk-go"
	"github.com/pipeshub-ai/pipeshub-sdk-go/models/components"
	"github.com/pipeshub-ai/pipeshub-sdk-go/retry"
	"log"
	"models/operations"
)

func main() {
	ctx := context.Background()

	s := pipeshub.New()

	res, err := s.UserAccount.InitAuth(ctx, components.InitAuthRequest{
		Email: "user@example.com",
	}, operations.WithRetries(
		retry.Config{
			Strategy: "backoff",
			Backoff: &retry.BackoffStrategy{
				InitialInterval: 1,
				MaxInterval:     50,
				Exponent:        1.1,
				MaxElapsedTime:  100,
			},
			RetryConnectionErrors: false,
		}))
	if err != nil {
		log.Fatal(err)
	}
	if res.InitAuthResponse != nil {
		// handle response
	}
}

If you'd like to override the default retry strategy for all operations that support retries, you can use the WithRetryConfig option at SDK initialization:

package main

import (
	"context"
	pipeshub "github.com/pipeshub-ai/pipeshub-sdk-go"
	"github.com/pipeshub-ai/pipeshub-sdk-go/models/components"
	"github.com/pipeshub-ai/pipeshub-sdk-go/retry"
	"log"
)

func main() {
	ctx := context.Background()

	s := pipeshub.New(
		pipeshub.WithRetryConfig(
			retry.Config{
				Strategy: "backoff",
				Backoff: &retry.BackoffStrategy{
					InitialInterval: 1,
					MaxInterval:     50,
					Exponent:        1.1,
					MaxElapsedTime:  100,
				},
				RetryConnectionErrors: false,
			}),
	)

	res, err := s.UserAccount.InitAuth(ctx, components.InitAuthRequest{
		Email: "user@example.com",
	})
	if err != nil {
		log.Fatal(err)
	}
	if res.InitAuthResponse != nil {
		// handle response
	}
}

Error Handling

Handling errors in this SDK should largely match your expectations. All operations return a response object or an error, they will never return both.

By Default, an API error will return apierrors.APIError. When custom error responses are specified for an operation, the SDK may also return their associated error. You can refer to respective Errors tables in SDK docs for more details on possible error types for each operation.

For example, the InitAuth function may return the following errors:

Error Type	Status Code	Content Type
apierrors.AuthError	400, 403, 404	application/json
apierrors.APIError	4XX, 5XX	*/*

Example

package main

import (
	"context"
	"errors"
	pipeshub "github.com/pipeshub-ai/pipeshub-sdk-go"
	"github.com/pipeshub-ai/pipeshub-sdk-go/models/apierrors"
	"github.com/pipeshub-ai/pipeshub-sdk-go/models/components"
	"log"
)

func main() {
	ctx := context.Background()

	s := pipeshub.New()

	res, err := s.UserAccount.InitAuth(ctx, components.InitAuthRequest{
		Email: "user@example.com",
	})
	if err != nil {

		var e *apierrors.AuthError
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}

		var e *apierrors.APIError
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}
	}
}

Server Selection

Select Server by Index

You can override the default server globally using the WithServerIndex(serverIndex int) option when initializing the SDK client instance. The selected server will then be used as the default on the operations that use it. This table lists the indexes associated with the available servers:

#	Server	Variables	Description
0	https://{instance_url}/api/v1	instance_url	Base API URL
1	https://{instance_url}	instance_url	Root URL (used for MCP endpoints mounted at /mcp)

If the selected server has variables, you may override its default values using the associated option(s):

Variable	Option	Default	Description
instance_url	WithInstanceURL(instanceURL string)	"https://app.pipeshub.com"	Base server URL

Example

package main

import (
	"context"
	pipeshub "github.com/pipeshub-ai/pipeshub-sdk-go"
	"github.com/pipeshub-ai/pipeshub-sdk-go/models/components"
	"log"
)

func main() {
	ctx := context.Background()

	s := pipeshub.New(
		pipeshub.WithServerIndex(0),
		pipeshub.WithInstanceURL("https://app.pipeshub.com"),
	)

	res, err := s.UserAccount.InitAuth(ctx, components.InitAuthRequest{
		Email: "user@example.com",
	})
	if err != nil {
		log.Fatal(err)
	}
	if res.InitAuthResponse != nil {
		// handle response
	}
}

Override Server URL Per-Client

The default server can also be overridden globally using the WithServerURL(serverURL string) option when initializing the SDK client instance. For example:

package main

import (
	"context"
	pipeshub "github.com/pipeshub-ai/pipeshub-sdk-go"
	"github.com/pipeshub-ai/pipeshub-sdk-go/models/components"
	"log"
)

func main() {
	ctx := context.Background()

	s := pipeshub.New(
		pipeshub.WithServerURL("https://https://app.pipeshub.com"),
	)

	res, err := s.UserAccount.InitAuth(ctx, components.InitAuthRequest{
		Email: "user@example.com",
	})
	if err != nil {
		log.Fatal(err)
	}
	if res.InitAuthResponse != nil {
		// handle response
	}
}

Override Server URL Per-Operation

The server URL can also be overridden on a per-operation basis, provided a server list was specified for the operation. For example:

package main

import (
	"context"
	pipeshub "github.com/pipeshub-ai/pipeshub-sdk-go"
	"github.com/pipeshub-ai/pipeshub-sdk-go/models/operations"
	"log"
)

func main() {
	ctx := context.Background()

	s := pipeshub.New()

	res, err := s.OpenIDConnect.OauthAuthorizationServerMetadata(ctx, operations.WithServerURL(""))
	if err != nil {
		log.Fatal(err)
	}
	if res.OpenIDConfiguration != nil {
		// handle response
	}
}

Custom HTTP Client

The Go SDK makes API calls that wrap an internal HTTP client. The requirements for the HTTP client are very simple. It must match this interface:

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

The built-in net/http client satisfies this interface and a default client based on the built-in is provided by default. To replace this default with a client of your own, you can implement this interface yourself or provide your own client configured as desired. Here's a simple example, which adds a client with a 30 second timeout.

import (
	"net/http"
	"time"

	"github.com/pipeshub-ai/pipeshub-sdk-go"
)

var (
	httpClient = &http.Client{Timeout: 30 * time.Second}
	sdkClient  = pipeshub.New(pipeshub.WithClient(httpClient))
)

This can be a convenient way to configure timeouts, cookies, proxies, custom headers, and other low-level configuration.