API Integration
ToothFairyAI provides a comprehensive API that allows you to integrate AI capabilities directly into your applications and workflows.
Getting Started
Authentication
All API requests require authentication using:
- API Key: Provided in your workspace settings
- Workspace ID: Your unique workspace identifier
Include these in your request headers:
x-api-key: your-api-key
And in your request body:
{
"workspaceid": "your-workspace-id"
}
API Endpoints
ToothFairyAI provides three types of API endpoints, each available in multiple regions:
Platform Management (api.*)
Used for workspace and platform management operations.
| Domain | Region | Access |
|---|---|---|
api.toothfairyai.com | Australia | Business and Enterprise |
api.eu.toothfairyai.com | Europe | Business and Enterprise |
api.us.toothfairyai.com | United States | Business and Enterprise |
REST API (ai.*)
Standard REST endpoints for AI services with request/response pattern.
| Domain | Region | Access |
|---|---|---|
ai.toothfairyai.com | Australia | All subscriptions |
ai.eu.toothfairyai.com | Europe | All subscriptions |
ai.us.toothfairyai.com | United States | All subscriptions |
Streaming & Voice (ais.*)
Server-Sent Events (SSE) and Voice endpoints for real-time streaming responses.
| Domain | Region | Access |
|---|---|---|
ais.toothfairyai.com | Australia | All subscriptions |
ais.eu.toothfairyai.com | Europe | All subscriptions |
ais.us.toothfairyai.com | United States | All subscriptions |
Choose the regional endpoint closest to your users or based on your data residency requirements. All regional endpoints share the same quotas and functionality.
For complete endpoint documentation, visit the API Reference.
Usage & Limits
ToothFairyAI uses an Intelligence Budget system to give you flexible control over your AI usage. Instead of rigid per-service limits, your workspace receives a monthly budget that can be used across all AI services.
API Access
External API access is available for Business and Enterprise subscriptions. Starter and Pro users can access AI features through the ToothFairyAI application.
| Subscription | External API Access |
|---|---|
| Starter | Application only |
| Pro | Application only |
| Business | Full API access |
| Enterprise | Full API access |
Monthly Intelligence Budget
Your monthly AI budget is measured in UoI (Units of Intelligence) and scales with your subscription tier.
| Subscription | UoI per Capacity Unit | Minimum Units | Starting Budget |
|---|---|---|---|
| Starter | 500 | 1 | 500 UoI |
| Pro | 1,500 | 1 | 1,500 UoI |
| Business | 5,000 | 5 | 25,000 UoI |
| Enterprise | 7,500 | 10 | 75,000 UoI |
Your monthly budget is calculated as UoI per Unit × Capacity Units. For example:
- A Business workspace with 10 capacity units: 5,000 × 10 = 50,000 UoI/month
- An Enterprise workspace with 20 capacity units: 7,500 × 20 = 150,000 UoI/month
Enterprise customers can request custom UoI allocations tailored to their specific needs.
Rate Limits
To ensure optimal performance for all users, AI requests are subject to rate limits based on a 30-minute rolling window:
| Subscription | Requests per 30 minutes |
|---|---|
| Starter | 150 per capacity unit |
| Pro | 400 per capacity unit |
| Business | 1,000 per capacity unit |
| Enterprise | 2,000 per capacity unit |
Rate limits scale with your capacity units. A Business workspace with 5 capacity units can make up to 5,000 requests per 30 minutes.
What counts towards usage?
Your intelligence budget is consumed based on the AI processing required for each request. Different operations have different costs based on complexity:
- Chat & Agent interactions - Based on conversation length and complexity
- Content generation - Based on output length
- Document processing - Based on document size
- Search & retrieval - Minimal cost per query
You can monitor your current usage and remaining budget in real-time from your workspace dashboard.
Available Services
ToothFairyAI services are organised into three main categories:
| Category | Endpoints | Description |
|---|---|---|
| Platform Management | api.* | Workspace configuration, agents creation, user management, and platform administration |
| AI Agents | ai.* | Interact with AI agents for tasks, plans, search, and agentic use cases |
| Voice Agents | ais.* | Real-time voice interactions with AI agents using streaming |
For complete endpoint documentation, request/response formats, and usage examples, visit the API Reference.
Error Handling
Common Error Responses
| Status Code | Description | Solution |
|---|---|---|
| 400 | Bad Request | Check your request body and ensure all required fields are included |
| 401 | Unauthorized | Verify your API key and workspace ID are correct |
| 404 | Not Found | Check the endpoint path is correct |
| 500 | Server Error | Retry the request; contact support if persistent |
Budget Exceeded
When your workspace has used its monthly intelligence budget:
{
"errorMessage": "The organisation has reached its monthly intelligence budget. Please upgrade your plan or wait until the next billing cycle."
}
What to do:
- Check your current usage in the workspace dashboard
- Wait for your budget to reset at the start of your next billing cycle
- Upgrade your subscription or add capacity units for more budget
Rate Limit Exceeded
When you've made too many requests in a short period:
{
"errorMessage": "Too many requests in the last 30 minutes. Please try again in a few minutes or upgrade your plan"
}
What to do:
- Wait a few minutes before retrying
- Implement exponential backoff in your application
- Consider upgrading for higher rate limits
API Access Denied
If your subscription doesn't include external API access:
{
"errorMessage": "API access not allowed for this subscription type"
}
What to do:
- Upgrade to Business or Enterprise for full API access
- Use the ToothFairyAI application for AI features on Starter/Pro plans
CLI, SDK & MCP
ToothFairyAI provides multiple tools for developers to integrate AI capabilities into their workflows.
Command Line Tools & SDKs
For command-line access and programmatic integration, visit the Downloads page for:
- Python CLI & SDK: Install with
pip install toothfairy-cli - Node.js CLI & SDK: Install with
npm install @toothfairyai/cli
These tools provide command-line access to ToothFairyAI's features for automation, scripting, and integration into development workflows.
Model Context Protocol (MCP)
ToothFairyAI supports the Model Context Protocol for seamless integration with AI assistants and IDE extensions.
- MCP Server (SSE): mcp.toothfairyai.com
The MCP server uses Server-Sent Events (SSE) for real-time communication and can be configured in compatible AI tools and IDEs.
Monitoring Usage
Track your intelligence budget consumption in real-time from your workspace dashboard:
- Navigate to Dashboard to view current usage
- Enable budget alerts in Settings > Other Settings > Notifications
- Receive notifications when approaching 80% and 100% of your monthly budget
When your monthly intelligence budget is exhausted, API requests will be rejected until:
- Your budget resets at the start of your next billing cycle, or
- You upgrade your subscription or add capacity units