TfCode & API Integration
ToothFairyAI provides a comprehensive API that allows you to integrate AI capabilities directly into your applications and workflows.
Getting Started
Finding Your Credentials
You can find your Workspace ID and API Key in the ToothFairyAI dashboard under Admin → TFCode & API Integration.
Key Management
Workspace administrators have the ability to rotate (regenerate) API keys at any time. This is recommended for:
- Security best practices
- Responding to potential key compromises
- Onboarding/offboarding team members
To rotate your API key:
- Navigate to Admin → TFCode & API Integration
- Click Rotate API Key
- Confirm the action
Rotating your API key immediately invalidates the previous key. Update any applications or integrations using the old key to avoid service interruptions.
- TF Code is available to all paid users.
- API Integration (external programmatic API access) is available only on paid plans.
Authentication
All API requests require authentication using:
- API Key: Found in Admin → TFCode & API Integration
- Workspace ID: Found in Admin → TFCode & API Integration
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 | All paid plans |
api.eu.toothfairyai.com | Europe | All paid plans |
api.us.toothfairyai.com | United States | All paid plans |
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 is a pure PaaS product — there is no fixed monthly subscription. You buy intelligence credits upfront and are billed for the UoI (Units of Intelligence) you actually consume. Credits never expire, so you only ever pay for what you use.
API Access
External API access is available to all paid users.
| Subscription | External API Access |
|---|---|
| Serverless | Full API access |
| Enterprise | Full API access |
Intelligence Credits
Your AI usage is measured in UoI (Units of Intelligence) at 1 UoI = $0.01 USD. You pre-purchase intelligence credits, and UoI is debited from your credit balance as your agents run.
| Subscription | How you pay | Credits expiry |
|---|---|---|
| Serverless | Pay as you go — buy credits upfront, billed for UoI consumed | Credits never expire |
| Enterprise | Custom annual commitment with reserved UoI | Arranged with your account team |
- Serverless is consumption-based: top up your credit balance at any time. There is no fixed monthly minimum or maximum — you simply consume UoI as you go, and unused credits carry over indefinitely.
- Enterprise customers can request custom UoI allocations and reserved compute 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. Rate limits scale with your workspace and can be increased for Enterprise customers with custom allocations. Contact support if you need higher limits for production workloads.
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 credit balance 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 |
Credit Balance Exhausted
When your workspace has used up its intelligence credit balance:
{
"errorMessage": "The organisation has exhausted its intelligence credit balance. Please top up your credits to continue."
}
What to do:
- Check your current usage in the workspace dashboard
- Top up your intelligence credits — credits never expire, so any unused balance remains available
- Contact support if you need higher allocations
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 a paid plan for full API access
- Use the ToothFairyAI application or TF Code for AI features without external API access
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): https://mcp.toothfairyai.com/sse
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 credit consumption in real-time from your workspace dashboard:
- Navigate to Dashboard to view current usage
- Enable alerts in Settings > Other Settings > Notifications
- Receive notifications when approaching 80% and 100% of your credit balance
When your intelligence credit balance is exhausted, API requests will be rejected until you top up your credits. Credits never expire, so there is no monthly reset — any unused balance remains available.