Skip to main content
LLM ReadyRaw Markdown for AI agents:api-reference.mdFull index:llms.txtllms-full.txt

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​

MethodHTTP EndpointDescription
getMetadata(options?)GET /api/v1Get workspace public metadata and configuration
getIceServers(options?)GET /api/v1/ice-serversRefresh WebRTC ICE/TURN server credentials

firetell.agents​

MethodHTTP EndpointDescription
list(params?, options?)GET /api/v1/agentsList agents with filters (state, role, is_active, country_code)
create(data, options?)POST /api/v1/agentsCreate 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}/teamsList teams assigned to an agent
uploadAvatar(id, file, options?)PATCH /api/v1/agents/{id}/avatarUpload agent avatar (multipart/form-data)
changePassword(id, data, options?)PATCH /api/v1/agents/{id}/passwordReset agent password

firetell.teams​

MethodHTTP EndpointDescription
list(params?, options?)GET /api/v1/teamsList workspace teams
create(data, options?)POST /api/v1/teamsCreate 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}/agentsList 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/suggestionsList active agents not yet in the team

firetell.calls​

MethodHTTP EndpointDescription
list(params?, options?)GET /api/v1/callsList Call Detail Records (CDR) with filters
make(data, options?)POST /api/v1/calls/makeInitiate an outbound programmable call
sendActions(id, data, options?)PUT /api/v1/calls/{id}/actionsExecute active call control actions
listEvents(id, params?, options?)GET /api/v1/calls/{id}/eventsGet call execution event timeline
getRecordings(id, options?)GET /api/v1/calls/{id}/recordingsList call recordings with presigned URLs
deleteRecordings(id, options?)DELETE /api/v1/calls/{id}/recordingsDelete 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=falseGet presigned stream metadata (omit index for primary recording)
getRecordingDownload(id, index?, options?)GET /api/v1/calls/{id}/recordings/{index}/download?redirect=falseGet presigned download URL metadata
getTranscription(id, options?)GET /api/v1/calls/{id}/transcriptionGet call transcription, dialogues, summary, and entities
deleteTranscription(id, options?)DELETE /api/v1/calls/{id}/transcriptionDelete call transcription

firetell.messages​

MethodHTTP EndpointDescription
send(data, options?)POST /api/v1/messages/sendSend an SMS or MMS message
list(params?, options?)GET /api/v1/messagesList SMS/MMS message history
retrieve(id, options?)GET /api/v1/messages/{id}Get message details by ID

firetell.recordings & firetell.transcriptions​

Resource & MethodHTTP EndpointDescription
recordings.list(params?, options?)GET /api/v1/recordingsList all workspace recordings
recordings.bulkDelete(ids, options?)DELETE /api/v1/recordings/bulkBulk delete recordings by IDs (max 100)
transcriptions.list(params?, options?)GET /api/v1/transcriptionsList all workspace transcriptions
transcriptions.bulkDelete(ids, options?)DELETE /api/v1/transcriptions/bulkBulk delete transcriptions by IDs (max 100)

firetell.voiceAgents & firetell.voiceAgents.tools​

MethodHTTP EndpointDescription
list(params?, options?)GET /api/v1/voice-agentsList Voice AI agents
create(data, options?)POST /api/v1/voice-agentsCreate 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}/settingsUpdate prompt, model, voice, and settings
listVersions(id, options?)GET /api/v1/voice-agents/{id}/versionsList settings version history
createVersion(id, options?)POST /api/v1/voice-agents/{id}/versionCreate 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}/publishPublish a draft version to production
testCall(id, params?, options?)POST /api/v1/voice-agents/{id}/test-callInitiate a WebRTC test call session
listProviders(params?, options?)GET /api/v1/voice-agents/providersList supported AI providers
listModels(params?, options?)GET /api/v1/voice-agents/modelsList supported Realtime models
listVoices(params?, options?)GET /api/v1/voice-agents/voicesList available system voices
listBuiltinTools(options?)GET /api/v1/voice-agents/builtin-toolsList built-in telephony tools
tools.list(voiceAgentId, params?, options?)GET /api/v1/voice-agents/{voiceAgentId}/toolsList custom tools for a Voice AI agent
tools.create(voiceAgentId, data, options?)POST /api/v1/voice-agents/{voiceAgentId}/toolsCreate 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​

MethodHTTP EndpointDescription
list(params?, options?)GET /api/v1/knowledge-basesList Knowledge Bases
create(data, options?)POST /api/v1/knowledge-basesCreate 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/analyticsWorkspace-level Knowledge Base analytics
getAnalytics(id, params?, options?)GET /api/v1/knowledge-bases/{id}/analyticsSingle Knowledge Base analytics
documents.list(kbId, params?, options?)GET /api/v1/knowledge-bases/{id}/documentsList 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/uploadUpload PDF, DOCX, XLSX, or TXT file
documents.crawl(kbId, data, options?)POST /api/v1/knowledge-bases/{id}/documents/crawlCrawl web URLs into Knowledge Base
documents.discoverUrls(kbId, data, options?)POST /api/v1/knowledge-bases/{id}/documents/discover-urlsAuto-discover sitemap & page URLs
documents.getDownloadUrl(kbId, docId, options?)GET /api/v1/knowledge-bases/{id}/documents/{doc_id}/download-urlGet presigned download URL
documents.bulkDelete(kbId, ids, options?)POST /api/v1/knowledge-bases/{id}/documents/bulk-deleteBulk delete documents
documents.recrawl(kbId, docId, options?)POST /api/v1/knowledge-bases/{id}/documents/{doc_id}/recrawlRe-crawl and re-index a URL document

Telephony, Contacts & Workspace Administration​

ResourceMethods
firetell.phoneNumberslist, retrieve, update, delete(id, otp)
firetell.sipAccountslist, create, update, delete
firetell.extensionslist, create, update, delete
firetell.audioslist, upload({ title, file }), retrieve, delete
firetell.webhookslist, create, retrieve, update, delete, testEvent, verifySignature, constructEvent
firetell.contactslist, create, lookup(number), retrieve, update, delete
firetell.addressBookslist, create, retrieve, update, delete
firetell.callFlowslist, create, retrieve, delete
firetell.invoiceslist
firetell.auditLogslist, retrieve
firetell.creditTransactionslist, retrieve

Error Classes​

Error ClassHTTP Status / ConditionExtra Properties
FiretellErrorBase class for all SDK errorsstatusCode, code, errors, raw
FiretellValidationError400, 422 (or invalid webhook signature)errors?: Array<{ field, messages }>
FiretellAuthenticationError401—
FiretellPermissionError403—
FiretellNotFoundError404—
FiretellConflictError409—
FiretellRateLimitError429retryAfter, limit, remaining
FiretellApiErrorOther 4xx / 5xx responses—
FiretellTimeoutErrorRequest timeout exceededtimeoutMs
FiretellNetworkErrorNetwork failure or aborted request—

Further Reading​