---
sidebar_position: 3
title: API Reference
description: Complete resource, method, error class, and helper reference for @firetell/firetell-node-sdk.
---

# API Reference

All resources are exposed as properties on an initialized `Firetell` instance:

```typescript
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 | — |

---

## Further Reading

- [Workspace API Reference](/developers/rest-api/overview)
- [OpenAPI Playground](/developers/api-playground/workspace-api)
- [Webhooks Guide](/developers/rest-api/workspace-api/webhooks)
