0
# Beta APIs
1

2
Experimental and preview APIs that provide access to cutting-edge features and capabilities. These APIs are in beta and may evolve as they mature. They provide advanced functionality for conversations, document libraries, and enhanced agent capabilities.
3

4
## Capabilities
5

6
### Conversations API
7

8
Manage conversational AI interactions with built-in function execution, streaming responses, and context management.
9

10
```python { .api }
11
def start(
12
    inputs: Union[ConversationInputs, dict],
13
    instructions: Optional[str] = None,
14
    tools: Optional[List[Tool]] = None,
15
    **kwargs
16
) -> ConversationResponse:
17
    """
18
    Start a new conversation.
19

20
    Parameters:
21
    - inputs: Initial conversation inputs and context
22
    - instructions: Optional system instructions
23
    - tools: Available tools for the conversation
24

25
    Returns:
26
    ConversationResponse with conversation ID and initial outputs
27
    """
28

29
async def start_async(
30
    inputs: Union[ConversationInputs, dict],
31
    **kwargs
32
) -> ConversationResponse:
33
    """
34
    Async version of start method.
35
    """
36

37
def list(
38
    limit: Optional[int] = None,
39
    after: Optional[str] = None,
40
    **kwargs
41
) -> List[AgentConversation]:
42
    """
43
    List conversations.
44

45
    Parameters:
46
    - limit: Maximum number of conversations to return
47
    - after: Cursor for pagination
48

49
    Returns:
50
    List of conversation objects
51
    """
52

53
def get(conversation_id: str, **kwargs) -> ConversationResponse:
54
    """
55
    Get conversation details.
56

57
    Parameters:
58
    - conversation_id: Unique conversation identifier
59

60
    Returns:
61
    ConversationResponse with full conversation state
62
    """
63

64
def append(
65
    conversation_id: str,
66
    inputs: Union[ConversationInputs, dict],
67
    **kwargs
68
) -> ConversationResponse:
69
    """
70
    Append to an existing conversation.
71

72
    Parameters:
73
    - conversation_id: Conversation to append to
74
    - inputs: New inputs to add to conversation
75

76
    Returns:
77
    Updated conversation response
78
    """
79

80
def restart(
81
    conversation_id: str,
82
    inputs: Union[ConversationInputs, dict],
83
    **kwargs
84
) -> ConversationResponse:
85
    """
86
    Restart a conversation with new inputs.
87

88
    Parameters:
89
    - conversation_id: Conversation to restart
90
    - inputs: New starting inputs
91

92
    Returns:
93
    Restarted conversation response
94
    """
95
```
96

97
### Streaming Conversations
98

99
Handle real-time conversational interactions with streaming responses.
100

101
```python { .api }
102
def start_stream(
103
    inputs: Union[ConversationInputs, dict],
104
    instructions: Optional[str] = None,
105
    tools: Optional[List[Tool]] = None,
106
    **kwargs
107
) -> Iterator[ConversationEvents]:
108
    """
109
    Start a streaming conversation.
110

111
    Parameters:
112
    - inputs: Initial conversation inputs
113
    - instructions: Optional system instructions
114
    - tools: Available tools
115

116
    Returns:
117
    Iterator of conversation events
118
    """
119

120
def append_stream(
121
    conversation_id: str,
122
    inputs: Union[ConversationInputs, dict],
123
    **kwargs
124
) -> Iterator[ConversationEvents]:
125
    """
126
    Stream append to existing conversation.
127

128
    Parameters:
129
    - conversation_id: Conversation to append to
130
    - inputs: New inputs to add
131

132
    Returns:
133
    Iterator of conversation update events
134
    """
135

136
def restart_stream(
137
    conversation_id: str,
138
    inputs: Union[ConversationInputs, dict],
139
    **kwargs
140
) -> Iterator[ConversationEvents]:
141
    """
142
    Stream restart conversation.
143

144
    Parameters:
145
    - conversation_id: Conversation to restart
146
    - inputs: New starting inputs
147

148
    Returns:
149
    Iterator of restart events
150
    """
151
```
152

153
### Libraries API
154

155
Create and manage document libraries to enhance agent capabilities with indexed document retrieval.
156

157
```python { .api }
158
def create(
159
    name: str,
160
    description: Optional[str] = None,
161
    metadata: Optional[dict] = None,
162
    **kwargs
163
) -> LibraryOut:
164
    """
165
    Create a new document library.
166

167
    Parameters:
168
    - name: Library name
169
    - description: Optional description
170
    - metadata: Optional metadata
171

172
    Returns:
173
    LibraryOut with library details
174
    """
175

176
def list(
177
    limit: Optional[int] = None,
178
    **kwargs
179
) -> ListLibraryOut:
180
    """
181
    List document libraries.
182

183
    Parameters:
184
    - limit: Maximum number of libraries to return
185

186
    Returns:
187
    ListLibraryOut with library list
188
    """
189

190
def get(library_id: str, **kwargs) -> LibraryOut:
191
    """
192
    Get library details.
193

194
    Parameters:
195
    - library_id: Unique library identifier
196

197
    Returns:
198
    LibraryOut with full library information
199
    """
200

201
def update(
202
    library_id: str,
203
    name: Optional[str] = None,
204
    description: Optional[str] = None,
205
    metadata: Optional[dict] = None,
206
    **kwargs
207
) -> LibraryOut:
208
    """
209
    Update library metadata.
210

211
    Parameters:
212
    - library_id: Library to update
213
    - name: Updated name
214
    - description: Updated description
215
    - metadata: Updated metadata
216

217
    Returns:
218
    Updated LibraryOut
219
    """
220

221
def delete(library_id: str, **kwargs) -> dict:
222
    """
223
    Delete a library.
224

225
    Parameters:
226
    - library_id: Library to delete
227

228
    Returns:
229
    Deletion confirmation
230
    """
231
```
232

233
### Document Management
234

235
Manage documents within libraries for enhanced agent knowledge.
236

237
```python { .api }
238
# Document operations are available through the libraries sub-API
239
def upload_document(
240
    library_id: str,
241
    file: Union[str, BinaryIO],
242
    metadata: Optional[dict] = None,
243
    **kwargs
244
) -> DocumentOut:
245
    """
246
    Upload document to library.
247

248
    Parameters:
249
    - library_id: Target library
250
    - file: Document file
251
    - metadata: Document metadata
252

253
    Returns:
254
    DocumentOut with document details
255
    """
256

257
def list_documents(
258
    library_id: str,
259
    limit: Optional[int] = None,
260
    **kwargs
261
) -> ListDocumentOut:
262
    """
263
    List documents in library.
264

265
    Parameters:
266
    - library_id: Library to list from
267
    - limit: Maximum documents to return
268

269
    Returns:
270
    ListDocumentOut with document list
271
    """
272
```
273

274
### Beta Agents API
275

276
Enhanced agent management with additional capabilities beyond the standard agents API.
277

278
```python { .api }
279
def create(
280
    name: str,
281
    model: str,
282
    description: Optional[str] = None,
283
    instructions: Optional[str] = None,
284
    **kwargs
285
) -> Agent:
286
    """
287
    Create a beta agent with enhanced capabilities.
288

289
    Parameters:
290
    - name: Agent name
291
    - model: Model to use
292
    - description: Agent description
293
    - instructions: System instructions
294

295
    Returns:
296
    Agent with beta features enabled
297
    """
298

299
def list(**kwargs) -> List[Agent]:
300
    """
301
    List beta agents.
302

303
    Returns:
304
    List of beta-enabled agents
305
    """
306

307
def get(agent_id: str, **kwargs) -> Agent:
308
    """
309
    Get beta agent details.
310

311
    Parameters:
312
    - agent_id: Agent identifier
313

314
    Returns:
315
    Agent with full beta configuration
316
    """
317

318
def update(
319
    agent_id: str,
320
    name: Optional[str] = None,
321
    description: Optional[str] = None,
322
    **kwargs
323
) -> Agent:
324
    """
325
    Update beta agent.
326

327
    Parameters:
328
    - agent_id: Agent to update
329
    - name: Updated name
330
    - description: Updated description
331

332
    Returns:
333
    Updated agent
334
    """
335

336
def update_version(
337
    agent_id: str,
338
    version_data: dict,
339
    **kwargs
340
) -> Agent:
341
    """
342
    Update agent version with beta features.
343

344
    Parameters:
345
    - agent_id: Agent to update
346
    - version_data: Version-specific configuration
347

348
    Returns:
349
    Agent with updated version
350
    """
351
```
352

353
## Usage Examples
354

355
### Starting a Conversation
356

357
```python
358
from mistralai import Mistral
359
from mistralai.models import ConversationInputs
360

361
client = Mistral(api_key="your-api-key")
362

363
# Start a conversation with beta API  
364
inputs = ConversationInputs(
365
    messages=[{"role": "user", "content": "Hello, I need help with data analysis."}]
366
)
367

368
conversation = client.beta.conversations.start(
369
    inputs=inputs,
370
    instructions="You are a data analysis expert. Help users analyze their data."
371
)
372

373
print(f"Started conversation: {conversation.id}")
374
```
375

376
### Creating a Document Library
377

378
```python
379
# Create a library for documentation
380
library = client.beta.libraries.create(
381
    name="Technical Documentation",
382
    description="Library of technical documentation and guides",
383
    metadata={"domain": "software", "language": "en"}
384
)
385

386
print(f"Created library: {library.id}")
387

388
# Upload documents to the library (conceptual - exact API may vary)
389
# document = client.beta.libraries.upload_document(
390
#     library_id=library.id,
391
#     file="technical_guide.pdf",
392
#     metadata={"type": "guide", "topic": "API"}
393
# )
394
```
395

396
### Streaming Conversation
397

398
```python
399
# Start streaming conversation
400
stream = client.beta.conversations.start_stream(
401
    inputs=inputs,
402
    instructions="Provide step-by-step analysis guidance."
403
)
404

405
for event in stream:
406
    if event.type == "message_output":
407
        print(f"Response: {event.content}")
408
    elif event.type == "function_call":
409
        print(f"Function called: {event.function_name}")
410
```
411

412
## Types
413

414
### Conversation Types
415

416
```python { .api }
417
class ConversationInputs:
418
    messages: List[dict]
419
    tools: Optional[List[Tool]]
420
    metadata: Optional[dict]
421

422
class ConversationResponse:
423
    id: str
424
    object: str
425
    created_at: int
426
    outputs: List[dict]
427
    usage: Optional[ConversationUsageInfo]
428

429
class ConversationEvents:
430
    type: str
431
    data: ConversationEventsData
432
    id: Optional[str]
433

434
class ConversationEventsData:
435
    content: Optional[str]
436
    function_name: Optional[str]
437
    arguments: Optional[dict]
438
```
439

440
### Library Types
441

442
```python { .api }
443
class LibraryOut:
444
    id: str
445
    object: str
446
    name: str
447
    description: Optional[str]
448
    created_at: int
449
    metadata: Optional[dict]
450

451
class ListLibraryOut:
452
    object: str
453
    data: List[LibraryOut]
454

455
class DocumentOut:
456
    id: str
457
    object: str
458
    filename: str
459
    library_id: str
460
    created_at: int
461
    metadata: Optional[dict]
462

463
class ListDocumentOut:
464
    object: str
465
    data: List[DocumentOut]
466
```
467

468
## Beta API Considerations
469

470
### Stability Warning
471

472
Beta APIs are experimental and may change without notice. They should be used with caution in production environments. Key considerations:
473

474
- **API Changes**: Method signatures and responses may evolve
475
- **Feature Availability**: Some features may be limited or require special access
476
- **Documentation**: May be less complete than stable APIs
477
- **Support**: Beta features may have different support policies
478

479
### Migration Path
480

481
When beta features graduate to stable APIs, migration guides will be provided to help transition existing implementations.
482

483
### Feedback
484

485
Beta APIs benefit from user feedback. Consider sharing your experience and use cases to help shape the final stable API design.