> ## Documentation Index > Fetch the complete documentation index at: https://doc.rapida.ai/llms.txt > Use this file to discover all available pages before exploring further. # create-assistant > Creates an assistant with one provider configuration and optional tools, knowledge, and tags. ## OpenAPI ````yaml /openapi/talk-api.yaml post /v1/assistant/create-assistant openapi: 3.0.3 info: title: Rapida Assistant API version: 0.1.0 description: >- REST endpoints for creating assistants, managing assistant deployments, and starting outbound assistant phone calls. servers: - url: https://assistant-01.in.rapida.ai description: Rapida managed assistant API - url: https://assistant-01.us.rapida.ai description: Local assistant API security: - ProjectApiKeyHeader: [] - ProjectApiKeyQuery: [] - AuthenticationHeader: [] tags: - name: assistants x-group: Assistants description: Assistant management APIs. - name: assistant-deployments x-group: Assistant deployments description: Assistant deployment management APIs. - name: calls x-group: Calls description: Outbound call APIs. paths: /v1/assistant/create-assistant: post: tags: - assistants summary: create-assistant description: >- Creates an assistant with one provider configuration and optional tools, knowledge, and tags. operationId: createAssistant parameters: - $ref: '#/components/parameters/ClientSourceHeader' - $ref: '#/components/parameters/AuthIdHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAssistantRequest' examples: model: summary: Create a model-backed assistant value: name: Support assistant description: Answers customer support questions. visibility: private language: en tags: - support - production assistantProvider: model: modelProviderName: openai template: prompt: - role: system content: You are a helpful support assistant. promptVariables: - name: customerName type: string defaultValue: there assistantModelOptions: - key: model value: gpt-4o-mini assistantTools: - name: handoff description: Escalate the conversation to a human. executionMethod: end-of-conversation assistantKnowledges: - knowledgeId: '2230142097179373568' topK: 5 scoreThreshold: 0.5 retrievalMethod: semantic agentkit: summary: Create an AgentKit assistant value: name: AgentKit support assistant description: Routes live conversations to a custom AgentKit backend. visibility: private language: en assistantProvider: description: AgentKit production backend agentkit: agentKitUrl: agent.your-domain.com:50051 metadata: authorization: shared-token tenant: acme transportSecurity: TLS tlsVerification: VERIFY tlsServerName: agent.your-domain.com connectTimeoutMs: 10000 keepaliveTimeMs: 30000 keepaliveTimeoutMs: 10000 maxRecvMessageBytes: 16777216 maxSendMessageBytes: 16777216 responses: '200': description: Assistant created. content: application/json: schema: $ref: '#/components/schemas/GetAssistantResponse' examples: created: summary: Assistant created value: code: 200 success: true data: id: '2230142097179373568' name: Support assistant status: active visibility: private assistantProvider: model assistantProviderModel: modelProviderName: openai status: active '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingName: summary: Missing name value: code: 400 success: false error: errorCode: '1001004' errorMessage: missing name parameter humanMessage: Please provide the required name parameter. invalidProvider: summary: Invalid assistant provider value: code: 400 success: false error: errorCode: '1001006' errorMessage: invalid assistant_provider parameter humanMessage: Please provide exactly one assistant provider. '403': description: Unauthenticated request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthenticated: summary: Missing or invalid API key value: code: 403 success: false error: errorCode: '1001002' errorMessage: unauthenticated request humanMessage: >- Unauthenticated request, please try again with valid authentication. '500': description: Failed to create assistant. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: createFailed: summary: Assistant creation failed value: code: 500 success: false error: errorCode: '1001011' errorMessage: unable to create assistant humanMessage: Unable to create assistant, please try again later. components: parameters: ClientSourceHeader: name: x-client-source in: header required: false schema: type: string default: sdk enum: - sdk description: Client source identifier. SDK clients send this automatically. AuthIdHeader: name: x-auth-id in: header required: false schema: type: string description: Optional user identifier to propagate with the request. schemas: CreateAssistantRequest: type: object required: - assistantProvider - name properties: assistantProvider: $ref: '#/components/schemas/CreateAssistantProviderRequest' assistantKnowledges: type: array items: $ref: '#/components/schemas/CreateAssistantKnowledgeRequest' assistantTools: type: array items: $ref: '#/components/schemas/CreateAssistantToolRequest' description: type: string description: Assistant description. example: Answers customer support questions. visibility: type: string description: Assistant visibility. example: private language: type: string description: Assistant language code. example: en source: type: string description: Optional source system for imported assistants. sourceIdentifier: $ref: '#/components/schemas/Uint64String' description: Optional source-system identifier. tags: type: array items: type: string example: - support - production name: type: string description: Assistant name. example: Support assistant GetAssistantResponse: type: object properties: code: type: integer format: int32 example: 200 success: type: boolean example: true data: $ref: '#/components/schemas/Assistant' error: $ref: '#/components/schemas/Error' ErrorResponse: type: object properties: code: type: integer format: int32 example: 400 success: type: boolean example: false error: $ref: '#/components/schemas/Error' CreateAssistantProviderRequest: type: object description: >- Provider configuration for the assistant. Provide exactly one of `model`, `agentkit`, or `websocket`. properties: assistantId: $ref: '#/components/schemas/Uint64String' description: type: string model: $ref: '#/components/schemas/CreateAssistantProviderModel' agentkit: $ref: '#/components/schemas/CreateAssistantProviderAgentkit' websocket: $ref: '#/components/schemas/CreateAssistantProviderWebsocket' CreateAssistantKnowledgeRequest: type: object properties: knowledgeId: $ref: '#/components/schemas/Uint64String' assistantId: $ref: '#/components/schemas/Uint64String' rerankerModelProviderId: $ref: '#/components/schemas/Uint64String' rerankerModelProviderName: type: string assistantKnowledgeRerankerOptions: type: array items: $ref: '#/components/schemas/Metadata' topK: type: integer format: uint32 example: 5 scoreThreshold: type: number format: float example: 0.5 retrievalMethod: type: string example: semantic rerankerEnable: type: boolean CreateAssistantToolRequest: type: object properties: assistantId: $ref: '#/components/schemas/Uint64String' name: type: string example: handoff description: type: string fields: type: object additionalProperties: true executionMethod: type: string executionOptions: type: array items: $ref: '#/components/schemas/Metadata' Uint64String: type: string pattern: ^[0-9]+$ example: '2227823180112723968' Assistant: type: object properties: id: $ref: '#/components/schemas/Uint64String' status: type: string visibility: type: string source: type: string sourceIdentifier: $ref: '#/components/schemas/Uint64String' projectId: $ref: '#/components/schemas/Uint64String' organizationId: $ref: '#/components/schemas/Uint64String' assistantProvider: type: string assistantProviderId: $ref: '#/components/schemas/Uint64String' name: type: string description: type: string assistantProviderModel: $ref: '#/components/schemas/AssistantProviderModel' assistantProviderAgentkit: $ref: '#/components/schemas/AssistantProviderAgentkit' assistantProviderWebsocket: $ref: '#/components/schemas/AssistantProviderWebsocket' assistantTag: $ref: '#/components/schemas/AssistantTag' createdBy: $ref: '#/components/schemas/Uint64String' updatedBy: $ref: '#/components/schemas/Uint64String' createdDate: type: string format: date-time updatedDate: type: string format: date-time assistantTools: type: array items: $ref: '#/components/schemas/AssistantTool' assistantKnowledges: type: array items: $ref: '#/components/schemas/AssistantKnowledge' Error: type: object description: > Platform error response details. `errorCode` is a stable platform error code. See `PlatformErrorCode` for documented code/message mappings. properties: errorCode: $ref: '#/components/schemas/PlatformErrorCode' description: Stable platform error code. errorMessage: type: string description: Stable client-safe error message. example: missing toNumber parameter humanMessage: type: string description: Client-safe human-readable message. example: Please provide the required toNumber parameter. CreateAssistantProviderModel: type: object required: - modelProviderName properties: template: $ref: '#/components/schemas/TextChatCompletePrompt' modelProviderName: type: string description: Model provider name. example: openai assistantModelOptions: type: array items: $ref: '#/components/schemas/Metadata' CreateAssistantProviderAgentkit: type: object required: - agentKitUrl properties: agentKitUrl: type: string description: AgentKit gRPC endpoint in `host` or `host:port` format. example: agent.your-domain.com:50051 certificate: type: string description: Optional PEM CA certificate for private or self-signed TLS. metadata: type: object description: gRPC metadata sent to the AgentKit backend. additionalProperties: type: string transportSecurity: type: string description: AgentKit transport security mode. enum: - TLS - PLAINTEXT default: TLS tlsVerification: type: string description: AgentKit TLS verification mode. enum: - VERIFY - SKIP_VERIFY default: VERIFY tlsServerName: type: string description: TLS server name override for certificate verification. example: agent.your-domain.com connectTimeoutMs: type: integer format: uint32 minimum: 1 maximum: 300000 description: Connection timeout in milliseconds. default: 10000 keepaliveTimeMs: type: integer format: uint32 minimum: 10000 maximum: 3600000 description: Keepalive ping interval in milliseconds. default: 30000 keepaliveTimeoutMs: type: integer format: uint32 minimum: 1000 maximum: 300000 description: Keepalive response timeout in milliseconds. default: 10000 maxRecvMessageBytes: type: integer format: uint32 minimum: 1024 maximum: 104857600 description: Maximum inbound gRPC message size. default: 16777216 maxSendMessageBytes: type: integer format: uint32 minimum: 1024 maximum: 104857600 description: Maximum outbound gRPC message size. default: 16777216 CreateAssistantProviderWebsocket: type: object required: - websocketUrl properties: websocketUrl: type: string description: WebSocket provider URL. example: wss://agent.example.com/ws headers: type: object additionalProperties: type: string connectionParameters: type: object additionalProperties: type: string Metadata: type: object properties: id: $ref: '#/components/schemas/Uint64String' key: type: string value: type: string AssistantProviderModel: type: object properties: id: $ref: '#/components/schemas/Uint64String' template: $ref: '#/components/schemas/TextChatCompletePrompt' description: type: string assistantId: $ref: '#/components/schemas/Uint64String' modelProviderName: type: string assistantModelOptions: type: array items: $ref: '#/components/schemas/Metadata' status: type: string AssistantProviderAgentkit: type: object properties: id: $ref: '#/components/schemas/Uint64String' description: type: string assistantId: $ref: '#/components/schemas/Uint64String' status: type: string url: type: string certificate: type: string metadata: type: object additionalProperties: type: string transportSecurity: type: string tlsVerification: type: string tlsServerName: type: string connectTimeoutMs: type: integer format: uint32 keepaliveTimeMs: type: integer format: uint32 keepaliveTimeoutMs: type: integer format: uint32 maxRecvMessageBytes: type: integer format: uint32 maxSendMessageBytes: type: integer format: uint32 AssistantProviderWebsocket: type: object properties: id: $ref: '#/components/schemas/Uint64String' description: type: string assistantId: $ref: '#/components/schemas/Uint64String' url: type: string headers: type: object additionalProperties: type: string parameters: type: object additionalProperties: type: string status: type: string AssistantTag: type: object properties: id: $ref: '#/components/schemas/Uint64String' assistantId: $ref: '#/components/schemas/Uint64String' tag: type: array items: type: string AssistantTool: type: object properties: id: $ref: '#/components/schemas/Uint64String' assistantId: $ref: '#/components/schemas/Uint64String' name: type: string description: type: string fields: type: object additionalProperties: true executionMethod: type: string executionOptions: type: array items: $ref: '#/components/schemas/Metadata' status: type: string AssistantKnowledge: type: object properties: id: $ref: '#/components/schemas/Uint64String' knowledgeId: $ref: '#/components/schemas/Uint64String' rerankerEnable: type: boolean topK: type: integer format: uint32 scoreThreshold: type: number format: float retrievalMethod: type: string rerankerModelProviderId: $ref: '#/components/schemas/Uint64String' rerankerModelProviderName: type: string assistantKnowledgeRerankerOptions: type: array items: $ref: '#/components/schemas/Metadata' status: type: string PlatformErrorCode: type: string pattern: ^[0-9]+$ description: > Stable platform error code. Create Assistant: - `1001001`: invalid request - Invalid request. - `1001002`: unauthenticated request - Unauthenticated request, please try again with valid authentication. - `1001003`: missing authentication scope - Unauthenticated request, please try again with valid authentication. - `1001004`: missing name parameter - Please provide the required name parameter. - `1001005`: missing assistant_provider parameter - Please provide the required assistantProvider parameter. - `1001006`: invalid assistant_provider parameter - Please provide exactly one assistant provider. - `1001007`: missing model_provider_name parameter - Please provide the required modelProviderName parameter. - `1001008`: missing agent_kit_url parameter - Please provide the required agentKitUrl parameter. - `1001009`: missing websocket_url parameter - Please provide the required websocketUrl parameter. - `1001010`: invalid source_identifier parameter - Please provide a valid sourceIdentifier parameter. - `1001011`: unable to create assistant - Unable to create assistant, please try again later. - `1001012`: invalid assistant provider template - Invalid assistant provider template. - `1001013`: unable to create assistant provider model - Unable to create assistant provider model, please try again later. - `1001014`: unable to attach assistant provider model - Unable to attach assistant provider model, please try again later. - `1001015`: unable to create assistant provider agentkit - Unable to create assistant provider agentkit, please try again later. - `1001016`: unable to attach assistant provider agentkit - Unable to attach assistant provider agentkit, please try again later. - `1001017`: unable to create assistant provider websocket - Unable to create assistant provider websocket, please try again later. - `1001018`: unable to attach assistant provider websocket - Unable to attach assistant provider websocket, please try again later. - `1001019`: invalid knowledge_id parameter - Please provide a valid knowledgeId parameter. - `1001020`: invalid reranker_model_provider_id parameter - Please provide a valid rerankerModelProviderId parameter. - `1001021`: unable to create assistant tools - Unable to create assistant tools, please try again later. - `1001022`: unable to create assistant knowledge - Unable to create assistant knowledge, please try again later. - `1001023`: unable to create assistant tags - Unable to create assistant tags, please try again. Create Phone Call: - `1002001`: invalid request - Invalid request. - `1002002`: unauthenticated request - Unauthenticated request, please try again with valid authentication. - `1002003`: missing toNumber parameter - Please provide the required toNumber parameter. - `1002004`: invalid assistant parameter - Please provide a valid assistant. - `1002005`: invalid metadata parameter - Please provide valid metadata. - `1002006`: invalid arguments parameter - Please provide valid arguments. - `1002007`: invalid options parameter - Please provide valid options. - `1002008`: unable to initiate outbound call - Unable to initiate outbound call, please try again later. Create Bulk Phone Call: - `1003001`: invalid request - Invalid request. - `1003002`: unauthenticated request - Unauthenticated request, please try again with valid authentication. - `1003003`: missing phone_calls parameter - Please provide at least one phone call. - `1003004`: missing toNumber parameter - Please provide the required toNumber parameter. - `1003005`: invalid assistant parameter - Please provide a valid assistant. - `1003006`: invalid metadata parameter - Please provide valid metadata. - `1003007`: invalid arguments parameter - Please provide valid arguments. - `1003008`: invalid options parameter - Please provide valid options. - `1003009`: unable to initiate outbound call - Unable to initiate outbound call, please try again later. Create Assistant Debugger Deployment: - `1004001`: invalid request - Invalid request. - `1004002`: unauthenticated request - Unauthenticated request, please try again with valid authentication. - `1004003`: missing authentication scope - Unauthenticated request, please try again with valid authentication. - `1004004`: invalid assistant_id parameter - Please provide a valid assistantId parameter. - `1004005`: unable to create assistant debugger deployment - Unable to create assistant debugger deployment, please try again later. - `1004006`: invalid audio provider parameter - Please provide a valid audioProvider parameter. - `1004007`: invalid ideal_timeout parameter - Please provide idealTimeout between 15 and 120 seconds. - `1004008`: invalid ideal_timeout_backoff parameter - Please provide idealTimeoutBackoff between 0 and 5 times. - `1004009`: invalid max_session_duration parameter - Please provide maxSessionDuration between 180 and 600 seconds. Create Assistant Phone Deployment: - `1005001`: invalid request - Invalid request. - `1005002`: unauthenticated request - Unauthenticated request, please try again with valid authentication. - `1005003`: missing authentication scope - Unauthenticated request, please try again with valid authentication. - `1005004`: invalid assistant_id parameter - Please provide a valid assistantId parameter. - `1005005`: unable to create assistant phone deployment - Unable to create assistant phone deployment, please try again later. - `1005006`: invalid audio provider parameter - Please provide a valid audioProvider parameter. - `1005007`: invalid ideal_timeout parameter - Please provide idealTimeout between 15 and 120 seconds. - `1005008`: invalid ideal_timeout_backoff parameter - Please provide idealTimeoutBackoff between 0 and 5 times. - `1005009`: invalid max_session_duration parameter - Please provide maxSessionDuration between 180 and 600 seconds. - `1005010`: missing phone_provider_name parameter - Please provide the required phoneProviderName parameter. Create Assistant API Deployment: - `1006001`: invalid request - Invalid request. - `1006002`: unauthenticated request - Unauthenticated request, please try again with valid authentication. - `1006003`: missing authentication scope - Unauthenticated request, please try again with valid authentication. - `1006004`: invalid assistant_id parameter - Please provide a valid assistantId parameter. - `1006005`: unable to create assistant api deployment - Unable to create assistant api deployment, please try again later. - `1006006`: invalid audio provider parameter - Please provide a valid audioProvider parameter. - `1006007`: invalid ideal_timeout parameter - Please provide idealTimeout between 15 and 120 seconds. - `1006008`: invalid ideal_timeout_backoff parameter - Please provide idealTimeoutBackoff between 0 and 5 times. - `1006009`: invalid max_session_duration parameter - Please provide maxSessionDuration between 180 and 600 seconds. Create Assistant Webplugin Deployment: - `1007001`: invalid request - Invalid request. - `1007002`: unauthenticated request - Unauthenticated request, please try again with valid authentication. - `1007003`: missing authentication scope - Unauthenticated request, please try again with valid authentication. - `1007004`: invalid assistant_id parameter - Please provide a valid assistantId parameter. - `1007005`: unable to create assistant web plugin deployment - Unable to create assistant web plugin deployment, please try again later. - `1007006`: invalid audio provider parameter - Please provide a valid audioProvider parameter. - `1007007`: invalid ideal_timeout parameter - Please provide idealTimeout between 15 and 120 seconds. - `1007008`: invalid ideal_timeout_backoff parameter - Please provide idealTimeoutBackoff between 0 and 5 times. - `1007009`: invalid max_session_duration parameter - Please provide maxSessionDuration between 180 and 600 seconds. Create Assistant WhatsApp Deployment: - `1008001`: invalid request - Invalid request. - `1008002`: unauthenticated request - Unauthenticated request, please try again with valid authentication. - `1008003`: missing authentication scope - Unauthenticated request, please try again with valid authentication. - `1008004`: invalid assistant_id parameter - Please provide a valid assistantId parameter. - `1008005`: unable to create assistant whatsapp deployment - Unable to create assistant whatsapp deployment, please try again later. - `1008006`: invalid ideal_timeout parameter - Please provide idealTimeout between 15 and 120 seconds. - `1008007`: invalid ideal_timeout_backoff parameter - Please provide idealTimeoutBackoff between 0 and 5 times. - `1008008`: invalid max_session_duration parameter - Please provide maxSessionDuration between 180 and 600 seconds. - `1008009`: missing whatsapp_provider_name parameter - Please provide the required whatsappProviderName parameter. Get Assistant Debugger Deployment: - `1009001`: unauthenticated request - Unauthenticated request, please try again with valid authentication. - `1009002`: missing authentication scope - Unauthenticated request, please try again with valid authentication. - `1009003`: invalid assistant_id parameter - Please provide a valid assistantId parameter. - `1009004`: unable to get assistant debugger deployment - Unable to get assistant debugger deployment, please try again later. Get Assistant Phone Deployment: - `1010001`: unauthenticated request - Unauthenticated request, please try again with valid authentication. - `1010002`: missing authentication scope - Unauthenticated request, please try again with valid authentication. - `1010003`: invalid assistant_id parameter - Please provide a valid assistantId parameter. - `1010004`: unable to get assistant phone deployment - Unable to get assistant phone deployment, please try again later. Get Assistant API Deployment: - `1011001`: unauthenticated request - Unauthenticated request, please try again with valid authentication. - `1011002`: missing authentication scope - Unauthenticated request, please try again with valid authentication. - `1011003`: invalid assistant_id parameter - Please provide a valid assistantId parameter. - `1011004`: unable to get assistant api deployment - Unable to get assistant api deployment, please try again later. Get Assistant Webplugin Deployment: - `1012001`: unauthenticated request - Unauthenticated request, please try again with valid authentication. - `1012002`: missing authentication scope - Unauthenticated request, please try again with valid authentication. - `1012003`: invalid assistant_id parameter - Please provide a valid assistantId parameter. - `1012004`: unable to get assistant webplugin deployment - Unable to get assistant webplugin deployment, please try again later. Get Assistant WhatsApp Deployment: - `1013001`: unauthenticated request - Unauthenticated request, please try again with valid authentication. - `1013002`: missing authentication scope - Unauthenticated request, please try again with valid authentication. - `1013003`: invalid assistant_id parameter - Please provide a valid assistantId parameter. - `1013004`: unable to get assistant whatsapp deployment - Unable to get assistant whatsapp deployment, please try again later. Get All Assistant Debugger Deployments: - `1014001`: unauthenticated request - Unauthenticated request, please try again with valid authentication. - `1014002`: missing authentication scope - Unauthenticated request, please try again with valid authentication. - `1014003`: invalid assistant_id parameter - Please provide a valid assistantId parameter. - `1014004`: invalid request - Invalid request. - `1014005`: unable to get assistant debugger deployments - Unable to get assistant debugger deployments, please try again later. Get All Assistant Phone Deployments: - `1015001`: unauthenticated request - Unauthenticated request, please try again with valid authentication. - `1015002`: missing authentication scope - Unauthenticated request, please try again with valid authentication. - `1015003`: invalid assistant_id parameter - Please provide a valid assistantId parameter. - `1015004`: invalid request - Invalid request. - `1015005`: unable to get assistant phone deployments - Unable to get assistant phone deployments, please try again later. Get All Assistant API Deployments: - `1016001`: unauthenticated request - Unauthenticated request, please try again with valid authentication. - `1016002`: missing authentication scope - Unauthenticated request, please try again with valid authentication. - `1016003`: invalid assistant_id parameter - Please provide a valid assistantId parameter. - `1016004`: invalid request - Invalid request. - `1016005`: unable to get assistant api deployments - Unable to get assistant api deployments, please try again later. Get All Assistant Webplugin Deployments: - `1017001`: unauthenticated request - Unauthenticated request, please try again with valid authentication. - `1017002`: missing authentication scope - Unauthenticated request, please try again with valid authentication. - `1017003`: invalid assistant_id parameter - Please provide a valid assistantId parameter. - `1017004`: invalid request - Invalid request. - `1017005`: unable to get assistant webplugin deployments - Unable to get assistant webplugin deployments, please try again later. Get All Assistant WhatsApp Deployments: - `1018001`: unauthenticated request - Unauthenticated request, please try again with valid authentication. - `1018002`: missing authentication scope - Unauthenticated request, please try again with valid authentication. - `1018003`: invalid assistant_id parameter - Please provide a valid assistantId parameter. - `1018004`: invalid request - Invalid request. - `1018005`: unable to get assistant whatsapp deployments - Unable to get assistant whatsapp deployments, please try again later. example: '1002003' TextChatCompletePrompt: type: object properties: prompt: type: array items: $ref: '#/components/schemas/TextPrompt' promptVariables: type: array items: $ref: '#/components/schemas/Variable' TextPrompt: type: object properties: role: type: string example: system content: type: string example: You are a helpful support assistant. Variable: type: object properties: id: $ref: '#/components/schemas/Uint64String' name: type: string type: type: string defaultValue: type: string securitySchemes: ProjectApiKeyHeader: type: apiKey in: header name: x-api-key description: API key from Rapida credentials. ProjectApiKeyQuery: type: apiKey in: query name: x-api-key description: API key from Rapida credentials. AuthenticationHeader: type: apiKey in: header name: Authentication description: API key from Rapida credentials. ````