# Create or get shareable link for an agent version
Source: https://docs.featherhq.com/api-reference/agent-shares/create-or-get-shareable-link-for-an-agent-version
post /api/v1/agent/version/{versionId}/share
Generate a shareable link for a specific agent version. Returns existing link if one already exists.
# Delete the shareable link for an agent version
Source: https://docs.featherhq.com/api-reference/agent-shares/delete-the-shareable-link-for-an-agent-version
delete /api/v1/agent/version/{versionId}/share
Delete the shareable link for a specific agent version
# Dispatch a shared agent (web mode)
Source: https://docs.featherhq.com/api-reference/agent-shares/dispatch-a-shared-agent-web-mode
post /api/v1/share/{token}/dispatch
Create a web call session using a shared agent link
# Get shareable link for an agent version
Source: https://docs.featherhq.com/api-reference/agent-shares/get-shareable-link-for-an-agent-version
get /api/v1/agent/version/{versionId}/share
Get the shareable link for a specific agent version (only one per version)
# Update the shareable link for an agent version
Source: https://docs.featherhq.com/api-reference/agent-shares/update-the-shareable-link-for-an-agent-version
patch /api/v1/agent/version/{versionId}/share
Update the seconds limit for a shareable link
# Start chat test session
Source: https://docs.featherhq.com/api-reference/agent-test/start-chat-test-session
post /api/v1/agent-test/sessions/start
Initialize a new chat test session for an agent without making a phone call
# Clone an existing agent
Source: https://docs.featherhq.com/api-reference/agents/clone-an-existing-agent
post /api/v1/agents/{id}/clone
Clone an existing agent with either the latest or deployed version
# Create a new agent
Source: https://docs.featherhq.com/api-reference/agents/create-a-new-agent
post /api/v1/agents
Create a new voice or text (SMS) agent
# Create agent version
Source: https://docs.featherhq.com/api-reference/agents/create-agent-version
post /api/v1/agents/{agentId}
Create a new version for an existing agent
# Delete agent version
Source: https://docs.featherhq.com/api-reference/agents/delete-agent-version
delete /api/v1/agents/{agentId}/versions/{versionId}
Delete a version of an agent
# Delete an agent
Source: https://docs.featherhq.com/api-reference/agents/delete-an-agent
delete /api/v1/agents/{agentId}
Delete an agent
# Deploy agent version
Source: https://docs.featherhq.com/api-reference/agents/deploy-agent-version
patch /api/v1/agents/{agentId}/versions/{versionId}/deploy
Deploy an existing agent version
# List agent deployments
Source: https://docs.featherhq.com/api-reference/agents/list-agent-deployments
get /api/v1/agents/{agentId}/deployments
List all deployments for an agent
# List agent versions
Source: https://docs.featherhq.com/api-reference/agents/list-agent-versions
get /api/v1/agents/{agentId}/versions
List all versions of an agent with cursor-based pagination
# List all agents
Source: https://docs.featherhq.com/api-reference/agents/list-all-agents
get /api/v1/agents
List all agents with cursor-based pagination
# Update agent version
Source: https://docs.featherhq.com/api-reference/agents/update-agent-version
patch /api/v1/agents/{agentId}/versions/{versionId}
Update an existing agent version
# Update agent version email configuration
Source: https://docs.featherhq.com/api-reference/agents/update-agent-version-email-configuration
patch /api/v1/agents/{agentId}/versions/{versionId}/email-config
Update the email-specific configuration for an agent version. The linked domain must be VERIFIED before it can be used.
# Update an agent
Source: https://docs.featherhq.com/api-reference/agents/update-an-agent
patch /api/v1/agents/{agentId}
Update an existing agent
# Delete bridging number
Source: https://docs.featherhq.com/api-reference/bridging-numbers/delete-bridging-number
delete /api/v1/twilio/bridging-number/{id}
# Import bridging number from Twilio account
Source: https://docs.featherhq.com/api-reference/bridging-numbers/import-bridging-number-from-twilio-account
post /api/v1/twilio/bridging-number
# List organization bridging numbers
Source: https://docs.featherhq.com/api-reference/bridging-numbers/list-organization-bridging-numbers
get /api/v1/twilio/bridging-number
# Cancel a booking
Source: https://docs.featherhq.com/api-reference/calendar-bookings/cancel-a-booking
post /api/v1/calendar-bookings/{bookingId}/cancel
# Create a booking
Source: https://docs.featherhq.com/api-reference/calendar-bookings/create-a-booking
post /api/v1/calendar-bookings
# Get a booking
Source: https://docs.featherhq.com/api-reference/calendar-bookings/get-a-booking
get /api/v1/calendar-bookings/{bookingId}
# List bookings
Source: https://docs.featherhq.com/api-reference/calendar-bookings/list-bookings
get /api/v1/calendar-bookings
# Reschedule a booking
Source: https://docs.featherhq.com/api-reference/calendar-bookings/reschedule-a-booking
post /api/v1/calendar-bookings/{bookingId}/reschedule
# Delete a calendar connection
Source: https://docs.featherhq.com/api-reference/calendar-connections/delete-a-calendar-connection
delete /api/v1/calendars/{calendarId}/connections/{connectionId}
# Get OAuth URL for external calendar
Source: https://docs.featherhq.com/api-reference/calendar-connections/get-oauth-url-for-external-calendar
get /api/v1/calendars/{calendarId}/connections/oauth-url
# List calendar connections
Source: https://docs.featherhq.com/api-reference/calendar-connections/list-calendar-connections
get /api/v1/calendars/{calendarId}/connections
# List external calendars from a connected account
Source: https://docs.featherhq.com/api-reference/calendar-connections/list-external-calendars-from-a-connected-account
get /api/v1/calendars/{calendarId}/connections/{connectionId}/external-calendars
# OAuth callback for external calendar
Source: https://docs.featherhq.com/api-reference/calendar-connections/oauth-callback-for-external-calendar
get /api/v1/calendar-connections/oauth/callback
# Update a calendar connection
Source: https://docs.featherhq.com/api-reference/calendar-connections/update-a-calendar-connection
patch /api/v1/calendars/{calendarId}/connections/{connectionId}
# Create an event type
Source: https://docs.featherhq.com/api-reference/calendar-event-types/create-an-event-type
post /api/v1/calendars/{calendarId}/event-types
# Delete an event type
Source: https://docs.featherhq.com/api-reference/calendar-event-types/delete-an-event-type
delete /api/v1/calendars/{calendarId}/event-types/{eventTypeId}
# Get an event type
Source: https://docs.featherhq.com/api-reference/calendar-event-types/get-an-event-type
get /api/v1/calendars/{calendarId}/event-types/{eventTypeId}
# Get available slots
Source: https://docs.featherhq.com/api-reference/calendar-event-types/get-available-slots
get /api/v1/calendars/{calendarId}/event-types/{eventTypeId}/slots
# List event types
Source: https://docs.featherhq.com/api-reference/calendar-event-types/list-event-types
get /api/v1/calendars/{calendarId}/event-types
# Update an event type
Source: https://docs.featherhq.com/api-reference/calendar-event-types/update-an-event-type
patch /api/v1/calendars/{calendarId}/event-types/{eventTypeId}
# Create a schedule
Source: https://docs.featherhq.com/api-reference/calendar-schedules/create-a-schedule
post /api/v1/calendars/{calendarId}/schedules
# Delete a schedule
Source: https://docs.featherhq.com/api-reference/calendar-schedules/delete-a-schedule
delete /api/v1/calendars/{calendarId}/schedules/{scheduleId}
# Get a schedule
Source: https://docs.featherhq.com/api-reference/calendar-schedules/get-a-schedule
get /api/v1/calendars/{calendarId}/schedules/{scheduleId}
# List schedules
Source: https://docs.featherhq.com/api-reference/calendar-schedules/list-schedules
get /api/v1/calendars/{calendarId}/schedules
# Update a schedule
Source: https://docs.featherhq.com/api-reference/calendar-schedules/update-a-schedule
patch /api/v1/calendars/{calendarId}/schedules/{scheduleId}
# Create a calendar
Source: https://docs.featherhq.com/api-reference/calendars/create-a-calendar
post /api/v1/calendars
# Delete a calendar
Source: https://docs.featherhq.com/api-reference/calendars/delete-a-calendar
delete /api/v1/calendars/{calendarId}
# Get a calendar
Source: https://docs.featherhq.com/api-reference/calendars/get-a-calendar
get /api/v1/calendars/{calendarId}
# List calendars
Source: https://docs.featherhq.com/api-reference/calendars/list-calendars
get /api/v1/calendars
# Update a calendar
Source: https://docs.featherhq.com/api-reference/calendars/update-a-calendar
patch /api/v1/calendars/{calendarId}
# Get a fresh presigned recording URL
Source: https://docs.featherhq.com/api-reference/calls/get-a-fresh-presigned-recording-url
get /api/v1/agent-calls/{id}/recording-url
Generate a fresh presigned URL for the agent call recording. Use when the URL delivered in the webhook or list/get endpoints has expired. Pass ?type=supervisor to fetch the warm-transfer supervisor leg recording instead of the main call recording.
# Get call record
Source: https://docs.featherhq.com/api-reference/calls/get-call-record
get /api/v1/agent-calls/{id}
Get an agent call by ID
# List all calls
Source: https://docs.featherhq.com/api-reference/calls/list-all-calls
get /api/v1/agent-calls
List agent calls with cursor-based pagination
# Create a new web chat thread
Source: https://docs.featherhq.com/api-reference/chat/create-a-new-web-chat-thread
post /api/v1/chat/threads
Create a new chat thread for web-based conversations. Returns thread ID and authentication token.
# Get messages for a web chat thread
Source: https://docs.featherhq.com/api-reference/chat/get-messages-for-a-web-chat-thread
get /api/v1/chat/threads/{threadId}/messages
Get paginated message history for a web chat thread. Requires chat JWT authentication.
# Get web chat thread session details
Source: https://docs.featherhq.com/api-reference/chat/get-web-chat-thread-session-details
get /api/v1/chat/threads/{threadId}
Get session metadata for a web chat thread. Requires chat JWT authentication.
# Update web chat thread session metadata
Source: https://docs.featherhq.com/api-reference/chat/update-web-chat-thread-session-metadata
patch /api/v1/chat/threads/{threadId}
Merge metadata and/or variables on a web chat thread. Requires chat JWT authentication.
# Add an ElevenLabs voice to collection and database
Source: https://docs.featherhq.com/api-reference/configuration/add-an-elevenlabs-voice-to-collection-and-database
post /api/v1/admin/elevenlabs-voices
Adds a voice to the Feather ElevenLabs account collection, then upserts a single AvailableVoice row for the given model and languageId.
# Get available voices
Source: https://docs.featherhq.com/api-reference/configuration/get-available-voices
get /api/v1/available-voices
Get all available voices
# Get LLM configs
Source: https://docs.featherhq.com/api-reference/configuration/get-llm-configs
get /api/v1/llm-configs
Get all available LLM configurations
# Get STT configs
Source: https://docs.featherhq.com/api-reference/configuration/get-stt-configs
get /api/v1/stt-configs
Get all available STT configurations
# Get supported languages
Source: https://docs.featherhq.com/api-reference/configuration/get-supported-languages
get /api/v1/languages
Get all active supported languages
# Get TTS configs
Source: https://docs.featherhq.com/api-reference/configuration/get-tts-configs
get /api/v1/tts-configs
Get all available TTS configurations
# Disconnect explicit dispatch
Source: https://docs.featherhq.com/api-reference/dispatch/disconnect-explicit-dispatch
post /agents/{agentId}/version/{version}/disconnect
# Dispatch audio agent
Source: https://docs.featherhq.com/api-reference/dispatch/dispatch-audio-agent
post /api/v1/agent/{agentId}/dispatch
Create a new explicit dispatch for a specific agent
# Listen to audio agent
Source: https://docs.featherhq.com/api-reference/dispatch/listen-to-audio-agent
post /api/v1/agent/listen
Create a listener token to join an existing agent call room
# Add phone number to DNC list
Source: https://docs.featherhq.com/api-reference/dnc/add-phone-number-to-dnc-list
post /api/v1/dnc
Add a phone number to the Do Not Call block list
# Check if phone number is on DNC list
Source: https://docs.featherhq.com/api-reference/dnc/check-if-phone-number-is-on-dnc-list
get /api/v1/dnc/check/{phoneNumber}
Check if a phone number is on the DNC block list (URL encoded, e.g., %2B14155551234)
# Delete DNC entry by ID
Source: https://docs.featherhq.com/api-reference/dnc/delete-dnc-entry-by-id
delete /api/v1/dnc/{id}
Remove a phone number from the DNC block list by entry ID
# Delete DNC entry by phone number
Source: https://docs.featherhq.com/api-reference/dnc/delete-dnc-entry-by-phone-number
delete /api/v1/dnc/phone/{phoneNumber}
Remove a phone number from the DNC block list by phone number (URL encoded, e.g., %2B14155551234)
# Get DNC entry by ID
Source: https://docs.featherhq.com/api-reference/dnc/get-dnc-entry-by-id
get /api/v1/dnc/{id}
Get a DNC entry by its ID
# Get DNC entry by phone number
Source: https://docs.featherhq.com/api-reference/dnc/get-dnc-entry-by-phone-number
get /api/v1/dnc/phone/{phoneNumber}
Get a DNC entry by phone number (URL encoded, e.g., %2B14155551234)
# List DNC entries
Source: https://docs.featherhq.com/api-reference/dnc/list-dnc-entries
get /api/v1/dnc
List all DNC entries with cursor-based pagination
# Create a Gmail-backed email domain
Source: https://docs.featherhq.com/api-reference/email-domains/create-a-gmail-backed-email-domain
post /api/v1/email-domains/gmail
Link a connected Gmail account as an email domain. No DNS setup required — the agent reads and sends via the Gmail API.
# Create an email domain
Source: https://docs.featherhq.com/api-reference/email-domains/create-an-email-domain
post /api/v1/email-domains
Register a new subdomain with Resend and return the DNS records the customer must add to their DNS provider.
# Create SendGrid email integration
Source: https://docs.featherhq.com/api-reference/email-domains/create-sendgrid-email-integration
post /api/v1/email-domains/sendgrid
Store SendGrid API credentials and create a verified email domain. Assign the domain to an agent under Agent Builder → Email Settings. Returns the inbound webhook URL for SendGrid Inbound Parse.
# Delete an email domain
Source: https://docs.featherhq.com/api-reference/email-domains/delete-an-email-domain
delete /api/v1/email-domains/{domainId}
Delete an email domain. Fails if any agent version is currently using this domain.
# Get an email domain
Source: https://docs.featherhq.com/api-reference/email-domains/get-an-email-domain
get /api/v1/email-domains/{domainId}
Retrieve a single email domain by ID
# List email domains
Source: https://docs.featherhq.com/api-reference/email-domains/list-email-domains
get /api/v1/email-domains
List all email domains for the organization
# Verify an email domain
Source: https://docs.featherhq.com/api-reference/email-domains/verify-an-email-domain
post /api/v1/email-domains/{domainId}/verify
Trigger Resend domain verification and update per-record verification state. Returns the updated domain with mxVerified, spfVerified, dkimVerified, cnameVerified flags.
# Terminate an email thread
Source: https://docs.featherhq.com/api-reference/email-threads/terminate-an-email-thread
patch /api/v1/email/threads/{threadId}/terminate
Permanently close an email thread. Terminated threads cannot be reopened by inbound replies — new replies create a fresh thread instead.
# Approve an email draft
Source: https://docs.featherhq.com/api-reference/email/approve-an-email-draft
post /api/v1/email/drafts/{messageId}/approve
Approve a draft email message and send it
# Create an email thread
Source: https://docs.featherhq.com/api-reference/email/create-an-email-thread
post /api/v1/email/threads
Initialize an outbound email thread for the given agent version. The version must be deployed and have a verified email domain configured.
# Discard an email draft
Source: https://docs.featherhq.com/api-reference/email/discard-an-email-draft
delete /api/v1/email/drafts/{messageId}
Discard (delete) a draft email message
# Edit an email draft
Source: https://docs.featherhq.com/api-reference/email/edit-an-email-draft
patch /api/v1/email/drafts/{messageId}
Edit the body of a draft email message
# Get messages for an email thread
Source: https://docs.featherhq.com/api-reference/email/get-messages-for-an-email-thread
get /api/v1/email/threads/{threadId}/messages
Get messages for a specific email thread with cursor-based pagination
# List email drafts
Source: https://docs.featherhq.com/api-reference/email/list-email-drafts
get /api/v1/email/drafts
List email draft messages pending human review with cursor-based pagination
# List email threads
Source: https://docs.featherhq.com/api-reference/email/list-email-threads
get /api/v1/email/threads
List email threads with cursor-based pagination and optional filters
# Delete a Gmail connection
Source: https://docs.featherhq.com/api-reference/gmail-connections/delete-a-gmail-connection
delete /api/v1/gmail/connections/{connectionId}
# Get OAuth URL for Gmail connection
Source: https://docs.featherhq.com/api-reference/gmail-connections/get-oauth-url-for-gmail-connection
get /api/v1/gmail/connections/oauth-url
# List Gmail connections for organization
Source: https://docs.featherhq.com/api-reference/gmail-connections/list-gmail-connections-for-organization
get /api/v1/gmail/connections
# OAuth callback for Gmail connection
Source: https://docs.featherhq.com/api-reference/gmail-connections/oauth-callback-for-gmail-connection
get /api/v1/gmail/oauth/callback
# Health check
Source: https://docs.featherhq.com/api-reference/health/health-check
get /health
# Create an integration instance
Source: https://docs.featherhq.com/api-reference/integrations/create-an-integration-instance
post /api/v1/integrations/create
Create a new integration instance for the organization
# Delete an integration instance
Source: https://docs.featherhq.com/api-reference/integrations/delete-an-integration-instance
delete /api/v1/integrations/{integrationInstanceId}
Delete an integration instance for the organization
# List all available integrations
Source: https://docs.featherhq.com/api-reference/integrations/list-all-available-integrations
get /api/v1/integrations
List all available integrations in the platform
# List integration instances for organization
Source: https://docs.featherhq.com/api-reference/integrations/list-integration-instances-for-organization
get /api/v1/integrations/instances
List all integration instances configured for the organization
# Update an integration instance
Source: https://docs.featherhq.com/api-reference/integrations/update-an-integration-instance
patch /api/v1/integrations/{integrationInstanceId}
Update an integration instance for the organization
# Add file to collection
Source: https://docs.featherhq.com/api-reference/knowledge-base/add-file-to-collection
post /api/v1/knowledge-base/collection/{collectionId}/file/{fileId}
# Bulk add files to collection
Source: https://docs.featherhq.com/api-reference/knowledge-base/bulk-add-files-to-collection
post /api/v1/knowledge-base/collection/{collectionId}/files/bulk-add
Add multiple knowledge base files to a collection at once (max 100)
# Bulk delete knowledge base files
Source: https://docs.featherhq.com/api-reference/knowledge-base/bulk-delete-knowledge-base-files
post /api/v1/knowledge-base/files/bulk-delete
Delete multiple knowledge base files at once (max 100)
# Bulk remove files from collection
Source: https://docs.featherhq.com/api-reference/knowledge-base/bulk-remove-files-from-collection
post /api/v1/knowledge-base/collection/{collectionId}/files/bulk-remove
Remove multiple knowledge base files from a collection at once (max 100)
# Create knowledge base collection
Source: https://docs.featherhq.com/api-reference/knowledge-base/create-knowledge-base-collection
post /api/v1/knowledge-base/collection
# Create knowledge base file
Source: https://docs.featherhq.com/api-reference/knowledge-base/create-knowledge-base-file
post /api/v1/knowledge-base/file
# Delete knowledge base collection
Source: https://docs.featherhq.com/api-reference/knowledge-base/delete-knowledge-base-collection
delete /api/v1/knowledge-base/collection/{id}
# Delete knowledge base file
Source: https://docs.featherhq.com/api-reference/knowledge-base/delete-knowledge-base-file
delete /api/v1/knowledge-base/file/{id}
# Generate presigned URL for uploading a file
Source: https://docs.featherhq.com/api-reference/knowledge-base/generate-presigned-url-for-uploading-a-file
post /generate-presigned-url
Generate a pre-signed URL for uploading a file to S3
# Get knowledge base collections
Source: https://docs.featherhq.com/api-reference/knowledge-base/get-knowledge-base-collections
get /api/v1/knowledge-base/collections
# Get knowledge base files
Source: https://docs.featherhq.com/api-reference/knowledge-base/get-knowledge-base-files
get /api/v1/knowledge-base/files
# Remove file from collection
Source: https://docs.featherhq.com/api-reference/knowledge-base/remove-file-from-collection
delete /api/v1/knowledge-base/collection/{collectionId}/file/{fileId}/remove
# Update file status
Source: https://docs.featherhq.com/api-reference/knowledge-base/update-file-status
patch /api/v1/knowledge-base/file/{fileId}/status
# View knowledge base file
Source: https://docs.featherhq.com/api-reference/knowledge-base/view-knowledge-base-file
post /api/v1/knowledge-base/file/{fileId}/view
# Get current organization
Source: https://docs.featherhq.com/api-reference/organization/get-current-organization
get /api/v1/organization
# Update organization settings
Source: https://docs.featherhq.com/api-reference/organization/update-organization-settings
patch /api/v1/organization
# Connect Twilio account
Source: https://docs.featherhq.com/api-reference/phone-numbers/connect-twilio-account
post /api/v1/twilio/import
# Create inbound dispatch rule
Source: https://docs.featherhq.com/api-reference/phone-numbers/create-inbound-dispatch-rule
post /api/v1/phone-number/inbound/{id}/dispatch-rule
# Delete phone number
Source: https://docs.featherhq.com/api-reference/phone-numbers/delete-phone-number
delete /api/v1/phone-number/{id}
# Get phone number by E.164 format
Source: https://docs.featherhq.com/api-reference/phone-numbers/get-phone-number-by-e-164-format
get /api/v1/phone-number/lookup/{phoneNumber}
Get a phone number record by E.164 phone number (URL encoded, e.g., %2B14155551234)
# Link SMS agent to phone number
Source: https://docs.featherhq.com/api-reference/phone-numbers/link-sms-agent-to-phone-number
post /api/v1/phone-number/sms/{id}/link-agent
Link an SMS agent to a phone number for SMS conversations. Only one SMS agent can be linked to a phone number at a time.
# List organization phone numbers
Source: https://docs.featherhq.com/api-reference/phone-numbers/list-organization-phone-numbers
get /api/v1/phone-numbers
# Purchase a Twilio phone number
Source: https://docs.featherhq.com/api-reference/phone-numbers/purchase-a-twilio-phone-number
post /api/v1/twilio/purchase
Purchase a phone number from Twilio and add it to the organization. Requires sufficient phone_lines credits.
# Remove inbound dispatch rule
Source: https://docs.featherhq.com/api-reference/phone-numbers/remove-inbound-dispatch-rule
delete /api/v1/phone-number/inbound/{id}/dispatch-rule
# Search available Twilio phone numbers
Source: https://docs.featherhq.com/api-reference/phone-numbers/search-available-twilio-phone-numbers
get /api/v1/twilio/search
Search for available phone numbers from Twilio based on various criteria
# Unlink SMS agent from phone number
Source: https://docs.featherhq.com/api-reference/phone-numbers/unlink-sms-agent-from-phone-number
post /api/v1/phone-number/sms/{id}/unlink-agent
Remove the SMS agent link from a phone number
# Update outbound dispatch rules with bulk agent IDs
Source: https://docs.featherhq.com/api-reference/phone-numbers/update-outbound-dispatch-rules-with-bulk-agent-ids
put /api/v1/phone-number/outbound/{id}/dispatch-rule
# List all prompt personalities
Source: https://docs.featherhq.com/api-reference/prompts/list-all-prompt-personalities
get /api/v1/prompts/personalities
List all available prompt personalities
# Create a new report generation job
Source: https://docs.featherhq.com/api-reference/reports/create-a-new-report-generation-job
post /api/v1/reports
Creates a new report generation job for exporting AgentCalls data. The report is generated asynchronously.
# Get download URL for a report
Source: https://docs.featherhq.com/api-reference/reports/get-download-url-for-a-report
get /api/v1/reports/{reportId}/download
Get a presigned URL to download a completed report
# List generated reports
Source: https://docs.featherhq.com/api-reference/reports/list-generated-reports
get /api/v1/reports
List all reports for the organization with cursor-based pagination
# Disconnect Slack alerts integration
Source: https://docs.featherhq.com/api-reference/slack-alerts/disconnect-slack-alerts-integration
delete /api/v1/organization/slack
# Get Slack alerts connection status
Source: https://docs.featherhq.com/api-reference/slack-alerts/get-slack-alerts-connection-status
get /api/v1/organization/slack
# Get Slack OAuth connect URL
Source: https://docs.featherhq.com/api-reference/slack-alerts/get-slack-oauth-connect-url
get /api/v1/organization/slack/connect-url
# List available Slack channels for alerting
Source: https://docs.featherhq.com/api-reference/slack-alerts/list-available-slack-channels-for-alerting
get /api/v1/organization/slack/channels
# Set default Slack channel for tool failure alerts
Source: https://docs.featherhq.com/api-reference/slack-alerts/set-default-slack-channel-for-tool-failure-alerts
patch /api/v1/organization/slack/channel
# Slack OAuth callback
Source: https://docs.featherhq.com/api-reference/slack-alerts/slack-oauth-callback
get /api/v1/integrations/slack/callback
# Create a new squad
Source: https://docs.featherhq.com/api-reference/squad/create-a-new-squad
post /api/v1/squads
Create a new squad configuration with an entrypoint agent
# Create transfer rule
Source: https://docs.featherhq.com/api-reference/squad/create-transfer-rule
post /api/v1/squads/{squadId}/transfer-rules
Create a new transfer rule between two agents in a squad
# Delete squad
Source: https://docs.featherhq.com/api-reference/squad/delete-squad
delete /api/v1/squads/{squadId}
Soft delete squad by setting archived=true
# Delete transfer rule
Source: https://docs.featherhq.com/api-reference/squad/delete-transfer-rule
delete /api/v1/squads/{squadId}/transfer-rules/{ruleId}
Hard delete a transfer rule
# Dispatch squad
Source: https://docs.featherhq.com/api-reference/squad/dispatch-squad
post /api/v1/squads/{squadId}/dispatch
Create a new dispatch for a squad, resolving the entrypoint agent internally
# Get squad details
Source: https://docs.featherhq.com/api-reference/squad/get-squad-details
get /api/v1/squads/{squadId}
Get detailed squad configuration including entrypoint agent, transfer rules, phone numbers, member agents, and basic stats
# List all squads for an organization
Source: https://docs.featherhq.com/api-reference/squad/list-all-squads-for-an-organization
get /api/v1/squads
Get a paginated list of squads with transfer rule counts
# List transfer rules
Source: https://docs.featherhq.com/api-reference/squad/list-transfer-rules
get /api/v1/squads/{squadId}/transfer-rules
Get all transfer rules for a squad with optional filters
# Update squad
Source: https://docs.featherhq.com/api-reference/squad/update-squad
patch /api/v1/squads/{squadId}
Update squad name, description, entrypoint agent, or archived status
# Update transfer rule
Source: https://docs.featherhq.com/api-reference/squad/update-transfer-rule
patch /api/v1/squads/{squadId}/transfer-rules/{ruleId}
Update an existing transfer rule
# Create a Cekura mock tool
Source: https://docs.featherhq.com/api-reference/testing-lab/create-a-cekura-mock-tool
post /api/v1/testing-lab/mock-tools
# Create a Cekura test profile
Source: https://docs.featherhq.com/api-reference/testing-lab/create-a-cekura-test-profile
post /api/v1/testing-lab/test-profiles
# Delete a Cekura mock tool
Source: https://docs.featherhq.com/api-reference/testing-lab/delete-a-cekura-mock-tool
delete /api/v1/testing-lab/mock-tools/by-name/{toolName}
# Delete a Cekura test profile
Source: https://docs.featherhq.com/api-reference/testing-lab/delete-a-cekura-test-profile
delete /api/v1/testing-lab/test-profiles/{id}
# Delete testing lab scenario by ID
Source: https://docs.featherhq.com/api-reference/testing-lab/delete-testing-lab-scenario-by-id
delete /api/v1/testing-lab/scenarios/{id}
# Generate testing lab scenarios
Source: https://docs.featherhq.com/api-reference/testing-lab/generate-testing-lab-scenarios
post /api/v1/testing-lab/scenarios/generate
# Get aggregated metric scores over time for an agent
Source: https://docs.featherhq.com/api-reference/testing-lab/get-aggregated-metric-scores-over-time-for-an-agent
get /api/v1/testing-lab/analytics
# Get detail for a single observed call including per-metric scores
Source: https://docs.featherhq.com/api-reference/testing-lab/get-detail-for-a-single-observed-call-including-per-metric-scores
get /api/v1/testing-lab/calls/{agentCallId}
# Get observed call logs for an agent
Source: https://docs.featherhq.com/api-reference/testing-lab/get-observed-call-logs-for-an-agent
get /api/v1/testing-lab/calls
# Get one aggregated testing-lab result with nested runs
Source: https://docs.featherhq.com/api-reference/testing-lab/get-one-aggregated-testing-lab-result-with-nested-runs
get /api/v1/testing-lab/results/{resultId}
# Get testing lab scenario by ID
Source: https://docs.featherhq.com/api-reference/testing-lab/get-testing-lab-scenario-by-id
get /api/v1/testing-lab/scenarios/{id}
# Get testing lab scenarios
Source: https://docs.featherhq.com/api-reference/testing-lab/get-testing-lab-scenarios
get /api/v1/testing-lab/scenarios
# List aggregated testing-lab results (Cekura test_framework/v1/results)
Source: https://docs.featherhq.com/api-reference/testing-lab/list-aggregated-testing-lab-results-cekura-test-framework-v1-results
get /api/v1/testing-lab/results
# List Cekura mock tools for an agent
Source: https://docs.featherhq.com/api-reference/testing-lab/list-cekura-mock-tools-for-an-agent
get /api/v1/testing-lab/mock-tools
# List Cekura test profiles for an agent
Source: https://docs.featherhq.com/api-reference/testing-lab/list-cekura-test-profiles-for-an-agent
get /api/v1/testing-lab/test-profiles
# Run testing lab scenarios
Source: https://docs.featherhq.com/api-reference/testing-lab/run-testing-lab-scenarios
post /api/v1/testing-lab/scenarios/run
# Update a Cekura mock tool
Source: https://docs.featherhq.com/api-reference/testing-lab/update-a-cekura-mock-tool
patch /api/v1/testing-lab/mock-tools/by-name/{toolName}
# Update a Cekura test profile
Source: https://docs.featherhq.com/api-reference/testing-lab/update-a-cekura-test-profile
patch /api/v1/testing-lab/test-profiles/{id}
# Update testing lab scenario by ID
Source: https://docs.featherhq.com/api-reference/testing-lab/update-testing-lab-scenario-by-id
patch /api/v1/testing-lab/scenarios/{id}
# Close a thread
Source: https://docs.featherhq.com/api-reference/threads/close-an-sms-thread
patch /api/v1/threads/{threadId}/close
Close an active thread
# Create a new SMS thread
Source: https://docs.featherhq.com/api-reference/threads/create-a-new-sms-thread
post /api/v1/threads
Create a new SMS thread for text-based conversations
# Create a new web chat thread
Source: https://docs.featherhq.com/api-reference/threads/create-a-new-web-chat-thread
post /api/v1/threads/web
Create a new web chat thread for server-side integrations. Use X-API-Key or Clerk auth.
# Get a thread by ID
Source: https://docs.featherhq.com/api-reference/threads/get-an-sms-thread-by-id
get /api/v1/threads/{threadId}
Get details of a specific thread
# Get messages for a thread
Source: https://docs.featherhq.com/api-reference/threads/get-messages-for-an-sms-thread
get /api/v1/threads/{threadId}/messages
Get messages for a specific thread with cursor-based pagination
# List threads
Source: https://docs.featherhq.com/api-reference/threads/list-sms-threads
get /api/v1/threads
List threads with cursor-based pagination and optional filters
# Send a message to a web chat thread
Source: https://docs.featherhq.com/api-reference/threads/send-a-message-to-a-web-chat-thread
post /api/v1/threads/{threadId}/messages
Send an inbound user message to a web chat thread. Agent replies are delivered via SSE or polling.
# Stream new web chat thread messages
Source: https://docs.featherhq.com/api-reference/threads/stream-new-web-chat-thread-messages
get /api/v1/threads/{threadId}/stream
Server-Sent Events stream for new outbound agent messages on a web chat thread. Load history separately via GET /api/v1/threads/{threadId}/messages.
# Update thread metadata
Source: https://docs.featherhq.com/api-reference/threads/update-thread-metadata
patch /api/v1/threads/{threadId}
Merge metadata and/or variables on a thread
# Create new tool
Source: https://docs.featherhq.com/api-reference/tools/create-new-tool
post /api/v1/tools
Create a new tool
# Delete tool
Source: https://docs.featherhq.com/api-reference/tools/delete-tool
delete /api/v1/tools/{toolId}
Delete a tool by ID
# Get tool details
Source: https://docs.featherhq.com/api-reference/tools/get-tool-details
get /api/v1/tools/{toolId}
Get a tool by ID
# List custom tools
Source: https://docs.featherhq.com/api-reference/tools/list-custom-tools
get /api/v1/tools
List all tools with cursor-based pagination
# List pre-built tools
Source: https://docs.featherhq.com/api-reference/tools/list-pre-built-tools
get /api/v1/pre-built-tools
List all pre-built tools
# Update tool
Source: https://docs.featherhq.com/api-reference/tools/update-tool
patch /api/v1/tools/{toolId}
Update an existing tool
# Bulk create workflow executions
Source: https://docs.featherhq.com/api-reference/workflows/bulk-create-workflow-executions
post /api/v1/workflow/{workflowId}/execution/bulk
Create multiple agent workflow executions at once (max 25 leads)
# Cancel all workflow executions by phone number
Source: https://docs.featherhq.com/api-reference/workflows/cancel-all-workflow-executions-by-phone-number
post /api/v1/executions/cancel
Cancel all running agent workflow executions across all workflows for a given phone number. Returns the count of cancelled executions.
# Cancel workflow execution
Source: https://docs.featherhq.com/api-reference/workflows/cancel-workflow-execution
post /api/v1/workflow/{workflowId}/executions/{executionId}/cancel
Cancel an agent workflow execution
# Cancel workflow execution by lead ID
Source: https://docs.featherhq.com/api-reference/workflows/cancel-workflow-execution-by-lead-id
post /api/v1/workflow/{workflowId}/leads/{customerLeadId}/execution/cancel
Cancel an agent workflow execution using the customer lead ID
# Cancel workflow executions by phone number
Source: https://docs.featherhq.com/api-reference/workflows/cancel-workflow-executions-by-phone-number
post /api/v1/workflow/{workflowId}/executions/cancel
Cancel all running agent workflow executions for a given phone number. Returns the count of cancelled executions.
# Create agent workflow
Source: https://docs.featherhq.com/api-reference/workflows/create-agent-workflow
post /api/v1/workflow
Create a new agent workflow
# Create workflow execution
Source: https://docs.featherhq.com/api-reference/workflows/create-workflow-execution
post /api/v1/workflow/{workflowId}/execution
Create a new agent workflow execution
# Delete agent workflow
Source: https://docs.featherhq.com/api-reference/workflows/delete-agent-workflow
delete /api/v1/workflow/{id}
Delete an agent workflow
# Delete workflow execution
Source: https://docs.featherhq.com/api-reference/workflows/delete-workflow-execution
delete /api/v1/workflow/{workflowId}/execution/{executionId}
Delete an agent workflow execution
# Get agent workflow
Source: https://docs.featherhq.com/api-reference/workflows/get-agent-workflow
get /api/v1/workflow/{id}
Get an agent workflow by ID
# Get workflow execution
Source: https://docs.featherhq.com/api-reference/workflows/get-workflow-execution
get /api/v1/workflow/{workflowId}/execution/{executionId}
Get an agent workflow execution by ID
# List agent workflows
Source: https://docs.featherhq.com/api-reference/workflows/list-agent-workflows
get /api/v1/workflow
List agent workflows
# List workflow executions
Source: https://docs.featherhq.com/api-reference/workflows/list-workflow-executions
get /api/v1/workflow/{workflowId}/executions
List agent workflow executions
# List workflow executions by phone number
Source: https://docs.featherhq.com/api-reference/workflows/list-workflow-executions-by-phone-number
get /api/v1/workflow/{workflowId}/executions/by-phone
List all workflow executions for a given phone number within a workflow, including metadata and variables.
# Pause workflow execution
Source: https://docs.featherhq.com/api-reference/workflows/pause-workflow-execution
post /api/v1/workflow/{workflowId}/executions/{executionId}/pause
Pause an agent workflow execution
# Resume workflow execution
Source: https://docs.featherhq.com/api-reference/workflows/resume-workflow-execution
post /api/v1/workflow/{workflowId}/executions/{executionId}/resume
Resume an agent workflow execution
# Update agent workflow
Source: https://docs.featherhq.com/api-reference/workflows/update-agent-workflow
patch /api/v1/workflow/{id}
Update an agent workflow
# Update workflow execution
Source: https://docs.featherhq.com/api-reference/workflows/update-workflow-execution
put /api/v1/workflow/{workflowId}/execution/{executionId}
Update an agent workflow execution
# Agents
Source: https://docs.featherhq.com/documentation/core-concepts/agents
Agents are Feather's reusable conversation workers. Versions define behavior, models, prompts, tools, and channel-specific settings.
Agents are the center of the Feather platform. They define who the assistant is, what it can do, and how it behaves across conversations.
## Agent Model
Feather separates an agent into two layers:
* **Agent**: the stable identity for a use case such as support, qualification, reminders, or scheduling
* **Agent version**: the deployable snapshot that contains the prompt, tools, models, voice, and channel-specific settings
This model lets you iterate safely: build a new version, test it, then deploy it when ready.
## Agent Types
Feather supports two primary agent types:
* **CALL** for live voice conversations
* **TEXT** for SMS and message-first use cases
Text-capable agents can also power outbound email threads and web chat flows when the related channel settings are configured.
## What Lives on a Version
An agent version can include:
* Prompt instructions and variables
* Custom tools and pre-built tools
* Knowledge base collections
* Language, voice, STT, TTS, and LLM settings
* Call behavior such as voicemail handling, interruption tuning, and silence timeouts
* Message behavior such as SMS and email token limits or inactivity windows
## Prompt Design
Keep prompts operational, not aspirational. A good production prompt usually covers:
* The agent's job
* What information it must collect
* What tools it is allowed to use
* When to escalate, transfer, or stop
* Tone and response length
### Example Prompt Shape
```json theme={"system"}
{
"system": "You are a renewal specialist for Feather Labs. Confirm who you are speaking with, explain the reason for the conversation, answer contract questions, and offer the next step.",
"variables": [
{
"name": "accountName",
"required": false,
"defaultValue": "the account"
},
{
"name": "renewalDate",
"required": false
}
],
"tools": ["lookup_contract", "create_follow_up_task"],
"preBuiltTools": []
}
```
## Creating an Agent
This request creates a text-capable agent with prompt variables and message settings.
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/agents" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Renewals Assistant",
"description": "Handles proactive renewal outreach",
"agentType": "TEXT",
"useKnowledgeBase": true,
"prompt": {
"system": "You are a renewal specialist for Feather Labs. Be concise, confirm account context, and move the customer toward the next step.",
"variables": [
{
"name": "accountName",
"required": false
},
{
"name": "renewalDate",
"required": false
}
],
"tools": ["lookup_contract", "create_follow_up_task"],
"preBuiltTools": []
},
"voicemailMessage": null,
"overrideSTTConfig": null,
"sms": {
"inactivityTimeoutHours": 24,
"smsMaxTokens": 500,
"smsTemperature": 0.7
}
}'
```
## Deployments
Creating an agent gives you an initial version, but live traffic uses the version you deploy. Common pattern:
1. Create or update a version.
2. Run tests or internal QA.
3. Deploy that version.
4. Route phone numbers, workflows, or public entry points to the deployed version.
## When to Create a New Version
Create a new version when you change any of these:
* Prompt behavior
* Tools or tool permissions
* Knowledge base attachments
* Voice, model, or language settings
* Channel configuration such as email sender identity or silence tuning
## Related Concepts
See how agents are exposed over voice, SMS, email, and web chat.
Extend agent behavior with custom actions.
Ground answers in your own documents.
Browse the full agent management API.
# Calendars
Source: https://docs.featherhq.com/documentation/core-concepts/calendars
Calendars, schedules, event types, bookings, and external connections give Feather agents a native scheduling layer.
Calendars let Feather agents do more than suggest a next step. They can expose structured availability, create bookings, and connect to external calendars when needed.
## Calendar Building Blocks
* **Calendar**: the top-level scheduling container
* **Schedule**: when time is generally available
* **Event type**: the bookable meeting definition
* **Booking**: a scheduled appointment
* **Connection**: an external calendar account linked for sync
## Typical Setup Flow
1. Create a calendar
2. Add one or more schedules
3. Create event types
4. Optionally connect an external calendar
5. Query slots and create bookings from an agent or workflow
## Create a Calendar
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/calendars" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Sales team calendar",
"description": "Primary scheduling calendar for demos"
}'
```
## Create an Event Type
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/calendars/CALENDAR_ID/event-types" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "30-minute demo",
"slug": "demo-30",
"duration": 30,
"slotInterval": 30,
"minimumBookingNotice": 120,
"location": "Google Meet",
"addGoogleMeet": true
}'
```
## Create a Booking
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/calendar-bookings" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"calendarId": "CALENDAR_ID",
"eventTypeId": "EVENT_TYPE_ID",
"startTime": "2026-03-18T18:00:00Z",
"timezone": "America/New_York",
"title": "Renewal review",
"attendeeName": "Taylor Smith",
"attendeeEmail": "taylor@example.com",
"attendeePhone": "+14155550123",
"leadId": "contact-123"
}'
```
## When to Use Native Calendars
Native calendars are a good fit when you want:
* Agent-friendly booking APIs in the same platform
* Shared scheduling logic across voice and messaging channels
* Direct slot lookup and booking flows from workflows or tools
If you already run a separate scheduling stack, you can still use Feather tools or integrations to bridge into it.
## Related API Reference
Create and manage calendars.
Define bookable meeting types.
Create, cancel, and reschedule bookings.
Connect external calendar providers.
# Conversations
Source: https://docs.featherhq.com/documentation/core-concepts/calls
Feather supports voice calls, SMS threads, email threads, and web chat using a shared conversation model.
Feather is multi-channel by design. The same agent foundation can be exposed through live voice, SMS, email, or web chat depending on the use case.
## Shared Conversation Concepts
Every conversation surface can carry:
* An agent or agent version
* Contact context such as `leadId`
* Variables used inside prompts or tools
* Metadata for CRM or reporting use
* Conversation records you can review later
## Conversation Surfaces
Best for real-time qualification, support, intake, reminders, and transfers.
Best for short updates, follow-ups, opt-ins, confirmations, and workflow steps.
Best for longer follow-up, summaries, scheduling, and asynchronous outreach.
Best for embedded product or marketing site conversations.
## Voice Calls
Voice conversations can begin in two common ways:
* A user calls a number assigned to an inbound agent or squad
* You launch an outbound call with direct dispatch or a workflow step
### Direct Dispatch Example
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/agent/AGENT_ID/dispatch" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"versionId": "VERSION_ID",
"outboundPhoneNumberId": "PHONE_NUMBER_ID",
"leadId": "contact-123",
"firstName": "Avery",
"toPhoneNumber": "+14155550123",
"variables": {
"accountName": "Northwind Health"
},
"metadata": {
"campaign": "renewal-q2"
}
}'
```
## SMS Threads
SMS uses persistent threads rather than one-off messages. This is the right model for follow-up, reminders, re-engagement, and workflow-based text outreach.
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/threads" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agentVersionId": "TEXT_AGENT_VERSION_ID",
"toPhoneNumber": "+14155550123",
"fromPhoneNumber": "+14155550999",
"fromPhoneNumberId": "FROM_PHONE_NUMBER_ID",
"initialMessage": "Hi Taylor, this is Feather. I wanted to confirm whether tomorrow still works for your renewal review.",
"leadId": "contact-123",
"variables": {
"accountName": "Northwind Health"
}
}'
```
## Email Threads
Email threads are outbound-initiated conversations tied to a deployed version. The version should have a verified sending domain configured before you start sending.
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/email/threads" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agentVersionId": "TEXT_AGENT_VERSION_ID",
"toEmail": "taylor@example.com",
"subject": "Next steps for your renewal review",
"firstMessage": "Thanks for taking the call today. Here is a short summary and the next action we discussed.",
"leadId": "contact-123"
}'
```
## Web Chat
Web chat threads are created on demand and return a short-lived token for the client. Chat creation is protected by an allowlist of approved domains.
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/chat/threads" \
-H "Content-Type: application/json" \
-H "Origin: https://www.example.com" \
-d '{
"agentId": "WEB_CHAT_AGENT_ID"
}'
```
Use [Update organization settings](/api-reference/organization/update-organization-settings) to manage `allowedChatDomains`.
## Design Guidance
* Use voice when the conversation needs urgency, nuance, or live transfer.
* Use SMS when a short asynchronous reply is enough.
* Use email when responses are longer or need richer written context.
* Use web chat for product surfaces or public website entry points.
* Reuse variables and metadata consistently across channels so workflows and reporting stay clean.
## Related API Reference
Review completed call records.
Start and manage text threads.
Create and inspect email threads.
Launch web chat sessions.
# Configurations
Source: https://docs.featherhq.com/documentation/core-concepts/configurations
Configure the listening, reasoning, speaking, and messaging behavior that each Feather agent version uses.
Configurations determine how an agent listens, reasons, and responds. In Feather, most of these settings live on the agent version so you can tune behavior without creating a new agent identity.
## Main Configuration Areas
* **LLM** for reasoning and response generation
* **STT** for speech recognition on call agents
* **TTS and voice** for spoken output
* **Language** for locale-aware behavior
* **Turn-taking settings** such as interruption and silence controls
* **Message settings** such as SMS or email token limits on text-capable versions
## Start with Defaults, Then Tune
For most teams, the best rollout pattern is:
1. Start with known-good default configs
2. Validate the prompt and tools first
3. Tune voice or model settings only after the baseline works
## Inspect Available Configurations
```bash cURL theme={"system"}
curl "https://prod.featherhq.com/api/v1/available-voices" \
-H "X-API-Key: $FEATHER_API_KEY"
```
```bash cURL theme={"system"}
curl "https://prod.featherhq.com/api/v1/llm-configs" \
-H "X-API-Key: $FEATHER_API_KEY"
```
```bash cURL theme={"system"}
curl "https://prod.featherhq.com/api/v1/stt-configs" \
-H "X-API-Key: $FEATHER_API_KEY"
```
```bash cURL theme={"system"}
curl "https://prod.featherhq.com/api/v1/tts-configs" \
-H "X-API-Key: $FEATHER_API_KEY"
```
## What to Tune First
### Voice Agents
Prioritize:
* Voice selection
* Silence timeouts
* Interruption sensitivity
* Maximum call duration
### Text Agents
Prioritize:
* Response length
* Temperature
* Inactivity timeout
* Sender identity for email
## Example Version Settings
```json theme={"system"}
{
"llmConfigId": "YOUR_LLM_CONFIG_ID",
"sttConfigId": "YOUR_STT_CONFIG_ID",
"ttsConfigId": "YOUR_TTS_CONFIG_ID",
"voiceId": "YOUR_VOICE_ID",
"languageId": "en-US",
"voiceSpeed": 1.0,
"voiceVolume": 100,
"initialSilenceTimeout": 30000,
"finalSilenceTimeout": 10000,
"minInterruptionWords": 1,
"minInterruptionDuration": 1.0
}
```
## Configuration Advice
* Change one variable at a time when testing quality.
* Keep a stable production baseline for each major use case.
* Version changes to voice, prompt, and tools together when the customer experience depends on all three.
* Match tone and pacing to the job, not just brand preference.
## Related API Reference
List supported voices.
Review model configuration options.
See supported language options.
Apply configurations at the version level.
# Integrations
Source: https://docs.featherhq.com/documentation/core-concepts/integrations
Integrations connect Feather to external systems so agents can use authenticated, reusable business capabilities.
Integrations are managed connections to external services. They are the configuration layer that powers integration-backed tools and connected workflows.
## Integrations vs Tools
* **Integrations** store the connection to a service
* **Tools** are the actions an agent performs using that connection
For example, an integration might connect Feather to a scheduling platform, while the tool created from that integration checks availability or books time.
## Typical Uses
* CRM lookups and updates
* Scheduling and appointment systems
* Domain-specific systems of record
* Secure access to third-party APIs across multiple agents
## List Available Integrations
```bash theme={"system"}
curl "https://prod.featherhq.com/api/v1/integrations" \
-H "X-API-Key: $FEATHER_API_KEY"
```
## Integration Instances
An integration instance is your organization's configured connection for one service. You can have multiple instances when teams, environments, or business units need different credentials or behavior.
Common pattern:
1. Inspect the available integrations
2. Create an instance with the right credentials or settings
3. Enable or reference the resulting capability through tools or agent configuration
## Design Guidance
* Use integrations when the same external system should support multiple agents.
* Use a custom tool when the action is unique to your own backend and does not need a reusable connection model.
* Keep external side effects in integrations or tools, not inside prompts.
## Adjacent Features
Some connected capabilities live in dedicated APIs rather than the generic integrations API, including:
* [Calendar connections](/api-reference/calendar-connections/get-oauth-url-for-external-calendar)
* [Email domains](/api-reference/email-domains/create-an-email-domain)
## Related API Reference
See the catalog of supported integration types.
Create and manage organization-specific integration instances.
Expose connected capabilities to agents through tools.
Use calendar-specific connections and booking flows.
# Knowledge Base
Source: https://docs.featherhq.com/documentation/core-concepts/knowledge-base
Knowledge base collections let Feather agents answer from your documents instead of relying only on prompt instructions.
Use the knowledge base when your agents need accurate, current answers from your own content such as product docs, support articles, policy material, scripts, or internal references.
## How It Works
Feather organizes knowledge in two layers:
* **Files**: the uploaded source documents
* **Collections**: reusable groups of files
You attach collections to agent versions so different agents can use different document sets.
## Typical Setup Flow
1. Create a collection
2. Request an upload URL for a file
3. Upload the file to that URL
4. Add the file to one or more collections
5. Attach the collection to the agent version you want to ground
## Create a Collection
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/knowledge-base/collection" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Product Support",
"description": "Support articles, setup guides, and troubleshooting notes"
}'
```
## Request an Upload URL
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/generate-presigned-url" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fileName": "billing-faq.pdf"
}'
```
After the file is uploaded, use the collection APIs to attach it to the right collection.
## Good Knowledge Base Content
Knowledge base works best with content that is:
* Written clearly and factually
* Divided by topic
* Updated regularly
* Focused on user-facing answers
Avoid uploading noisy exports, duplicate files, or content that should only live behind a live API tool.
## When to Use Knowledge Base vs Tools
* Use **knowledge base** for explanations, policy answers, and static reference material.
* Use **tools** for live account data, actions, and system-of-record updates.
For example, a support agent might use knowledge base to explain a refund policy and a tool to check the status of a specific refund.
## Best Practices
* Create collections by domain, not by every individual team member.
* Keep marketing, support, and policy content in separate collections when the agents have different jobs.
* Re-attach collections at the version level so changes can be tested before deployment.
* Remove stale content instead of relying on prompt instructions to override it.
## Related API Reference
Follow the safe replacement workflow for stale files and collections.
Manage knowledge collections.
Track uploaded files and file status.
Request upload URLs for new files.
Attach collections to deployed agent versions.
# Phone Numbers
Source: https://docs.featherhq.com/documentation/core-concepts/phone-numbers
Phone numbers connect Feather agents to voice and SMS channels for inbound traffic, outbound calls, and thread-based messaging.
Phone numbers are the public entry points for live calling and SMS. They decide where inbound traffic lands and which identity outbound traffic uses.
## Number Roles
* **Inbound voice numbers** receive live calls into an agent or squad
* **Outbound voice numbers** are used when Feather places calls
* **SMS-linked numbers** are attached to text-capable agents for thread creation
* **Bridging numbers** are available for advanced call routing and transfer flows
## Common Setup Patterns
### Inbound Support Line
Assign one number to an agent or squad so callers land in a stable entry point.
### Outbound Campaign Pool
Provision one or more outbound numbers and let calls or workflows use them for caller identity.
### Dedicated SMS Number
Link a number to a text agent so the thread experience stays consistent for the recipient.
## Typical Setup Order
1. Connect or import a Twilio-backed number into Feather
2. Decide whether the number is for inbound, outbound, SMS, or a squad entry point
3. Test direct dispatch or a thread creation flow
4. Add workflows, routing, or transfers once the base path works
## List Existing Numbers
```bash theme={"system"}
curl "https://prod.featherhq.com/api/v1/phone-numbers" \
-H "X-API-Key: $FEATHER_API_KEY"
```
## Things to Plan For
* Which number should represent each brand or team
* Whether inbound calls should land on one agent or a squad
* Whether SMS should use the same number as voice or a dedicated thread identity
* Which outbound numbers should be available to workflows
## Related Capabilities
* Use [Dispatch](/api-reference/dispatch/dispatch-audio-agent) for one-off outbound calls
* Use [SMS Threads](/api-reference/sms-threads/create-a-new-sms-thread) for text conversations
* Use [Squads](/documentation/core-concepts/squads) when one number should route across multiple specialists
## Related API Reference
List and manage phone numbers.
Search available numbers before purchase.
Attach a text agent to a number.
Manage bridging numbers for advanced routing.
# Squads
Source: https://docs.featherhq.com/documentation/core-concepts/squads
Squads let you route a single live call across multiple specialized voice agents.
A squad is a voice-only routing layer for multi-agent experiences. One entrypoint agent starts the conversation, then transfer rules determine when the call should move to a different specialist.
## When to Use a Squad
Use a squad when one conversation may need multiple specialists, such as:
* Front desk to billing to scheduling
* Qualification to closer
* General support to product-specific experts
If one agent can handle the full conversation alone, keep the design simpler and skip squads.
## Squad Model
* **Entrypoint agent**: the first voice agent that answers the conversation
* **Transfer rules**: routing rules that define which agent can hand off to which other agent
Only call agents belong in squads.
## Create a Squad
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/squads" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Patient access squad",
"description": "Routes calls between front desk, billing, and scheduling",
"entrypointAgentId": "ENTRYPOINT_CALL_AGENT_ID"
}'
```
## Add a Transfer Rule
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/squads/SQUAD_ID/transfer-rules" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fromAgentId": "ENTRYPOINT_CALL_AGENT_ID",
"toAgentId": "SCHEDULING_AGENT_ID",
"allowManualTrigger": true,
"toolDescription": "Transfer the call to the scheduling specialist when the caller is ready to book.",
"variables": [
{
"name": "appointmentType",
"description": "Requested appointment type",
"required": false
}
],
"speakBeforeTransfer": "I am connecting you to our scheduling specialist now."
}'
```
## Best Practices
* Give each squad member a distinct job.
* Keep transfer descriptions short and operational.
* Pass only the variables the receiving agent needs.
* Start with a small routing graph before building a large specialist network.
## Related Concepts
Use a squad as the inbound destination for a phone number.
Design specialized voice agents for each handoff.
Manage squads and transfer rules.
Launch a routed conversation directly.
# Testing Lab
Source: https://docs.featherhq.com/documentation/core-concepts/testing-lab
Testing Lab helps you generate scenarios, run repeatable evaluations, and compare agent behavior before deployment.
Testing Lab is Feather's structured environment for validating agent behavior before you send real traffic to a new version.
## What It Helps You Catch
* Prompt regressions
* Weak objection handling
* Missing tool coverage
* Broken booking or transfer paths
* Inconsistent qualification behavior
## Core Objects
* **Scenario**: the test case
* **Run**: one execution over one or more scenarios
* **Expected outcome**: the condition you want the agent to satisfy
## Generate Scenarios
Use generated scenarios when you want a wide spread of realistic tests from a short brief.
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/testing-lab/scenarios/generate" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": 123,
"num_scenarios": 5,
"inbound_phone_number": 456,
"first_message": "Hi, I wanted to learn more about your pricing.",
"extra_instructions": "Include one confused prospect, one price-sensitive prospect, and one customer asking for a callback.",
"generate_expected_outcomes": true,
"tags": ["release-candidate"]
}'
```
## Run Scenarios
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/testing-lab/scenarios/run" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": 123,
"scenarios": [1001, 1002, 1003],
"frequency": 1,
"name": "RC1 voice validation",
"outbound_phone_number": "+14155550999",
"tags": ["release-candidate"]
}'
```
## Suggested Testing Process
1. Generate or hand-author scenarios for the core jobs the agent must complete.
2. Include edge cases, objections, and failure paths.
3. Run the candidate version.
4. Fix prompts, tools, or settings.
5. Re-run before deployment.
## What Good Scenarios Look Like
Good scenarios are:
* Specific about the caller or sender goal
* Focused on one main success condition
* Diverse in tone and objections
* Tagged so release candidates can be compared over time
## Related Guides
Validate each new version before deployment.
Test the agents used in automated outreach.
Generate, inspect, and run scenarios.
Review live production results after launch.
# Tools
Source: https://docs.featherhq.com/documentation/core-concepts/tools
Tools let Feather agents read data and take actions in your own systems or connected services.
Tools are how an agent moves beyond conversation into action. A tool can look up account data, create a task, schedule an appointment, update a CRM record, or trigger a downstream workflow.
## Tool Categories
* **Custom tools**: HTTP requests you define
* **Pre-built tools**: ready-made Feather capabilities exposed to agents
* **Integration-backed tools**: actions unlocked after connecting a supported integration
## When to Use a Tool
Use a tool when the agent needs trusted data or a side effect, for example:
* Look up an order or policy
* Create or update a CRM record
* Trigger internal follow-up work
* Book or confirm an appointment
* Hand off to another workflow or human team
## Custom Tool Example
This tool creates a follow-up task in an external system.
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/tools" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Create follow-up task",
"slug": "create_follow_up_task",
"description": "Create a follow-up task in the CRM after a customer conversation.",
"speech": "I am creating the follow-up now.",
"structure": {
"url": "https://api.example.com/tasks",
"method": "POST",
"headers": [
{
"key": "Authorization",
"value": "Bearer YOUR_BACKEND_TOKEN",
"secure": true
},
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"title": "{{task_title}}",
"ownerId": "{{owner_id}}",
"customerId": "{{customer_id}}",
"notes": "{{notes}}"
},
"timeout": 30,
"variables": [
{
"name": "task_title",
"type": "str",
"description": "Short action-oriented task title",
"required": true
},
{
"name": "owner_id",
"type": "str",
"description": "CRM owner identifier",
"required": true
},
{
"name": "customer_id",
"type": "str",
"description": "Customer identifier in the CRM",
"required": true
},
{
"name": "notes",
"type": "str",
"description": "Freeform notes about the follow-up",
"required": false
}
]
}
}'
```
## Prompting for Tool Use
Describe tools in the prompt in terms of intent, not implementation. Good prompts tell the agent:
* When the tool should be used
* Which facts must be confirmed first
* What success looks like
* When the agent must avoid using the tool
## Tool Design Guidelines
* Keep tools narrow and outcome-focused.
* Require only the inputs the agent can reliably collect.
* Return structured, human-readable results.
* Hide credentials in secure headers instead of prompt text.
* Make side effects idempotent where possible.
## Tools and Knowledge Base
Tools and knowledge base solve different problems:
* Use **knowledge base** for grounded answers from documents.
* Use **tools** for live data retrieval and actions.
Most production agents use both.
## Related API Reference
Create and manage custom tools.
Inspect the tools Feather exposes directly.
Learn how connected services can power tools.
Pair tools with grounded document retrieval.
# Workflows
Source: https://docs.featherhq.com/documentation/core-concepts/workflows
Workflows automate multi-step call and text outreach with reusable definitions, schedules, and per-contact executions.
Workflows let you orchestrate outreach over time instead of sending a single call or message. They are useful for sequences like qualification, collections, reminders, re-engagement, and follow-up.
## Workflow Model
* A **workflow** is the reusable template.
* An **execution** is one run of that workflow for one contact.
This means you can define a sequence once and run it for many contacts with different variables and metadata.
## What a Workflow Can Do
* Mix call and text steps
* Delay between steps
* Stop early based on outcomes
* Respect schedule windows
* Launch one execution or many in bulk
## Scheduling
Feather supports two layers of timing:
* **Workflow schedule**: when the workflow itself is allowed to run in its configured timezone
* **TCPA schedule**: when contact attempts are allowed in the recipient's local timezone
Use workflow schedule for business operations. Use TCPA schedule for compliance controls.
## Example Workflow Definition
This example calls first, then sends a text follow-up if the workflow is still active.
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/workflow" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Two-step follow-up",
"description": "One call and one text reminder",
"active": true,
"timezone": "America/New_York",
"workflowSchedule": {
"monday": {
"enabled": true,
"timeRanges": [
{ "startHour": 9, "startMinute": 0, "endHour": 17, "endMinute": 0 }
]
},
"tuesday": {
"enabled": true,
"timeRanges": [
{ "startHour": 9, "startMinute": 0, "endHour": 17, "endMinute": 0 }
]
}
},
"definition": {
"steps": [
{
"type": "CALL",
"order": 1,
"delayInSecs": 0,
"agentId": "CALL_AGENT_ID",
"leaveVoicemail": true,
"finishOn": ["CALENDLY", "NOT_INTERESTED", "DNC"]
},
{
"type": "TEXT",
"order": 2,
"delayInSecs": 86400,
"agentId": "TEXT_AGENT_ID",
"initialMessage": "Hi {{firstName}}, following up on our earlier outreach. Let me know if you want to reconnect.",
"finishOn": ["DNC"]
}
]
}
}'
```
## Starting an Execution
Executions carry the contact record for one run.
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/workflow/WORKFLOW_ID/execution" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"customerLeadId": "contact-123",
"primaryPhone": "+14155550123",
"zipcode": "94107",
"variables": {
"firstName": "Taylor"
},
"metadata": {
"firstName": "Taylor",
"campaign": "renewal-q2"
},
"priorityDate": "2026-03-12T10:00:00Z"
}'
```
## Common Controls
You can manage executions after creation:
* List active or historical runs
* Pause and resume
* Cancel a single execution
* Cancel by lead ID
* Cancel by phone number
* Bulk create up to a batch of contacts
## Best Practices
* Keep each workflow focused on one business goal.
* Use variables for contact-specific content instead of duplicating workflows.
* Separate channel logic by step type instead of overloading one prompt.
* Use finish conditions aggressively to avoid unnecessary follow-up.
* Test new versions before attaching them to large workflows.
## Related Guides
Choose the right agent for each step.
Configure the numbers workflows call from.
Browse workflow creation and execution endpoints.
Test agent behavior before attaching it to automation.
# Authentication
Source: https://docs.featherhq.com/documentation/getting-started/authentication
Authenticate Feather API requests with an organization API key.
Feather uses organization-scoped API keys for server-to-server requests. Send your key in the `X-API-Key` header on every authenticated API call.
## Get an API Key
1. Open the Feather dashboard.
2. Go to your organization settings.
3. Create an API key for the integration or environment you are setting up.
4. Store it in your secret manager or deployment platform.
Treat Feather API keys like production credentials. Store them in environment variables or a secrets manager, never in client-side code.
## Send Your First Authenticated Request
```bash cURL theme={"system"}
curl "https://prod.featherhq.com/api/v1/organization" \
-H "X-API-Key: $FEATHER_API_KEY"
```
```javascript JavaScript theme={"system"}
const response = await fetch("https://prod.featherhq.com/api/v1/organization", {
headers: {
"X-API-Key": process.env.FEATHER_API_KEY,
},
});
const data = await response.json();
console.log(data);
```
```python Python theme={"system"}
import os
import requests
response = requests.get(
"https://prod.featherhq.com/api/v1/organization",
headers={"X-API-Key": os.environ["FEATHER_API_KEY"]},
timeout=30,
)
print(response.json())
```
## Header Format
Use this exact header:
```http theme={"system"}
X-API-Key: your_api_key_here
```
You do not need to prefix the value with `Bearer`.
## Best Practices
* Create different keys for local development, staging, and production.
* Rotate keys when ownership changes or exposure is suspected.
* Keep keys in backend services only.
* Log request IDs and response codes, not secrets.
## What Uses API Keys?
API keys cover the main management and automation APIs, including:
* Agents and deployments
* Direct dispatch and workflows
* Phone number setup
* SMS, email, and chat thread creation
* Tools, knowledge base, calendars, and reports
Some public-facing flows such as shared sessions or web chat use short-lived tokens generated by Feather after your authenticated setup request.
## Next Steps
Create and launch your first agent.
Create an agent through the API.
# Introduction
Source: https://docs.featherhq.com/documentation/getting-started/overview
Feather is an AI conversation platform for voice calls, SMS, email, web chat, routing, scheduling, and workflow automation.
Feather helps you build AI-driven customer conversations across voice and messaging channels from one platform. A single agent model powers live calls, SMS threads, email conversations, web chat, workflow-driven outreach, and handoffs between specialized agents.
## What You Can Build
Handle inbound calls, launch outbound calls, transfer conversations, and capture call outcomes.
Run SMS, email, and web chat conversations with the same prompt, tools, and variables model.
Orchestrate multi-step call and text workflows with scheduling, throttling, and execution controls.
Route calls through squads, connect calendars, and let agents schedule appointments in flow.
## Core Building Blocks
### Agents and Versions
An **agent** is the long-lived identity for a use case such as support, sales, intake, or reminders. An **agent version** is the deployable configuration for that agent: prompt, tools, model settings, voice, language, and channel behavior.
### Conversations
Feather supports four main conversation surfaces:
* Voice calls
* SMS threads
* Email threads
* Web chat threads
Each surface can use shared variables, metadata, tools, and knowledge sources.
### Workflows
Workflows let you automate outreach over time. A workflow defines the sequence. Each execution runs that sequence for one lead or contact.
### Tools and Knowledge
Tools let an agent read or write data in external systems. Knowledge base collections let an agent ground answers in your documents and internal content.
## Recommended Build Order
1. Create an agent for the job you want to automate.
2. Add tools, prompt variables, and optional knowledge base collections.
3. Configure phone numbers, email sending, chat domains, or calendars for the channel you need.
4. Deploy the agent version you want to expose to live traffic.
5. Test the behavior in Testing Lab before scaling through workflows or public entry points.
## Start Here
Create, deploy, and dispatch your first agent.
Send authenticated API requests with `X-API-Key`.
Understand agent types, versions, prompts, and deployment.
Learn how voice, SMS, email, and chat fit together.
## API Reference
When you are ready for endpoint-level detail, start with:
* [Agents API](/api-reference/agents/list-all-agents)
* [Workflows API](/api-reference/workflows/create-agent-workflow)
* [Phone Numbers API](/api-reference/phone-numbers/list-organization-phone-numbers)
* [Calendars API](/api-reference/calendars/create-a-calendar)
# Quickstart
Source: https://docs.featherhq.com/documentation/getting-started/quickstart
Create a call agent, deploy it, and place a live test conversation.
This quickstart walks through the smallest useful Feather flow:
1. Create an agent
2. Deploy its first version
3. Dispatch a live outbound call
## Prerequisites
* A Feather account and API key
* At least one configured STT config, TTS config, LLM config, and voice
* An outbound phone number configured in your Feather organization
## Step 1: Create an Agent
This example creates a voice agent with a prompt, default model selections, and no knowledge base yet.
```bash cURL theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/agents" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Demo Calling Agent",
"description": "Qualifies and routes inbound or outbound conversations",
"agentType": "CALL",
"useKnowledgeBase": false,
"prompt": {
"system": "You are a concise and helpful assistant for Feather Labs. Introduce yourself clearly, answer questions directly, and capture the next step.",
"variables": [
{
"name": "company",
"required": false,
"defaultValue": "Feather Labs"
}
],
"tools": [],
"preBuiltTools": []
},
"voicemailMessage": null,
"overrideSTTConfig": null,
"sttConfigId": "YOUR_STT_CONFIG_ID",
"ttsConfigId": "YOUR_TTS_CONFIG_ID",
"llmConfigId": "YOUR_LLM_CONFIG_ID",
"voiceId": "YOUR_VOICE_ID"
}'
```
```javascript JavaScript theme={"system"}
const response = await fetch("https://prod.featherhq.com/api/v1/agents", {
method: "POST",
headers: {
"X-API-Key": process.env.FEATHER_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Demo Calling Agent",
description: "Qualifies and routes inbound or outbound conversations",
agentType: "CALL",
useKnowledgeBase: false,
prompt: {
system:
"You are a concise and helpful assistant for Feather Labs. Introduce yourself clearly, answer questions directly, and capture the next step.",
variables: [
{
name: "company",
required: false,
defaultValue: "Feather Labs",
},
],
tools: [],
preBuiltTools: [],
},
voicemailMessage: null,
overrideSTTConfig: null,
sttConfigId: "YOUR_STT_CONFIG_ID",
ttsConfigId: "YOUR_TTS_CONFIG_ID",
llmConfigId: "YOUR_LLM_CONFIG_ID",
voiceId: "YOUR_VOICE_ID",
}),
});
const { agent } = await response.json();
console.log("Agent ID:", agent.id);
console.log("Version ID:", agent.version.id);
```
Save the returned `agent.id` and `agent.version.id`.
## Step 2: Deploy the Version
Only deployed versions handle live traffic.
```bash theme={"system"}
curl -X PATCH "https://prod.featherhq.com/api/v1/agents/AGENT_ID/versions/VERSION_ID/deploy" \
-H "X-API-Key: $FEATHER_API_KEY"
```
## Step 3: Dispatch a Test Call
Use direct dispatch to place a single outbound call without creating a workflow.
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/agent/AGENT_ID/dispatch" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"versionId": "VERSION_ID",
"outboundPhoneNumberId": "OUTBOUND_PHONE_NUMBER_ID",
"leadId": "contact-123",
"firstName": "Taylor",
"toPhoneNumber": "+14155550123",
"metadata": {
"source": "quickstart"
},
"variables": {
"company": "Feather Labs"
}
}'
```
## Step 4: Inspect the Conversation
After the call completes, you can review:
* [Call records](/api-reference/calls/list-all-calls)
* [Agent deployments](/api-reference/agents/list-agent-deployments)
* [Configuration options](/documentation/core-concepts/configurations)
## Next Steps
Once the basic call flow works, expand into one of these:
Start text conversations from deployed text agents.
Automate call and text sequences over time.
Ground answers in your own documents.
Let agents find availability and book meetings.
# Updating a Knowledge File
Source: https://docs.featherhq.com/documentation/guides/updating-knowledge-base
Use this workflow to replace stale knowledge content, validate the new file, and roll it into the right collection safely.
When knowledge content changes, treat the update as a controlled replacement. Upload the new file, add it to the target collection, confirm it is ready, then remove the stale file.
This avoids breaking live agents while the new content is still being processed.
Feather accepts knowledge files in `.pdf` and `.md` format. For safe replacements, use a distinct versioned filename such as `refund-policy-2026-03.pdf` instead of reusing the old filename.
## What You Are Updating
There are two common cases:
* **File refresh**: a policy, FAQ, script, or reference doc changed, but the collection should stay the same.
* **Collection change**: the grouping itself needs to change, such as splitting one collection into multiple domains.
For a file refresh, keep the same collection and replace the file membership. For a larger reorganization, create a new collection and switch agents over after validation.
## Step 1: Inspect the Current State
Start by identifying:
* the collection you want to update
* the current file or files that should be replaced
* any agent versions that rely on that collection
```bash theme={"system"}
curl -X GET "https://prod.featherhq.com/api/v1/knowledge-base/collections" \
-H "X-API-Key: $FEATHER_API_KEY"
```
If you need a flat inventory of files and statuses, list files as well:
```bash theme={"system"}
curl -X GET "https://prod.featherhq.com/api/v1/knowledge-base/files" \
-H "X-API-Key: $FEATHER_API_KEY"
```
## Step 2: Request an Upload URL for the New File
Generate an upload URL for the replacement document. This returns both a temporary upload URL and a `fileId` for that upload target.
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/generate-presigned-url" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fileName": "{updated-file-name}.pdf"
}'
```
Then upload the file contents to the returned URL before you create the knowledge file record.
```bash theme={"system"}
curl -X PUT "{uploadUrl}" \
-H "Content-Type: application/pdf" \
--upload-file "./{updated-file-name}.pdf"
```
If you are uploading markdown, change the content type to `text/markdown`.
## Step 3: Create the New Knowledge File Record
Use the `fileId` from the previous step to create the knowledge file entry after the upload has completed. Add `prompt` only when you want retrieval instructions scoped to that file.
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/knowledge-base/file" \
-H "X-API-Key: $FEATHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fileId": "{newFileId}",
"prompt": "Use this file for refund policy questions and customer eligibility details."
}'
```
## Step 4: Wait for the New File to Be Ready
Do not remove the old file yet. First confirm the replacement file appears in the file list and reaches `INGESTED`.
```bash theme={"system"}
curl -X GET "https://prod.featherhq.com/api/v1/knowledge-base/files" \
-H "X-API-Key: $FEATHER_API_KEY"
```
Look for the new file and confirm its status is `INGESTED`. If you want to verify the stored file directly, request a view URL:
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/knowledge-base/file/{newFileId}/view" \
-H "X-API-Key: $FEATHER_API_KEY"
```
## Step 5: Add the New File to the Existing Collection
Once the file is ready, attach it to the collection that your agents already use.
```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/knowledge-base/collection/{collectionId}/file/{newFileId}" \
-H "X-API-Key: $FEATHER_API_KEY"
```
At this point, the collection contains both the old and new file. That overlap is useful while you validate the update.
## Step 6: Validate Before Cleanup
Before removing the old file:
1. confirm the collection now includes the new file
2. test the affected agent version with representative questions
3. verify the agent answers from the updated content
If the collection is attached to a production agent, validate on a draft or candidate version first when possible.
## Step 7: Remove the Stale File From the Collection
After validation, remove the outdated file from the collection.
```bash theme={"system"}
curl -X DELETE "https://prod.featherhq.com/api/v1/knowledge-base/collection/{collectionId}/file/{oldFileId}/remove" \
-H "X-API-Key: $FEATHER_API_KEY"
```
This is the step that actually updates the collection membership.
## Step 8: Delete the Old File Record
If the old file is no longer needed anywhere else, delete it to keep the workspace clean.
```bash theme={"system"}
curl -X DELETE "https://prod.featherhq.com/api/v1/knowledge-base/file/{oldFileId}" \
-H "X-API-Key: $FEATHER_API_KEY"
```
Only do this after confirming the file is not still referenced by another collection.
## Updating the Collection Structure
If the collection itself needs to change, use this sequence:
1. create a new collection
2. upload and attach the correct file set
3. move the relevant agent version to the new collection
4. test the new setup
5. retire the old collection
There is no separate "edit collection contents" endpoint beyond adding and removing files, so larger reorganizations are cleaner when treated as a new collection rollout.
## Recommended Operating Pattern
* Use clear file names with dates or version markers.
* Do not reuse the exact same filename when you want a staged replacement.
* Replace content by adding the new file before removing the old one.
* Keep collections organized by domain, not by one-off uploads.
* Test agent answers after every material content change.
* Delete stale files only after you have confirmed they are unused.
## Related Pages
Learn how collections and files fit into agent grounding.
Attach validated collections to the right agent version.
Inspect collections and file membership.
Track file status and cleanup stale entries.