Assistants

An assistant represents an AI agent that can perform tasks, answer questions, and interact with users. Assistants can be customized with models, instructions, functions, MCP servers.

Endpoints

Manage your assistants with these REST endpoints.

List assistantsRetrieve a list of assistants

Create assistantCreate a new assistant

Get assistantRetrieve a specific assistant

Update assistantUpdate an existing assistant

Delete assistantDelete an existing assistant

`Assistant` type

Parameter	Type	Description
`id`	string	Unique identifier for the assistant
`storageProviderType`	`StorageProviderType`	Storage backend for threads and messages (see `StorageProviderType`)
`storageProviderAssistantId`	string or `null`	Identifier for the assistant in the storage provider
`modelProviderId`	string	Identifier for the AI provider
`model`	string	The AI model used by the assistant (e.g., "gpt-4.1")
`name`	string	Name of the assistant
`description`	string	Description of the assistant’s purpose
`instructions`	string	Instructions that guide the assistant’s behavior
`codeInterpreterEnabled`	boolean	Whether the code interpreter is enabled for the assistant
`fileSearchEnabled`	boolean	Whether file search is enabled for the assistant
`createdAt`	string	Timestamp when the assistant was created
`updatedAt`	string	Timestamp when the assistant was last updated

`StorageProviderType`

Possible values for StorageProviderType are:

OPENAI - Uses OpenAI Assistants API for storage

AZURE_OPENAI - Uses Azure OpenAI Assistants API for storage

AZURE_AGENTS - Uses Azure AI Agents for storage

OPENAI_RESPONSES - Uses OpenAI Chat Completions API (stores responses locally)

AZURE_OPENAI_RESPONSES - Uses Azure OpenAI Chat Completions API (stores responses locally)

SUPERINTERFACE_CLOUD - Stores all data in Superinterface Cloud

Storage provider type defines where the assistant's thread data and messages are stored.

Assistants API providers (OPENAI, AZURE_OPENAI, AZURE_AGENTS):

Superinterface stores only references to threads/agents

Thread messages are stored in the provider's Assistants API

Supports advanced features like file search and code interpreter

Responses providers (OPENAI_RESPONSES, AZURE_OPENAI_RESPONSES):

Thread messages are stored in the provider's Responses API

Similar to Assistants API but lighter weight

No assistant creation in external provider needed

Superinterface Cloud (SUPERINTERFACE_CLOUD):

All data stored in Superinterface Cloud

No external provider integration required

Example assistant

const assistant = { id: '00cfe680-fee5-49b9-b386-6a7097eb8497', storageProviderType: 'OPENAI', storageProviderAssistantId: 'asst_xwQudIsRPVWBOkanyBRWWBn2', modelProviderId: '01afd9c6-519f-4336-a39e-e739143f0a5c', model: 'gpt-4.1', name: 'AI builder', description: 'Builds applications', instructions: 'Help user build apps.', codeInterpreterEnabled: true, fileSearchEnabled: false, createdAt: '2024-01-15T10:30:00Z', updatedAt: '2024-01-15T10:30:00Z', }

`PublicAssistant` type

PublicAssistant is returned by endpoints that require a public API key. It only contains fields safe for client-side use.

Parameter	Type	Description
`id`	string	Unique identifier for the assistant
`name`	string	Assistant name
`description`	string	Public description
`theme`	object	Visual theme information
`avatar`	object	Assistant avatar

Example `PublicAssistant`

const publicAssistant = { id: '00cfe680-fee5-49b9-b386-6a7097eb8497', name: 'AI builder', description: 'Builds applications', theme: { accentColor: 'blue', grayColor: 'gray', appearance: 'light', radius: 'medium', scaling: '100%', panelBackground: 'solid', }, avatar: { type: 'ICON', imageAvatar: null, iconAvatar: { name: 'LIGHTNING_BOLT', }, }, }

Assistants

Endpoints

Assistant type

StorageProviderType

Example assistant

PublicAssistant type

Example PublicAssistant

`Assistant` type

`StorageProviderType`

`PublicAssistant` type

Example `PublicAssistant`