Skip to main content

​
Prerequisites

Before you begin, make sure you have:
  • A Wordsmith account (sign up here)
  • An API key (see Authentication)
  • A tool to make HTTP requests (curl, Postman, or your preferred programming language)

​
Step 1: Test Your Authentication

First, let’s verify your API key works by getting your user information: 
curl -X GET "https://api.wordsmith.ai/api/v1/me" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json"
You should receive a response like: 
{
  "user_id": "12345",
  "customer_id": "67890",
  "user_name": "John Doe",
  "user_email": "john@example.com",
  "customer_name": "Example Law Firm"
}

​
Step 2: Ask Your First Question

Now let’s ask the AI assistant a legal question: 
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?",
    "sync_mode": true
  }'
The response will include: 
{
  "id": "session_123",
  "status": "completed",
  "answer": "A valid contract typically requires four key elements: 1) Offer - A clear proposal...",
  "attachments": null
}

​
Step 3: Upload and Analyze a Document

You can also upload documents for analysis. First, get an upload URL: 
curl -X POST "https://api.wordsmith.ai/api/v1/files/upload-url" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "contract.pdf",
    "content_type": "application/pdf"
  }'
Then upload your file to the returned URL and use the job ID in your question: 
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 summarize the key terms",
    "attachments": [
      {
        "upload_job_id": "upload_job_123"
      }
    ],
    "sync_mode": false,
    "callback_url": "https://your-app.com/webhooks/wordsmith"
  }'

​
Sync vs Async Mode

​
Sync Mode (sync_mode: true)

  • Response includes the complete answer immediately
  • Limited to 30 seconds processing time
  • Best for simple questions without attachments
  • Good for testing and development

​
Async Mode (sync_mode: false)

  • Returns immediately with status: "in_progress"
  • Longer processing time for complex questions
  • Requires polling or callback URL for results
  • Recommended for production use

​
Error Handling

Always check for errors in your responses: 
if (response.status >= 400) {
  console.error("API Error:", response.data);
  // Handle error appropriately
}
Common error status codes:
  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (invalid API key)
  • 429 - Too Many Requests (rate limit exceeded)
  • 500 - Internal Server Error

​
Next Steps

Now that you’ve made your first API calls:
  1. Explore the API Reference - See all available endpoints and parameters
  2. Set up webhooks - Use callback URLs to receive async results
  3. Integrate with your app - Build Wordsmith into your workflow
  4. Monitor usage - Keep track of your API usage and rate limits

​
SDK and Libraries

While we don’t currently provide official SDKs, the API works with any HTTP client library in your preferred programming language:
  • Python: requests, httpx
  • JavaScript/Node.js: fetch, axios
  • PHP: cURL, Guzzle
  • Ruby: net/http, Faraday
  • Java: OkHttp, Apache HttpClient

​
Need Help?

If you run into issues: