Skip to main content

ToothFairyAI API - Quick Guide

A simple guide to upload files and chat with documents.

Prerequisites​

You need:

  • API Key: Your ToothFairyAI API key
  • Workspace ID: Your workspace identifier
  • Agent ID: Your agent identifier

Step 1: Upload a File​

Request 1.1: Get Pre-Signed Upload URL​

Method: GET

URL:

https://api.toothfairyai.com/documents/requestPreSignedURL

Headers:

KeyValue
x-api-keyYOUR_API_KEY
Content-Typeapplication/json

Query Params:

KeyValueExample
filenameimported_doc_files/{workspace-id}/{timestamp}{filename}imported_doc_files/6586b7e6-683e-4ee6-a6cf-24c19729b5ff/1760886623830contract.pdf
importTypepdf, image, spreadsheet, or documentpdf
contentTypeMIME typeapplication/pdf

Example Query Params:

filename: imported_doc_files/6586b7e6-683e-4ee6-a6cf-24c19729b5ff/1760886623830contract.pdf
importType: pdf
contentType: application/pdf

Response (Copy the uploadURL for next step):

{
  "uploadURL": "https://s3.amazonaws.com/bucket/presigned-url...",
  "filePath": "s3://bucket/imported_doc_files/6586b7e6-683e-4ee6-a6cf-24c19729b5ff/1760886623830contract.pdf"
}

Request 1.2: Upload File to S3​

Method: PUT

URL:

[Paste the uploadURL from previous response]

Headers:

KeyValue
Content-Typeapplication/pdf (or your file's MIME type)

Body:

  • Select binary
  • Click "Select File" and choose your file

Response: Empty (200 OK means success)

Step 2: Chat with Uploaded File​

Request 2.1: Send Message with File Attachment​

Method: POST

URL:

https://ais.toothfairyai.com/agent

Headers:

KeyValue
x-api-keyYOUR_API_KEY
Content-Typeapplication/json

Body (select raw and JSON):

For Documents (PDFs, Excel, Word, etc.)​

{
  "workspaceid": "6586b7e6-683e-4ee6-a6cf-24c19729b5ff",
  "agentid": "your-agent-id",
  "chatid": null,
  "messages": [
    {
      "text": "Summarize this document",
      "role": "user",
      "files": ["imported_doc_files/6586b7e6-683e-4ee6-a6cf-24c19729b5ff/1760886623830contract.pdf"]
    }
  ]
}

For Images​

{
  "workspaceid": "6586b7e6-683e-4ee6-a6cf-24c19729b5ff",
  "agentid": "your-agent-id",
  "chatid": null,
  "messages": [
    {
      "text": "What's in this image?",
      "role": "user",
      "images": ["imported_doc_files/6586b7e6-683e-4ee6-a6cf-24c19729b5ff/1760886623830photo.png"]
    }
  ]
}

For Videos​

{
  "workspaceid": "6586b7e6-683e-4ee6-a6cf-24c19729b5ff",
  "agentid": "your-agent-id",
  "chatid": null,
  "messages": [
    {
      "text": "Describe this video",
      "role": "user",
      "videos": ["imported_video_files/6586b7e6-683e-4ee6-a6cf-24c19729b5ff/1760886623830video.mp4"]
    }
  ]
}

For Audios​

{
  "workspaceid": "6586b7e6-683e-4ee6-a6cf-24c19729b5ff",
  "agentid": "your-agent-id",
  "chatid": null,
  "messages": [
    {
      "text": "Transcribe this audio",
      "role": "user",
      "audios": ["imported_audio_files/6586b7e6-683e-4ee6-a6cf-24c19729b5ff/1760886623830audio.mp3"]
    }
  ]
}

Response:

{
  "message": "This document is a contract between...",
  "chatid": "new-chat-id-123"
}

File Path Structure​

Format​

{folder}/{workspace-id}/{timestamp}{filename}

Folders by File Type​

File TypeFolder NameExample
Documents (PDF, Excel, Word, Text)imported_doc_filesimported_doc_files/6586b7e6-683e-4ee6-a6cf-24c19729b5ff/1760886623830report.pdf
Images (PNG, JPG, GIF, WebP)imported_doc_filesimported_doc_files/6586b7e6-683e-4ee6-a6cf-24c19729b5ff/1760886623830photo.png
Videos (MP4, MOV, AVI)imported_video_filesimported_video_files/6586b7e6-683e-4ee6-a6cf-24c19729b5ff/1760886623830video.mp4
Audios (MP3, WAV, M4A)imported_audio_filesimported_audio_files/6586b7e6-683e-4ee6-a6cf-24c19729b5ff/1760886623830audio.mp3

Timestamp​

Use Unix timestamp in milliseconds:

// JavaScript
const timestamp = Date.now(); // e.g., 1760886623830

// Python
import time
timestamp = int(time.time() * 1000) # e.g., 1760886623830

Quick Reference: Chat Message Fields​

FieldUse ForExample
filesPDF, Excel, Word, Text["imported_doc_files/workspace-id/timestamp_file.pdf"]
imagesPNG, JPG, GIF, WebP["imported_doc_files/workspace-id/timestamp_photo.png"]
videosMP4, MOV, AVI["imported_video_files/workspace-id/timestamp_video.mp4"]
audiosMP3, WAV, M4A["imported_audio_files/workspace-id/timestamp_audio.mp3"]

Complete Example: Upload PDF and Ask Questions​

Step 1: Upload PDF​

GET Request: https://api.toothfairyai.com/documents/requestPreSignedURL

Query Params:

filename: imported_doc_files/6586b7e6-683e-4ee6-a6cf-24c19729b5ff/1760886623830contract.pdf
importType: pdf
contentType: application/pdf

Headers:

x-api-key: your-api-key
Content-Type: application/json

Response: Copy the uploadURL

Step 2: Upload to S3​

PUT Request: [paste uploadURL from step 1]

Headers:

Content-Type: application/pdf

Body: Binary (select your PDF file)

Step 3: Chat with PDF​

POST Request: https://ais.toothfairyai.com/agent

Headers:

x-api-key: your-api-key
Content-Type: application/json

Body (JSON):

{
  "workspaceid": "6586b7e6-683e-4ee6-a6cf-24c19729b5ff",
  "agentid": "your-agent-id",
  "chatid": null,
  "messages": [
    {
      "text": "What are the key terms in this contract?",
      "role": "user",
      "files": ["imported_doc_files/6586b7e6-683e-4ee6-a6cf-24c19729b5ff/1760886623830contract.pdf"]
    }
  ]
}

Tips​

  1. Generate Timestamp: Use Date.now() in JavaScript or int(time.time() * 1000) in Python
  2. File Paths: Always use the correct folder prefix based on file type
  3. Multiple Files: You can attach multiple files/images:
    "files": [
      "imported_doc_files/workspace-id/1760886623830file1.pdf",
      "imported_doc_files/workspace-id/1760886623831file2.pdf"
    ]
  4. Continue Conversation: Save the chatid from the response and use it in the next request to maintain context

Common Errors​

Error: "Invalid filename"​

Solution: Ensure filename follows format: {folder}/{workspace-id}/{timestamp}{filename}

Error: "File not found"​

Solution: Make sure you completed the S3 upload (Step 1.2) successfully before chatting

Error: "401 Unauthorized"​

Solution: Check your API key in the x-api-key header

Last Updated: 2025-10-19