Class MosaiaClient

Main Mosaia SDK client class

Provides access to all Mosaia API endpoints through a unified interface. Supports authentication, user management, organization management, AI agents, tools, applications, and more.

The MosaiaClient is the primary entry point for all SDK operations. It manages configuration, authentication, and provides access to all API collections.

Example

import * as SDK from '@mosaia/mosaia-node-sdk';

const mosaia = new SDK.MosaiaClient({
  apiKey: 'your-api-key',
  apiURL: 'https://api.mosaia.ai',
  appURL: 'https://mosaia.ai',
  clientId: 'your-client-id'
});

// Get all users
const users = await mosaia.users.get();

// Create an OAuth instance
const oauth = mosaia.oauth({
  redirectUri: 'https://your-app.com/callback',
  scopes: ['read', 'write']
});

Example

// Using individual collection classes
const users = new SDK.Users();
const agents = new SDK.Agents();
const apps = new SDK.Apps();

// Perform operations
const allUsers = await users.get();
const agent = await agents.get({}, 'agent-id');

Index

Constructors

constructor

Methods

session oauth

Constructors

constructor

new MosaiaClient(config: MosaiaConfig): MosaiaClient
Creates a new Mosaia SDK instance

Initializes the SDK with the provided configuration and sets up the internal configuration manager. The configuration is used for all subsequent API requests.
Parameters
- config: MosaiaConfig
  Configuration object for the SDK
  
  Configuration interface for the Mosaia SDK
  
  This interface defines all configuration options available when initializing the Mosaia SDK client. It includes authentication settings, API endpoints, and optional context parameters.
  - OptionalapiKey?: string
    API key for authentication (optional if using OAuth)
  - Optionalversion?: string
    API version to use (defaults to '1')
  - OptionalapiURL?: string
    Base URL for API requests (defaults to https://api.mosaia.ai)
  - OptionalclientId?: string
    Client ID for client credentials flows (Optional)
  - OptionalclientSecret?: string
    Client secret for client credentials flow (optional)
  - Optionalverbose?: boolean
    Enable verbose HTTP request/response logging (defaults to false)
  - Optionalsession?: SessionCredentials
    Session credentials for OAuth and token-based authentication (optional)
Returns MosaiaClient
Example
```
const mosaia = new SDK.MosaiaClient({
  apiKey: 'your-api-key',
  apiURL: 'https://api.mosaia.ai',
  appURL: 'https://mosaia.ai',
  clientId: 'your-client-id'
});
```
Example
```
// Minimal configuration with API key
const mosaia = new SDK.MosaiaClient({
  apiKey: 'your-api-key'
});

// Full configuration with OAuth support
const mosaia = new SDK.MosaiaClient({
  apiKey: 'your-api-key',
  apiURL: 'https://api.mosaia.ai',
  version: '1',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  user: 'user-id',
  org: 'org-id'
});
```
- Defined in index.ts:143

Accessors

config

get config(): MosaiaConfig
Get the current configuration

Returns the current configuration object used by this client instance.

Returns MosaiaConfig
The current configuration object
Example
```
const config = mosaia.config;
console.log(config.apiKey); // 'your-api-key'
console.log(config.apiURL); // 'https://api.mosaia.ai'
```
- Defined in index.ts:162
set config(config: MosaiaConfig): void
Set the configuration

Updates the configuration for this client instance. This will affect all subsequent API requests made through this client.
Parameters
- config: MosaiaConfig
  The new configuration object
Returns void
Example
```
mosaia.config = {
  apiKey: 'new-api-key',
  apiURL: 'https://api-staging.mosaia.ai'
};
```
- Defined in index.ts:182

apiKey

set apiKey(apiKey: string): void
Set the API key for authentication

Updates the API key used for authenticating requests to the Mosaia API. This can be used to change authentication credentials at runtime.
Parameters
- apiKey: string
  The new API key for authentication
Returns void
Example
```
const mosaia = new SDK.MosaiaClient(config);

// Update API key
mosaia.apiKey = 'new-api-key-123';

// Now all subsequent requests will use the new API key
const users = await mosaia.users.get();
```
- Defined in index.ts:205

version

set version(version: string): void
Set the API version

Updates the API version used for requests. This affects the version header sent with API requests.
Parameters
- version: string
  The new API version (e.g., '1', '2')
Returns void
Example
```
const mosaia = new SDK.MosaiaClient(config);

// Update API version
mosaia.version = '2';

// Now all subsequent requests will use API v2
const users = await mosaia.users.get();
```
- Defined in index.ts:228

apiURL

set apiURL(apiURL: string): void

Set the API base URL

Updates the base URL used for API requests. This is useful for switching between different environments (development, staging, production).

Parameters

apiURL: string
The new API base URL

Returns void

Example

const mosaia = new SDK.MosaiaClient(config);

// Switch to staging environment
mosaia.apiURL = 'https://api-staging.mosaia.ai';

// Switch to production environment
mosaia.apiURL = 'https://api.mosaia.ai';

// Switch to local development
mosaia.apiURL = 'http://localhost:3000';

clientId

set clientId(clientId: string): void

Set the OAuth client ID

Updates the OAuth client ID used for authentication flows. This is required for OAuth-based authentication.

Parameters

clientId: string
The new OAuth client ID

Returns void

Example

const mosaia = new SDK.MosaiaClient(config);

// Update OAuth client ID
mosaia.clientId = 'new-client-id-123';

// Create OAuth instance with updated client ID
const oauth = mosaia.oauth({
  redirectUri: 'https://myapp.com/callback',
  scopes: ['read', 'write']
});

clientSecret

set clientSecret(clientSecret: string): void

Set the OAuth client secret

Updates the OAuth client secret used for client credentials flow. This is used for server-to-server authentication.

Parameters

clientSecret: string
The new OAuth client secret

Returns void

Example

const mosaia = new SDK.MosaiaClient(config);

// Update OAuth client secret
mosaia.clientSecret = 'new-client-secret-456';

// Use client credentials flow with updated secret
const auth = new Auth(mosaia.config);
const authResponse = await auth.signInWithClient(
  mosaia.config.clientId!,
  mosaia.config.clientSecret!
);

auth

get auth(): MosaiaAuth

Access to Authentication API

Handle authentication flows, including sign in, sign out, token refresh, and session management.

Returns MosaiaAuth

Authentication API client

Example

// Sign in with password
const auth = await mosaia.auth.signInWithPassword('user@example.com', 'password', 'client-id');

// Sign in with client credentials
const auth = await mosaia.auth.signInWithClient('client-id', 'client-secret');

// Refresh token
const newAuth = await mosaia.auth.refreshToken('refresh-token');

// Sign out
await mosaia.auth.signOut();

agents

get agents(): Agents

Access to Agents API

Manage AI agents, including CRUD operations, chat completions, and agent-specific functionality.

Returns Agents

Agents API client

Example

// Get all agents
const agents = await mosaia.agents.get();

// Get specific agent
const agent = await mosaia.agents.get({}, 'agent-id');

// Create chat completion
const completion = await mosaia.agents.chatCompletion('agent-id', {
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello' }]
});

apps

get apps(): Apps

Access to Applications API

Manage applications, including CRUD operations and app-specific functionality.

Returns Apps

Applications API client

Example

// Get all apps
const apps = await mosaia.apps.get();

// Get specific app
const app = await mosaia.apps.get({ id: 'app-id' });

// Create new app
const newApp = await mosaia.apps.create({
  name: 'My App',
  short_description: 'Description'
});

tools

get tools(): Tools

Access to Tools API

Manage tools and integrations, including CRUD operations and tool-specific functionality.

Returns Tools

Tools API client

Example

// Get all tools
const tools = await mosaia.tools.get();

// Get specific tool
const tool = await mosaia.tools.get({ id: 'tool-id' });

// Create new tool
const newTool = await mosaia.tools.create({
  name: 'My Tool',
  short_description: 'Description',
  tool_schema: '{}'
});

users

get users(): Users

Access to Users API

Manage users, including CRUD operations, authentication, and user-specific functionality.

Returns Users

Users API client

Example

 * // Get all users
const users = await mosaia.users.get();

// Get specific user
const user = await mosaia.users.get({}, 'user-id');

// Create new user
const newUser = await mosaia.users.create({
  email: 'user@example.com',
  first_name: 'John',
  last_name: 'Doe'
});

organizations

get organizations(): Organizations

Access to Organizations API

Manage organizations, including CRUD operations and organization-specific functionality.

Returns Organizations

Organizations API client

Example

// Get all organizations
const orgs = await mosaia.organizations.get();

// Get specific organization
const org = await mosaia.organizations.get({}, 'org-id');

// Create new organization
const newOrg = await mosaia.organizations.create({
  name: 'My Organization',
  short_description: 'Description'
});

models

get models(): Models

Access to Models API

Manage AI models, including CRUD operations and model-specific functionality.

Returns Models

Models API client

Example

// Get all models
const models = await mosaia.models.get();

// Get specific model
const model = await mosaia.models.get({}, 'model-id');

// Create new model
const newModel = await mosaia.models.create({
  name: 'My Model',
  provider: 'openai',
  model_id: 'gpt-4'
});

appConnectors

get appConnectors(): AppConnectors

Access to App Connectors API

Manage app connectors, which are specialized integrations that connect applications with AI agents or agent groups through webhook-style interactions.

Returns AppConnectors

App Connectors API client

Example

// Get all app connectors
const connectors = await mosaia.appConnectors.get();

// Get a specific app connector
const connector = await mosaia.appConnectors.get({}, 'connector-id');

// Create a new app connector
const newConnector = await mosaia.appConnectors.create({
  app: 'app-id',
  response_url: 'https://myapp.com/webhook',
  agent: 'agent-id'
});

appWebhooks

get appWebhooks(): AppWebhooks

Access to App Webhooks API

Manage app webhooks, which enable external systems to receive notifications about application events through webhook-style interactions.

Returns AppWebhooks

App Webhooks API client

Example

// Get all app webhooks
const webhooks = await mosaia.appWebhooks.get();

// Get a specific app webhook
const webhook = await mosaia.appWebhooks.get({}, 'webhook-id');

// Create a new app webhook
const newWebhook = await mosaia.appWebhooks.create({
  app: 'app-id',
  url: 'https://myapp.com/webhook',
  events: ['REQUEST'],
  secret: 'webhook-secret-key'
});

search

get search(): Search

Access to Search API

Perform universal search across multiple resource types (agents, apps, tools, models) with a single query.

Returns Search

Search API client

Example

// Search across all resource types
const results = await mosaia.search.query({
  q: 'customer support',
  limit: 10
});

// Access results by type
console.log('Agents:', results.data.agents);
console.log('Apps:', results.data.apps);
console.log('Tools:', results.data.tools);
console.log('Models:', results.data.models);

Example

// Search specific resource types
const results = await mosaia.search.query({
  q: 'AI assistant',
  search_types: ['agent', 'app'],
  limit: 5
});

drives

get drives(): Drives

Access to Drives API

Manage drives, which are containers for organizing and managing files and documents, scoped to users or organizations.

Returns Drives

Drives API client

Example

// Get all drives
const drives = await mosaia.drives.get();

// Get a specific drive
const drive = await mosaia.drives.get({}, 'drive-id');

// Create a new drive
const newDrive = await mosaia.drives.create({
  name: 'My Documents',
  description: 'Personal document storage'
});

// Access drive items
const items = await drive.items.get();

logs

get logs(): Logs

Access to Logs API

Manage agent logs, which track conversations and interactions with agents.

Returns Logs

Logs API client

Example

// Get all logs
const logs = await mosaia.logs.get();

// Get a specific log
const log = await mosaia.logs.get({}, 'log-id');

// Access log messages and snapshots
const messages = await log.messages.get();
const snapshots = await log.snapshots.get();

scopes

get scopes(): Scopes
Access to Scopes API

Get permission scopes available in the platform.

Returns Scopes
Scopes API client
Example
```
const result = await mosaia.scopes.get();
console.log('Available scopes:', result.data.scopes);
```
- Defined in index.ts:707

sso

get sso(): SSO

Access to SSO API

Authenticate using single sign-on with OAuth providers.

Returns SSO

SSO API client

Example

const result = await mosaia.sso.authenticate({
  mosaia_user: { id: 'user-id' },
  oauth_account: {
    type: 'oauth',
    provider: 'google'
  }
});

notifications

get notifications(): Notifications
Access to Notifications API

Send email notifications through the platform.

Returns Notifications
Notifications API client
Example
```
await mosaia.notifications.sendEmail({
  to: 'user@example.com',
  subject: 'Welcome!',
  text: 'Welcome to our platform!'
});
```
- Defined in index.ts:749

snapshots

get snapshots(): Snapshots
Access to Snapshots API

Manage snapshots, which are point-in-time captures of data.

Returns Snapshots
Snapshots API client
Example
```
const snapshots = await mosaia.snapshots.get();
```
- Defined in index.ts:765

vectorIndexes

get vectorIndexes(): VectorIndexes
Access to Vector Indexes API

Manage vector indexes for semantic search and similarity matching.

Returns VectorIndexes
Vector Indexes API client
Example
```
const indexes = await mosaia.vectorIndexes.get();
```
- Defined in index.ts:781

tasks

get tasks(): Tasks

Access to Tasks API

Manage tasks in the platform.

Returns Tasks

Tasks API client

Example

const tasks = await mosaia.tasks.get();

// Get a specific task
const task = await mosaia.tasks.get({}, 'task-id');

// Access task plans
const plans = await task.plans.get();

Methods

session

session(): Promise<Session>
Get the current user session

Retrieves information about the currently authenticated user, including user details, organization information, and permissions.

Returns Promise<Session>
Session object containing user and organization information
Throws
When authentication fails or session is invalid
Example
```
try {
  const session = await mosaia.session();
  console.log('User:', session.user?.email);
  console.log('Organization:', session.org?.name);
} catch (error) {
  console.error('Session error:', error.message);
}
```
- Defined in index.ts:387

oauth

oauth(oauthConfig: OAuthConfig): OAuth
Creates a new OAuth instance for handling OAuth2 Authorization Code flow with PKCE

This method creates an OAuth client that supports the PKCE (Proof Key for Code Exchange) flow for secure authentication, even for public clients.
Parameters
- oauthConfig: OAuthConfig
  OAuth configuration object
  
  OAuth configuration interface
  
  Configuration object for OAuth2 Authorization Code flow with PKCE. Used when initializing OAuth instances for secure authentication. This interface defines all the parameters needed to configure OAuth authentication flows.
  - OptionalredirectUri?: string
    Redirect URI for the OAuth flow (optional)
  - OptionalappURL?: string
    App URL for authorization endpoints (optional defaults to https://mosaia.ai)
  - Optionalscopes?: string[]
    Array of scopes to request (optional)
  - OptionalclientId?: string
    OAuth client ID (required only if not using default)
  - OptionalapiURL?: string
    API URL for API endpoints (required only if not using default)
  - OptionalapiVersion?: string
    API version (required only if not using default)
  - Optionalstate?: string
    State parameter for CSRF protection (optional)
Returns OAuth
OAuth instance for handling the authentication flow
Throws
When clientId is not provided in SDK configuration
Example
```
// Initialize OAuth
const oauth = mosaia.oauth({
  redirectUri: 'https://your-app.com/callback',
  scopes: ['read', 'write']
});

// Get authorization URL and code verifier
const { url, codeVerifier } = oauth.getAuthorizationUrlAndCodeVerifier();

// Redirect user to the authorization URL
// After user authorizes, you'll receive a code in your callback

// Exchange code for new authenticated config (requires the code verifier)
const newConfig = await oauth.authenticateWithCodeAndVerifier(code, codeVerifier);

// create new instance with authenticated config
const newMosaiaInstance = new SDK.MosaiaClient(newConfig);
```
- Defined in index.ts:840

Class MosaiaClient

Example

Example

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

OptionalapiKey?: string

Optionalversion?: string

OptionalapiURL?: string

OptionalclientId?: string

OptionalclientSecret?: string

Optionalverbose?: boolean

Optionalsession?: SessionCredentials

Returns MosaiaClient

Example

Example

Accessors

config

Returns MosaiaConfig

Example

Parameters

Returns void

Example

apiKey

Parameters

Returns void

Example

version

Parameters

Returns void

Example

apiURL

Parameters

Returns void

Example

clientId

Parameters

Returns void

Example

clientSecret

Parameters

Returns void

Example

auth

Returns MosaiaAuth

Example

agents

Returns Agents

Example

apps

Returns Apps

Example

tools

Returns Tools

Example

users

Returns Users

Example

organizations

Returns Organizations

Example

models

Returns Models

Example

appConnectors

Returns AppConnectors

Example

appWebhooks

Returns AppWebhooks

Example

search

Returns Search

Example

Example

drives

Returns Drives

`Optional`apiKey?: string

`Optional`version?: string

`Optional`apiURL?: string

`Optional`clientId?: string

`Optional`clientSecret?: string

`Optional`verbose?: boolean

`Optional`session?: SessionCredentials

`Optional`redirectUri?: string

`Optional`appURL?: string

`Optional`scopes?: string[]

`Optional`clientId?: string

`Optional`apiURL?: string

`Optional`apiVersion?: string

`Optional`state?: string