POST/api/v1/assistants/{id}/tools
Assistants
Assign Tool
Appends a user-owned tool to the assistant's selected_tools list using an idempotent $addToSet — assigning an already-assigned tool is a no-op. Both the assistant and the tool must belong to the authenticated user. Returns the full updated AssistantDTO.
Request
Endpoint
POST
/api/v1/assistants/{id}/toolsAuthentication
x-api-keyorAuthorization: BearerPath Parameters
| Name | Type | Description |
|---|---|---|
idrequired | ObjectId | MongoDB ObjectId for the assistant. Invalid ids return 400. |
Body Parameters
| Name | Type | Description |
|---|---|---|
tool_idrequired | ObjectId | ObjectId of the user tool to assign. Must be owned by the authenticated user. |
Request Body Example
body.json
{
"tool_id": "66aa2b3c4d5e6f7a8b9c0d11"
}Notes
Use GET /api/v1/tools to retrieve your tool ids.
Assigning a tool that is already assigned is a no-op — the response is the same as a new assignment.
Content-Type: application/json is required on the request.
Response Example
response.json
{
"success": true,
"data": {
"id": "665f1a2b3c4d5e6f7a8b9c0d",
"name": "Sales Bot",
"system_prompt": "You are a concise sales assistant.",
"welcome_message": "Hi! How can I help?",
"ai_provider": "openai",
"model": "gpt-4.1-mini",
"max_tokens": 256,
"temperature": 0.3,
"voice": {
"provider": "azure",
"name": "hi-IN-AartiNeural",
"speed": 1,
"language": "hi-IN",
"stability": 0.75,
"similarity_boost": 0.8,
"tts_model": null,
"instructions": "Indian Accent"
},
"transcription": {
"provider": "azure",
"language": "hi-IN",
"mode": "single",
"prompt": null,
"deepgram": {
"model": "nova-2",
"utterance_end_ms": 1200,
"endpointing": 300,
"vad_events": true,
"diarize": true
},
"cartesia": {
"model": "ink-whisper",
"min_volume": 0.3,
"max_silence_duration_secs": 2
},
"gladia": {
"model": "fast",
"languages": [],
"main_language": "en"
},
"smallest_ai": {
"diarize": false,
"redact_pii": false,
"emotion": false,
"word_timestamps": false
}
},
"maintain_context": false,
"maximum_duration": 600,
"silence_timeout": 12,
"inactivity_message": "Are you still there?",
"timeout_end_message": "Thank you for calling. Goodbye!",
"filler_words_enabled": true,
"filler_words": "",
"dynamic_welcome_enabled": false,
"dynamic_welcome_message": "Hello {{name}}",
"selected_tools": [
"66aa2b3c4d5e6f7a8b9c0d11"
],
"created_at": "2026-05-01T10:00:00.000Z",
"updated_at": "2026-05-02T08:30:00.000Z"
}
}Status Codes
| HTTP | Meaning | Description |
|---|---|---|
| 200 | OK | Request succeeded. |
| 400 | Bad request | Malformed input, invalid ObjectId, or no updatable fields. |
| 401 | Unauthorized | Missing, invalid, inactive, or origin-restricted API key. |
| 404 | Not found | Resource was not found inside the authenticated user's scope. |
| 415 | Unsupported media type | Content-Type header is missing or is not application/json. |
| 422 | Validation error | JSON body failed schema or business validation. |
| 429 | Rate limited | Per-IP or per-key request budget was exceeded. |
Security Model
User-scoped by default
This endpoint only sees resources owned by the user attached to the API key. If another user's id is supplied, the API responds as if the resource does not exist.