API Reference
All resources are exposed as properties on an initialized Firetell instance:
const firetell = new Firetell({
domain: 'yourcompany.firetell.app',
secretKey: process.env.FIRETELL_SECRET_KEY!,
});
Resources Overview
firetell.workspace
| Method | HTTP Endpoint | Description |
|---|---|---|
getMetadata(options?) | GET /api/v1 | Get workspace public metadata and configuration |
getIceServers(options?) | GET /api/v1/ice-servers | Refresh WebRTC ICE/TURN server credentials |
firetell.agents
| Method | HTTP Endpoint | Description |
|---|---|---|
list(params?, options?) | GET /api/v1/agents | List agents with filters (state, role, is_active, country_code) |
create(data, options?) | POST /api/v1/agents | Create a new workspace agent |
retrieve(id, options?) | GET /api/v1/agents/{id} | Get agent details by ID |
update(id, data, options?) | PATCH /api/v1/agents/{id} | Update agent details |
delete(id, options?) | DELETE /api/v1/agents/{id} | Delete an agent |
listTeams(id, params?, options?) | GET /api/v1/agents/{id}/teams | List teams assigned to an agent |
uploadAvatar(id, file, options?) | PATCH /api/v1/agents/{id}/avatar | Upload agent avatar (multipart/form-data) |
changePassword(id, data, options?) | PATCH /api/v1/agents/{id}/password | Reset agent password |
firetell.teams
| Method | HTTP Endpoint | Description |
|---|---|---|
list(params?, options?) | GET /api/v1/teams | List workspace teams |
create(data, options?) | POST /api/v1/teams | Create a new team |
retrieve(id, options?) | GET /api/v1/teams/{id} | Get team details by ID |
update(id, data, options?) | PATCH /api/v1/teams/{id} | Update team title |
delete(id, options?) | DELETE /api/v1/teams/{id} | Delete a team |
listAgents(id, params?, options?) | GET /api/v1/teams/{id}/agents | List agents in a team |
addAgent(id, agentId, options?) | PUT /api/v1/teams/{id}/agents/{agent_id} | Add an agent to a team |
removeAgent(id, agentId, options?) | DELETE /api/v1/teams/{id}/agents/{agent_id} | Remove an agent from a team |
listAgentSuggestions(id, params?, options?) | GET /api/v1/teams/{id}/agents/suggestions | List active agents not yet in the team |
firetell.calls
| Method | HTTP Endpoint | Description |
|---|---|---|
list(params?, options?) | GET /api/v1/calls | List Call Detail Records (CDR) with filters |
make(data, options?) | POST /api/v1/calls/make | Initiate an outbound programmable call |
sendActions(id, data, options?) | PUT /api/v1/calls/{id}/actions | Execute active call control actions |
listEvents(id, params?, options?) | GET /api/v1/calls/{id}/events | Get call execution event timeline |
getRecordings(id, options?) | GET /api/v1/calls/{id}/recordings | List call recordings with presigned URLs |
deleteRecordings(id, options?) | DELETE /api/v1/calls/{id}/recordings | Delete all recordings for a call |
deleteRecording(id, recordingId, options?) | DELETE /api/v1/calls/{id}/recordings/{recording_id} | Delete a single recording by ID |
getRecordingStream(id, index?, options?) | GET /api/v1/calls/{id}/recordings/{index}/stream?redirect=false | Get presigned stream metadata (omit index for primary recording) |
getRecordingDownload(id, index?, options?) | GET /api/v1/calls/{id}/recordings/{index}/download?redirect=false | Get presigned download URL metadata |
getTranscription(id, options?) | GET /api/v1/calls/{id}/transcription | Get call transcription, dialogues, summary, and entities |
deleteTranscription(id, options?) | DELETE /api/v1/calls/{id}/transcription | Delete call transcription |
firetell.messages
| Method | HTTP Endpoint | Description |
|---|---|---|
send(data, options?) | POST /api/v1/messages/send | Send an SMS or MMS message |
list(params?, options?) | GET /api/v1/messages | List SMS/MMS message history |
retrieve(id, options?) | GET /api/v1/messages/{id} | Get message details by ID |
firetell.recordings & firetell.transcriptions
| Resource & Method | HTTP Endpoint | Description |
|---|---|---|
recordings.list(params?, options?) | GET /api/v1/recordings | List all workspace recordings |
recordings.bulkDelete(ids, options?) | DELETE /api/v1/recordings/bulk | Bulk delete recordings by IDs (max 100) |
transcriptions.list(params?, options?) | GET /api/v1/transcriptions | List all workspace transcriptions |
transcriptions.bulkDelete(ids, options?) | DELETE /api/v1/transcriptions/bulk | Bulk delete transcriptions by IDs (max 100) |
firetell.voiceAgents & firetell.voiceAgents.tools
| Method | HTTP Endpoint | Description |
|---|---|---|
list(params?, options?) | GET /api/v1/voice-agents | List Voice AI agents |
create(data, options?) | POST /api/v1/voice-agents | Create a Voice AI agent |
retrieve(id, params?, options?) | GET /api/v1/voice-agents/{id} | Get Voice AI agent details (optional version) |
update(id, data, options?) | PATCH /api/v1/voice-agents/{id} | Update Voice AI agent info |
delete(id, options?) | DELETE /api/v1/voice-agents/{id} | Delete Voice AI agent |
updateSettings(id, data, options?) | PATCH /api/v1/voice-agents/{id}/settings | Update prompt, model, voice, and settings |
listVersions(id, options?) | GET /api/v1/voice-agents/{id}/versions | List settings version history |
createVersion(id, options?) | POST /api/v1/voice-agents/{id}/version | Create a new draft version snapshot |
deleteVersion(id, version, options?) | DELETE /api/v1/voice-agents/{id}/version/{version} | Delete a draft version snapshot |
publish(id, data, options?) | PATCH /api/v1/voice-agents/{id}/publish | Publish a draft version to production |
testCall(id, params?, options?) | POST /api/v1/voice-agents/{id}/test-call | Initiate a WebRTC test call session |
listProviders(params?, options?) | GET /api/v1/voice-agents/providers | List supported AI providers |
listModels(params?, options?) | GET /api/v1/voice-agents/models | List supported Realtime models |
listVoices(params?, options?) | GET /api/v1/voice-agents/voices | List available system voices |
listBuiltinTools(options?) | GET /api/v1/voice-agents/builtin-tools | List built-in telephony tools |
tools.list(voiceAgentId, params?, options?) | GET /api/v1/voice-agents/{voiceAgentId}/tools | List custom tools for a Voice AI agent |
tools.create(voiceAgentId, data, options?) | POST /api/v1/voice-agents/{voiceAgentId}/tools | Create a custom webhook tool |
tools.retrieve(voiceAgentId, toolId, options?) | GET /api/v1/voice-agents/{voiceAgentId}/tools/{toolId} | Get a custom tool by ID |
tools.update(voiceAgentId, toolId, data, options?) | PATCH /api/v1/voice-agents/{voiceAgentId}/tools/{toolId} | Update a custom tool |
tools.delete(voiceAgentId, toolId, options?) | DELETE /api/v1/voice-agents/{voiceAgentId}/tools/{toolId} | Delete a custom tool |
firetell.knowledgeBases & firetell.knowledgeBases.documents
| Method | HTTP Endpoint | Description |
|---|---|---|
list(params?, options?) | GET /api/v1/knowledge-bases | List Knowledge Bases |
create(data, options?) | POST /api/v1/knowledge-bases | Create a Knowledge Base |
retrieve(id, options?) | GET /api/v1/knowledge-bases/{id} | Get Knowledge Base details |
update(id, data, options?) | PATCH /api/v1/knowledge-bases/{id} | Update Knowledge Base |
delete(id, options?) | DELETE /api/v1/knowledge-bases/{id} | Delete Knowledge Base |
getWorkspaceAnalytics(params?, options?) | GET /api/v1/knowledge-bases/analytics | Workspace-level Knowledge Base analytics |
getAnalytics(id, params?, options?) | GET /api/v1/knowledge-bases/{id}/analytics | Single Knowledge Base analytics |
documents.list(kbId, params?, options?) | GET /api/v1/knowledge-bases/{id}/documents | List documents in Knowledge Base |
documents.retrieve(kbId, docId, options?) | GET /api/v1/knowledge-bases/{id}/documents/{doc_id} | Get document details |
documents.delete(kbId, docId, options?) | DELETE /api/v1/knowledge-bases/{id}/documents/{doc_id} | Delete document |
documents.upload(kbId, file, options?) | POST /api/v1/knowledge-bases/{id}/documents/upload | Upload PDF, DOCX, XLSX, or TXT file |
documents.crawl(kbId, data, options?) | POST /api/v1/knowledge-bases/{id}/documents/crawl | Crawl web URLs into Knowledge Base |
documents.discoverUrls(kbId, data, options?) | POST /api/v1/knowledge-bases/{id}/documents/discover-urls | Auto-discover sitemap & page URLs |
documents.getDownloadUrl(kbId, docId, options?) | GET /api/v1/knowledge-bases/{id}/documents/{doc_id}/download-url | Get presigned download URL |
documents.bulkDelete(kbId, ids, options?) | POST /api/v1/knowledge-bases/{id}/documents/bulk-delete | Bulk delete documents |
documents.recrawl(kbId, docId, options?) | POST /api/v1/knowledge-bases/{id}/documents/{doc_id}/recrawl | Re-crawl and re-index a URL document |
Telephony, Contacts & Workspace Administration
| Resource | Methods |
|---|---|
firetell.phoneNumbers | list, retrieve, update, delete(id, otp) |
firetell.sipAccounts | list, create, update, delete |
firetell.extensions | list, create, update, delete |
firetell.audios | list, upload({ title, file }), retrieve, delete |
firetell.webhooks | list, create, retrieve, update, delete, testEvent, verifySignature, constructEvent |
firetell.contacts | list, create, lookup(number), retrieve, update, delete |
firetell.addressBooks | list, create, retrieve, update, delete |
firetell.callFlows | list, create, retrieve, delete |
firetell.invoices | list |
firetell.auditLogs | list, retrieve |
firetell.creditTransactions | list, retrieve |
Error Classes
| Error Class | HTTP Status / Condition | Extra Properties |
|---|---|---|
FiretellError | Base class for all SDK errors | statusCode, code, errors, raw |
FiretellValidationError | 400, 422 (or invalid webhook signature) | errors?: Array<{ field, messages }> |
FiretellAuthenticationError | 401 | — |
FiretellPermissionError | 403 | — |
FiretellNotFoundError | 404 | — |
FiretellConflictError | 409 | — |
FiretellRateLimitError | 429 | retryAfter, limit, remaining |
FiretellApiError | Other 4xx / 5xx responses | — |
FiretellTimeoutError | Request timeout exceeded | timeoutMs |
FiretellNetworkError | Network failure or aborted request | — |