Authentication & routing

Credentials

Every client needs two credentials:

Credential	Where to find it	Sent as
API key	Settings → API Keys	x-api-key header
Workspace ID	Settings → General (UUID v4)	workspaceid field on every write, and workspaceid query param on every read

The SDKs inject the workspace ID automatically — you set it once on the client and never pass it per-call.

Three routing domains

ToothFairyAI traffic is served from three endpoints. The SDKs select the right one for you based on the manager/method you call, but it helps to know which is which when reading the per-method Endpoint lines:

Domain	Default base URL	Used for	SDK method
Core API	https://api.toothfairyai.com	CRUD for every resource (agents, chats, documents, …)	client.request() / client.request()
AI service	https://ai.toothfairyai.com	Predictions, planner, agent chat (/agent), search, embeddings, dispatch	client.aiRequest() / client.ai_request()
Streaming	https://ais.toothfairyai.com	Server-Sent Events (SSE) for streaming predictions and agent responses	client.getStreamingUrl() / client.get_streaming_url()

Each manager page labels its methods with the domain they hit (for example POST /agent/create · API service vs POST /agent · AI streaming service (SSE)).

Node.js client

import { ToothFairyClient } from "@toothfairyai/sdk";

const client = new ToothFairyClient({
  apiKey: process.env.TF_API_KEY!,
  workspaceId: process.env.TF_WORKSPACE_ID!,
  // optional overrides (defaults shown):
  baseUrl: "https://api.toothfairyai.com",
  aiUrl: "https://ai.toothfairyai.com",
  aiStreamUrl: "https://ais.toothfairyai.com",
  timeout: 120000, // ms
});

ToothFairyClientConfig fields:

Field	Type	Required	Description
apiKey	string	yes	API key sent as x-api-key.
workspaceId	string	yes	Workspace UUID, auto-injected into every request.
baseUrl	string	no	Core API base URL. Default https://api.toothfairyai.com.
aiUrl	string	no	AI service base URL. Default https://ai.toothfairyai.com.
aiStreamUrl	string	no	Streaming base URL. Default https://ais.toothfairyai.com.
timeout	number	no	Request timeout in ms. Default 120000.

Errors are thrown as ToothFairyError (with code and status_code); see Error handling.

Python client

from toothfairyai import ToothFairyClient

client = ToothFairyClient(
    api_key=os.environ["TF_API_KEY"],
    workspace_id=os.environ["TF_WORKSPACE_ID"],
    # optional overrides (defaults shown):
    base_url="https://api.toothfairyai.com",
    ai_url="https://ai.toothfairyai.com",
    ai_stream_url="https://ais.toothfairyai.com",
    timeout=120,
    user_agent=None,
)

ToothFairyClient.__init__ parameters:

Parameter	Type	Required	Description
api_key	str	yes	API key sent as x-api-key. Raises MissingApiKeyError if empty.
workspace_id	str	yes	Workspace UUID, auto-injected into every request. Raises MissingWorkspaceIdError if empty.
base_url	str	no	Core API base URL. Default https://api.toothfairyai.com.
ai_url	str	no	AI service base URL. Default https://ai.toothfairyai.com.
ai_stream_url	str	no	Streaming base URL. Default https://ais.toothfairyai.com.
timeout	int	no	Request timeout in seconds. Default 120.
user_agent	str	no	Custom User-Agent header.

Environment variables

Both CLIs read credentials from the environment so you don't have to pass them on every invocation:

export TF_API_KEY="your-api-key"
export TF_WORKSPACE_ID="your-workspace-id"

The CLIs also accept --apiKey / --workspaceid flags (Node) and --api-key / --workspace-id flags (Python), which override the environment.