> ## Documentation Index > Fetch the complete documentation index at: https://wordsmithai.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create Assistant Question > Ask a question to the Wordsmith AI assistant with optional file attachments Creates a new assistant session by asking a question, or adds a question to an existing session. The assistant can analyze text, documents, and provide legal insights based on the question and any attached files. When adding questions to an existing session, the conversation context is preserved, allowing for follow-up questions and multi-turn conversations. ## Authentication This endpoint requires a valid API key in the Authorization header. ## Path Parameters The ID of the assistant to use. Use `"default"` for the general Wordsmith assistant, or specify a custom assistant ID if available. ## Request Body The question to ask the assistant. Maximum length: 10,000 characters. An array of file attachments (maximum 10 files). Each attachment can be either an uploaded file or a URL. The upload job ID returned from the file upload endpoint. Either this or `url` must be provided. A publicly accessible URL to download the file. Either this or `upload_job_id` must be provided. Whether to automatically extract ZIP archives and process individual files within them. The session ID to add this question to. If not provided, a new session will be created. When adding to an existing session, the conversation context is preserved for follow-up questions. Optional permissions settings for the chat session. The visibility level for the chat session. Controls who can access the session:
• `"private"`: Only you can access the session
• `"organization"`: Anyone in your organization can access the session
• `"public"`: Anyone with the link can access the session URL to receive a webhook notification when async processing is complete. Only used when `sync_mode` is `false`. Optionally signed with the webhook secret if provided when creating a new API key. Signature is in the `Wordsmith-Signature` header. Whether to wait for the complete response synchronously. `true`: Response includes the full answer (30-second timeout). `false`: Returns immediately with a session ID for async processing. ```bash cURL - Simple Question theme={null} curl -X POST "https://api.wordsmith.ai/api/v1/assistants/default/questions" \ -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "question": "What are the key elements of a valid contract under US law?", "sync_mode": true }' ``` ```bash cURL - With File Attachment theme={null} curl -X POST "https://api.wordsmith.ai/api/v1/assistants/default/questions" \ -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "question": "Please review this contract and identify any potential issues", "attachments": [ { "upload_job_id": "123e4567-e89b-12d3-a456-426614174000" } ], "sync_mode": false, "callback_url": "https://your-app.com/webhooks/wordsmith" }' ``` ```bash cURL - With URL Attachment theme={null} curl -X POST "https://api.wordsmith.ai/api/v1/assistants/default/questions" \ -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "question": "Analyze this public document", "attachments": [ { "url": "https://example.com/public-document.pdf" } ], "sync_mode": false }' ``` ```bash cURL - Add Question to Existing Session theme={null} curl -X POST "https://api.wordsmith.ai/api/v1/assistants/default/questions" \ -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "question": "Can you elaborate on the liability clause you mentioned?", "session_id": "550e8400-e29b-41d4-a716-446655440000", "sync_mode": false }' ``` ```bash cURL - With Session Permissions theme={null} curl -X POST "https://api.wordsmith.ai/api/v1/assistants/default/questions" \ -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "question": "Review this contract for potential issues", "attachments": [ { "upload_job_id": "123e4567-e89b-12d3-a456-426614174000" } ], "permissions": { "visibility": "organization" }, "sync_mode": false }' ``` ```javascript JavaScript theme={null} const response = await fetch( "https://api.wordsmith.ai/api/v1/assistants/default/questions", { method: "POST", headers: { Authorization: "Bearer sk-ws-api1-your_api_key_here", "Content-Type": "application/json", }, body: JSON.stringify({ question: "What are the implications of this clause?", attachments: [ { upload_job_id: "123e4567-e89b-12d3-a456-426614174000", }, ], permissions: { visibility: "organization", }, sync_mode: false, callback_url: "https://your-app.com/webhooks/wordsmith", }), } ); const result = await response.json(); ``` ```python Python theme={null} import requests headers = { "Authorization": "Bearer sk-ws-api1-your_api_key_here", "Content-Type": "application/json" } data = { "question": "Please summarize the key terms in this agreement", "attachments": [ { "upload_job_id": "upload_abc123def456" } ], "permissions": { "visibility": "organization" }, "sync_mode": False, "callback_url": "https://your-app.com/webhooks/wordsmith" } response = requests.post( "https://api.wordsmith.ai/api/v1/assistants/default/questions", headers=headers, json=data ) result = response.json() ``` ## Response The unique identifier for this specific question. The session ID that contains this question. This is always the same for all questions within a conversation session. A direct URL to view this session in the Wordsmith web application. This allows users to access the full conversation history and interact with the assistant through the web interface. The current status of the question: `"in_progress"`: Processing is ongoing. `"completed"`: Answer is ready. `"error"`: Processing failed. The assistant's response to your question. Only present when `status` is `"completed"`. Array of files generated by the assistant (e.g., summary documents, analysis reports). Only present when `status` is `"completed"`. The name of the generated file The MIME type of the file The size of the file in bytes A presigned URL to download the file (expires after 24 hours) ```json Sync Mode - Completed Response theme={null} { "id": "123e4567-e89b-12d3-a456-426614174000", "session_id": "123e4567-e89b-12d3-a456-426614174000", "session_url": "https://app.wordsmith.ai/chat/123e4567-e89b-12d3-a456-426614174000", "status": "completed", "answer": "A valid contract under US law typically requires four essential elements:\n\n1. **Offer**: A clear, definite proposal to enter into an agreement...", "attachments": [ { "file_name": "contract_analysis.pdf", "content_type": "application/pdf", "content_length": 245760, "url": "https://files.wordsmith.ai/signed-url-here" } ] } ``` ```json Async Mode - In Progress Response theme={null} { "id": "987fcdeb-51a2-43d1-9e8f-7b6c5a4d3e2f", "session_id": "987fcdeb-51a2-43d1-9e8f-7b6c5a4d3e2f", "session_url": "https://app.wordsmith.ai/chat/987fcdeb-51a2-43d1-9e8f-7b6c5a4d3e2f", "status": "in_progress", "answer": null, "attachments": null } ``` ```json Follow-up Question in Existing Session theme={null} { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "session_id": "550e8400-e29b-41d4-a716-446655440000", "session_url": "https://app.wordsmith.ai/chat/550e8400-e29b-41d4-a716-446655440000", "status": "in_progress", "answer": null, "attachments": null } ``` ```json Error Response theme={null} { "id": "abcdef12-3456-7890-abcd-ef1234567890", "session_id": "abcdef12-3456-7890-abcd-ef1234567890", "session_url": "https://app.wordsmith.ai/chat/abcdef12-3456-7890-abcd-ef1234567890", "status": "error", "answer": "Unable to process the attached file. Please ensure the file is not corrupted and try again.", "attachments": null } ``` ## Async Processing & Webhooks When using `sync_mode: false`, you can receive notifications via webhook when processing completes: ```json Webhook Payload - Completed theme={null} { "id": "987fcdeb-51a2-43d1-9e8f-7b6c5a4d3e2f", "session_id": "987fcdeb-51a2-43d1-9e8f-7b6c5a4d3e2f", "session_url": "https://app.wordsmith.ai/chat/987fcdeb-51a2-43d1-9e8f-7b6c5a4d3e2f", "status": "completed", "answer": "Based on my analysis of the contract...", "attachments": [ { "file_name": "contract_review.pdf", "content_type": "application/pdf", "content_length": 524288, "url": "https://files.wordsmith.ai/signed-url-here" } ] } ``` ```json Webhook Payload - Error theme={null} { "id": "987fcdeb-51a2-43d1-9e8f-7b6c5a4d3e2f", "session_id": "987fcdeb-51a2-43d1-9e8f-7b6c5a4d3e2f", "session_url": "https://app.wordsmith.ai/chat/987fcdeb-51a2-43d1-9e8f-7b6c5a4d3e2f", "status": "error", "answer": "The document format is not supported. Please convert to PDF and try again.", "attachments": null } ``` For detailed information about webhook setup, signature verification, and security best practices, see the [Webhooks documentation](/webhooks). ## Error Responses See the [Errors](/errors) page for the full error format reference and handling guidance. ```json 400 Bad Request - Invalid Body theme={null} { "error_code": "invalid_request_body", "ws_api_error_code": "invalid_request_body", "message": "Request body is invalid. Ensure it is valid JSON with a 'question' field." } ``` ```json 400 Bad Request - Invalid Upload Job theme={null} { "error_code": "invalid_upload_job", "ws_api_error_code": "invalid_upload_job", "message": "One or more upload_job_id values are invalid or have expired. Generate a new upload URL and re-upload the file." } ``` ```json 400 Bad Request - Session Processing theme={null} { "error_code": "session_still_processing", "ws_api_error_code": "session_still_processing", "message": "Cannot add a new question while a previous question in this session is still processing." } ``` ```json 401 Unauthorized theme={null} { "error_code": "unauthorized", "ws_api_error_code": "unauthorized", "message": "Invalid API key" } ``` ```json 404 Not Found theme={null} { "error_code": "resource_not_found", "ws_api_error_code": "resource_not_found", "message": "Question not found for this assistant." } ``` ```json 429 Too Many Requests theme={null} { "error_code": "rate_limit_exceeded", "ws_api_error_code": "rate_limit_exceeded", "message": "Rate limit exceeded. Please retry after a short delay." } ``` ## Session Management ### Adding Questions to Existing Sessions When adding questions to an existing session using the `session_id` parameter: * **Conversation Context**: The assistant maintains context from previous questions and answers in the session * **Sequential Processing**: New questions cannot be submitted until the previous question in the session has completed processing * **Error Handling**: If a previous question is still processing, the API will return a 400 Bad Request error ### ID vs Session ID The response includes two important identifiers: * **`id`**: The unique identifier for this specific question. For new sessions, this equals the session\_id. For follow-up questions, this is a unique question ID. * **`session_id`**: The session ID that contains this question. This remains constant for all questions within the same conversation. Use the `id` field to check the status of individual questions, and the `session_id` to identify which conversation session the question belongs to. ## Best Practices ### Sync vs Async Mode **Use Sync Mode (`sync_mode: true`) for:** * Testing and development **Use Async Mode (`sync_mode: false`) for:** * Complex document analysis * Multiple file attachments * Production applications * Long-form research questions ### File Attachments * **Supported formats**: PDF, DOC, DOCX, TXT, MD, HTML, XLS, XLSX, CSV, TSV, PPT, PPTX, PNG, JPEG, WebP, TIFF, MP3, MP4, M4A, MPEG, WAV, WebM, ZIP * **Maximum file size**: 50 MB per file * **Maximum attachments**: 10 files per question ### Question Guidelines * **Be specific**: More detailed questions get better answers * **Provide context**: Include relevant background information ## Use Cases ### 1. Document Review & Analysis * **Basic Review**: "Review attached document" * **Review with Specific Playbook**: "Review this document using the Standard NDA playbook" * **Reference Playbook by ID**: "Review this document using playbook ID: 123e4567-e89b-12d3-a456-426614174000" ### 2. Template Filling & Document Generation * **Fill Template**: "Fill in our standardemployment agreement template using me as the employer party" * **Reference Template by ID**: "Fill in template ID: 123e4567-e89b-12d3-a456-426614174000 using my company information" ### 3. Legal Research & Analysis * **Case Law Research**: "What are the recent precedents for breach of contract cases in California?" * **Regulatory Compliance**: "What are the current requirements for data protection in healthcare contracts?" * **Legal Framework**: "Explain the key elements of a valid employment contract under UK law" * **Industry Standards**: "What are the standard terms typically included in SaaS vendor agreements?" ### 4. Document Drafting & Creation * **Email Drafting**: "Draft a professional email to a client explaining contract delays" * **Clause Drafting**: "Draft a force majeure clause for a construction contract" * **Legal Letters**: "Write a demand letter for unpaid invoices" * **Meeting Minutes**: "Draft meeting minutes based on the attached audio recording" ### 5. Translation & Conversion * **Language Translation**: "Translate this contract to Spanish while maintaining legal accuracy" * **Multi-language**: "Provide this agreement in both English and French versions" * **Format Conversion**: "Convert this PDF document to DOCX" ### 6. Presentations & Spreadsheets * **Generate Presentation**: "Create a PowerPoint presentation summarizing the key findings from the review of attached NDA" * **Executive Summary**: "Generate an executive summary of this legal document for senior management" * **Questionnaire Processing**: "Fill in this security questionnaire in the attached XLSX" * **Spreadsheet Generation**: "Extract all dates, amounts, and party names from this document into a structured spreadsheet"