Create Assistant Question

curl --request POST \
  --url https://api.wordsmith.ai/api/v1/assistants/{assistant_id}/questions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "question": "<string>",
  "attachments": [
    {
      "upload_job_id": "<string>",
      "url": "<string>",
      "unzip": true
    }
  ],
  "session_id": "<string>",
  "permissions": {
    "visibility": "<string>"
  },
  "callback_url": "<string>",
  "sync_mode": true
}
'

import requests

url = "https://api.wordsmith.ai/api/v1/assistants/{assistant_id}/questions"

payload = {
    "question": "<string>",
    "attachments": [
        {
            "upload_job_id": "<string>",
            "url": "<string>",
            "unzip": True
        }
    ],
    "session_id": "<string>",
    "permissions": { "visibility": "<string>" },
    "callback_url": "<string>",
    "sync_mode": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    question: '<string>',
    attachments: [{upload_job_id: '<string>', url: '<string>', unzip: true}],
    session_id: '<string>',
    permissions: {visibility: '<string>'},
    callback_url: '<string>',
    sync_mode: true
  })
};

fetch('https://api.wordsmith.ai/api/v1/assistants/{assistant_id}/questions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.wordsmith.ai/api/v1/assistants/{assistant_id}/questions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'question' => '<string>',
    'attachments' => [
        [
                'upload_job_id' => '<string>',
                'url' => '<string>',
                'unzip' => true
        ]
    ],
    'session_id' => '<string>',
    'permissions' => [
        'visibility' => '<string>'
    ],
    'callback_url' => '<string>',
    'sync_mode' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.wordsmith.ai/api/v1/assistants/{assistant_id}/questions"

	payload := strings.NewReader("{\n  \"question\": \"<string>\",\n  \"attachments\": [\n    {\n      \"upload_job_id\": \"<string>\",\n      \"url\": \"<string>\",\n      \"unzip\": true\n    }\n  ],\n  \"session_id\": \"<string>\",\n  \"permissions\": {\n    \"visibility\": \"<string>\"\n  },\n  \"callback_url\": \"<string>\",\n  \"sync_mode\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.wordsmith.ai/api/v1/assistants/{assistant_id}/questions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"question\": \"<string>\",\n  \"attachments\": [\n    {\n      \"upload_job_id\": \"<string>\",\n      \"url\": \"<string>\",\n      \"unzip\": true\n    }\n  ],\n  \"session_id\": \"<string>\",\n  \"permissions\": {\n    \"visibility\": \"<string>\"\n  },\n  \"callback_url\": \"<string>\",\n  \"sync_mode\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.wordsmith.ai/api/v1/assistants/{assistant_id}/questions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"question\": \"<string>\",\n  \"attachments\": [\n    {\n      \"upload_job_id\": \"<string>\",\n      \"url\": \"<string>\",\n      \"unzip\": true\n    }\n  ],\n  \"session_id\": \"<string>\",\n  \"permissions\": {\n    \"visibility\": \"<string>\"\n  },\n  \"callback_url\": \"<string>\",\n  \"sync_mode\": true\n}"

response = http.request(request)
puts response.read_body

{
  "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"
    }
  ],
  "reason": 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,
  "reason": 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,
  "reason": 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,
  "reason": null
}

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "session_id": null,
  "session_url": null,
  "status": "filtered",
  "answer": "This assistant only handles commercial contract questions, and this one is about employment law.",
  "attachments": null,
  "reason": "This assistant only handles commercial contract questions, and this one is about employment law."
}

POST

api

assistants

{assistant_id}

questions

Create Assistant Question

curl --request POST \
  --url https://api.wordsmith.ai/api/v1/assistants/{assistant_id}/questions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "question": "<string>",
  "attachments": [
    {
      "upload_job_id": "<string>",
      "url": "<string>",
      "unzip": true
    }
  ],
  "session_id": "<string>",
  "permissions": {
    "visibility": "<string>"
  },
  "callback_url": "<string>",
  "sync_mode": true
}
'

import requests

url = "https://api.wordsmith.ai/api/v1/assistants/{assistant_id}/questions"

payload = {
    "question": "<string>",
    "attachments": [
        {
            "upload_job_id": "<string>",
            "url": "<string>",
            "unzip": True
        }
    ],
    "session_id": "<string>",
    "permissions": { "visibility": "<string>" },
    "callback_url": "<string>",
    "sync_mode": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    question: '<string>',
    attachments: [{upload_job_id: '<string>', url: '<string>', unzip: true}],
    session_id: '<string>',
    permissions: {visibility: '<string>'},
    callback_url: '<string>',
    sync_mode: true
  })
};

fetch('https://api.wordsmith.ai/api/v1/assistants/{assistant_id}/questions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.wordsmith.ai/api/v1/assistants/{assistant_id}/questions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'question' => '<string>',
    'attachments' => [
        [
                'upload_job_id' => '<string>',
                'url' => '<string>',
                'unzip' => true
        ]
    ],
    'session_id' => '<string>',
    'permissions' => [
        'visibility' => '<string>'
    ],
    'callback_url' => '<string>',
    'sync_mode' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.wordsmith.ai/api/v1/assistants/{assistant_id}/questions"

	payload := strings.NewReader("{\n  \"question\": \"<string>\",\n  \"attachments\": [\n    {\n      \"upload_job_id\": \"<string>\",\n      \"url\": \"<string>\",\n      \"unzip\": true\n    }\n  ],\n  \"session_id\": \"<string>\",\n  \"permissions\": {\n    \"visibility\": \"<string>\"\n  },\n  \"callback_url\": \"<string>\",\n  \"sync_mode\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.wordsmith.ai/api/v1/assistants/{assistant_id}/questions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"question\": \"<string>\",\n  \"attachments\": [\n    {\n      \"upload_job_id\": \"<string>\",\n      \"url\": \"<string>\",\n      \"unzip\": true\n    }\n  ],\n  \"session_id\": \"<string>\",\n  \"permissions\": {\n    \"visibility\": \"<string>\"\n  },\n  \"callback_url\": \"<string>\",\n  \"sync_mode\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.wordsmith.ai/api/v1/assistants/{assistant_id}/questions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"question\": \"<string>\",\n  \"attachments\": [\n    {\n      \"upload_job_id\": \"<string>\",\n      \"url\": \"<string>\",\n      \"unzip\": true\n    }\n  ],\n  \"session_id\": \"<string>\",\n  \"permissions\": {\n    \"visibility\": \"<string>\"\n  },\n  \"callback_url\": \"<string>\",\n  \"sync_mode\": true\n}"

response = http.request(request)
puts response.read_body

{
  "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"
    }
  ],
  "reason": 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,
  "reason": 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,
  "reason": 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,
  "reason": null
}

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "session_id": null,
  "session_url": null,
  "status": "filtered",
  "answer": "This assistant only handles commercial contract questions, and this one is about employment law.",
  "attachments": null,
  "reason": "This assistant only handles commercial contract questions, and this one is about employment law."
}

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

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

string

required

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

array

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

Show Attachment Object

string

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

string

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

boolean

default:"false"

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

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.

object

Optional permissions settings for the chat session.

Show Permissions Object

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

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.

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

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

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

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

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

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();

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

string

The unique identifier for this specific question. Always usable to check the question’s status, including when status is "filtered".

string

The session ID that contains this question. This is always the same for all questions within a conversation session. null only when status is "filtered", where no session was created.

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. null only when status is "filtered", where there is no session to view.

string

The current status of the question: "in_progress": Processing is ongoing. "completed": Answer is ready. "error": Processing failed. "filtered": The assistant declined the question — see Filtered questions.

string

The assistant’s response to your question. Present when status is "completed", and also when it is "filtered" — where it carries the decline wording, so a client that only reads answer still has something to show. See Filtered questions.

array

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

Show Attachment Object

string

The name of the generated file

string

The MIME type of the file

integer

The size of the file in bytes

string

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

string

One sentence explaining why the assistant declined the question. Present only when status is "filtered", and null for every other status. It may also be null on a filtered question — see Filtered questions — so treat it as an explanation to show when you have one, not a field to depend on.

{
  "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"
    }
  ],
  "reason": 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,
  "reason": 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,
  "reason": 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,
  "reason": null
}

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "session_id": null,
  "session_url": null,
  "status": "filtered",
  "answer": "This assistant only handles commercial contract questions, and this one is about employment law.",
  "attachments": null,
  "reason": "This assistant only handles commercial contract questions, and this one is about employment law."
}

Filtered Questions

An assistant can be configured with an intake instruction describing the work it accepts. When a new question does not match that instruction, the assistant declines it: the request returns status: "filtered" and no session is created. "filtered" is not an error. The request was well-formed and authenticated; the assistant simply decided the question was not for it. Handle it as its own outcome rather than as a failure to retry. Three things follow from no session existing:

session_id and session_url are null. They are null for this status and no other, so existing handling for "in_progress", "completed" and "error" is unaffected.
id is still valid. It identifies the filtered question, and GET /api/v1/assistants/{assistant_id}/questions/{id} keeps returning "filtered" for it. Nothing about the request is lost.
"filtered" is terminal. A filtered question never becomes "in_progress" or "completed", so polling loops must stop on it — see Get Question Status.

What you get back to show

Both answer and reason carry the decline wording, so a client written against answer alone keeps working without knowing the status exists:

reason is always the assistant’s own one-sentence explanation of why this question was declined — for example, “This article is about a new UK immigration white paper and salary thresholds for skilled worker visas, not about statutory minimum wage rates.”
answer is the same sentence, unless the assistant’s owner has written fixed wording to use instead. Doing so trades the per-question detail for a string you can rely on being identical every time.

Both are written for a person, so either is safe to log or show to whoever submitted the question. Neither is a stable identifier: the generated wording differs per question, and the fixed wording can be edited at any time. Branch on status, never on this text.

answer and reason can both be null on a "filtered" response. Questions filtered before these fields existed have no stored explanation, and one is not reconstructed on later polls. Show the explanation when it is there and fall back to your own copy when it is not.

Editing the assistant’s wording only affects questions filtered afterwards. Whatever a question was answered with is stored when it is declined, so re-polling an old id always returns what you were originally told. Only a new question is judged. A follow-up sent with session_id continues a conversation the assistant already accepted and is never filtered. If you supplied a callback_url, a "filtered" webhook is delivered too, so webhook-driven integrations are not left waiting for a run that will never happen.

An agent-backed assistant only accepts questions while its API intake is switched on. If it has been switched off, this endpoint returns 404 — the assistant also stops appearing in List Assistants. Questions asked before it was switched off remain pollable via Get Question Status, so an in-flight answer is never stranded.

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"
    }
  ],
  "reason": 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,
  "reason": null
}

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "session_id": null,
  "session_url": null,
  "status": "filtered",
  "answer": "This assistant only handles commercial contract questions, and this one is about employment law.",
  "attachments": null,
  "reason": "This assistant only handles commercial contract questions, and this one is about employment law."
}

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

Error Responses

See the Errors page for the full error format reference and handling guidance.

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

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

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

{
  "error_code": "unauthorized",
  "ws_api_error_code": "unauthorized",
  "message": "Invalid API key"
}

{
  "error_code": "resource_not_found",
  "ws_api_error_code": "resource_not_found",
  "message": "Question not found for this assistant."
}

{
  "error_code": "resource_not_found",
  "ws_api_error_code": "resource_not_found",
  "message": "Assistant 'a1b2c3d4' is not available over the API. Enable the agent's API intake to expose it."
}

{
  "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. For a filtered question it is an identifier of its own, naming a question no session was created for.
session_id: The session ID that contains this question. This remains constant for all questions within the same conversation, and is null when status is "filtered".

Use the id field to check the status of individual questions, and the session_id to identify which conversation session the question belongs to. Treat id as an opaque string: it is always present and always pollable, but do not assume it equals the session_id — that only holds for the first question of an accepted session.

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

Tasks

Directory

Create Assistant Question

Authentication

Path Parameters

Request Body

Response

Filtered Questions

What you get back to show

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

​Filtered Questions

​What you get back to show

​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

Filtered Questions

What you get back to show

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