Sync Tools

Fetches all tools from the Ultravox API for the authenticated agency and synchronizes them into the local agency_tools database table. New tools are inserted, existing tools are updated, and tools that no longer exist in Ultravox are marked as inactive.

Endpoint

Property	Value
Function Name	tools-sync
HTTP Method	POST
Authentication	Supabase JWT (Bearer token)
Required Role	agency_owner

Request

Headers

Authorization: Bearer <supabase_jwt_token>
Content-Type: application/json

Body

No request body is required.

Response

Success (200)

{
  "success": true,
  "message": "Synced 15 tools from Ultravox",
  "stats": {
    "total_in_ultravox": 15,
    "created": 5,
    "updated": 10,
    "errors": 0,
    "orphaned": 2
  }
}

Field	Description
total_in_ultravox	Total number of tools found in the Ultravox account
created	Number of new tools inserted into the local database
updated	Number of existing tools updated with fresh data
errors	Number of tools that failed to sync (logged server-side)
orphaned	Number of local tools that no longer exist in Ultravox (marked inactive)

Error Responses

Status	Condition
400	Ultravox API key not configured for the agency
401	Missing or invalid authorization header
403	User is not an agency user or is not an agency_owner
405	HTTP method is not POST
500	Failed to retrieve API credentials
502	Ultravox API returned an error during tool fetch

Behavior

• Authenticates the user via Supabase JWT and verifies they have the agency_owner role
• Retrieves the agency's Ultravox API key via the get_agency_credentials RPC function
• Fetches all tools from Ultravox with pagination via GET https://api.ultravox.ai/api/tools?limit=100, following next links until all pages are retrieved
• For each tool returned by Ultravox:
  • Determines the tool type from the definition (http, client, dataConnection, staticResponse, or unknown)
  • If the tool already exists locally (matched by ultravox_tool_id), updates it
  • If the tool is new, inserts it with extracted fields: name, description, tool_type, ownership, definition, http_base_url, http_method, dynamic_parameters, static_parameters, and timestamps
• After processing all Ultravox tools, identifies orphaned local tools (tools in the database whose ultravox_tool_id no longer appears in the Ultravox response) and marks them as is_active: false with a sync error message
• Returns aggregate statistics about the sync operation

Database Tables Read/Written

Table	Operation	Purpose
users	Read	Verify user role and agency membership
agency_tools	Read	Fetch existing tools to determine insert vs. update
agency_tools	Write (insert)	Create new tool records
agency_tools	Write (update)	Update existing tools and mark orphaned tools inactive

RPC Functions Called

Function	Purpose
get_agency_credentials	Retrieve Ultravox API key

External APIs Called

API	Method	Endpoint	Purpose
Ultravox	GET	/api/tools?limit=100	Fetch all tools (paginated)

Related Functions

• List Tools -- View the locally cached tools after syncing
• Get Tool -- Retrieve or refresh a single tool