Create Assistant Question

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

assistant_id

string

default:"default"

required

The ID of the assistant to use. Use "default" for the general Wordsmith assistant, or specify a custom assistant ID if available.

Request Body

question

string

required

The question to ask the assistant. Maximum length: 10,000 characters.

attachments

array

An array of file attachments (maximum 10 files). Each attachment can be either an uploaded file or a URL.

Show Attachment Object

upload_job_id

string

The upload job ID returned from the file upload endpoint. Either this or url must be provided.

url

string

A publicly accessible URL to download the file. Either this or upload_job_id must be provided.

unzip

boolean

default:"false"

Whether to automatically extract ZIP archives and process individual files within them.

session_id

string

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.

permissions

object

Optional permissions settings for the chat session.

Show Permissions Object

visibility

string

required

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

callback_url

string

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.

sync_mode

boolean

default:"false"

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.

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
  }'

Response

string

The unique identifier for this specific question.

session_id

string

The session ID that contains this question. This is always the same for all questions within a conversation session.

session_url

string

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.

status

string

The current status of the question: "in_progress": Processing is ongoing. "completed": Answer is ready. "error": Processing failed.

answer

string

The assistant’s response to your question. Only present when status is "completed".

attachments

array

Array of files generated by the assistant (e.g., summary documents, analysis reports). Only present when status is "completed".

Show Attachment Object

file_name

string

The name of the generated file

content_type

string

The MIME type of the file

content_length

integer

The size of the file in bytes

url

string

A presigned URL to download the file (expires after 24 hours)

{
  "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"
    }
  ]
}

Async Processing & Webhooks

When using sync_mode: false, you can receive notifications via webhook when processing completes:

{
  "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"
    }
  ]
}

For detailed information about webhook setup, signature verification, and security best practices, see the Webhooks documentation.

Error Responses

{
  "error": "Question exceeds maximum length of 10,000 characters",
  "status": 400
}

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”

API Documentation

​Authentication

​Path Parameters

​Request Body

​Response

​Async Processing & Webhooks

​Error Responses

​Session Management

​Adding Questions to Existing Sessions

​ID vs Session ID

​Best Practices

​Sync vs Async Mode

​File Attachments

​Question Guidelines

​Use Cases

​1. Document Review & Analysis

​2. Template Filling & Document Generation

​3. Legal Research & Analysis

​4. Document Drafting & Creation

​5. Translation & Conversion

​6. Presentations & Spreadsheets

Authentication

Path Parameters

Request Body

Response

Async Processing & Webhooks

Error Responses

Session Management

Adding Questions to Existing Sessions

ID vs Session ID

Best Practices

Sync vs Async Mode

File Attachments

Question Guidelines

Use Cases

1. Document Review & Analysis

2. Template Filling & Document Generation

3. Legal Research & Analysis

4. Document Drafting & Creation

5. Translation & Conversion

6. Presentations & Spreadsheets