Get Tool

Returns a single tool record by its local database ID or its Ultravox tool ID. Optionally fetches fresh data from the Ultravox API and updates the local record before returning it.

Endpoint

Property	Value
Function Name	tools-get
HTTP Method	GET
Authentication	Supabase JWT (Bearer token)
Required Role	Any authenticated agency user

Request

Headers

Authorization: Bearer <supabase_jwt_token>

Query Parameters

Field	Type	Required	Description
tool_id	string	One of tool_id or id is required	Ultravox tool ID
id	string	One of tool_id or id is required	Local database UUID
refresh	string	No	If "true", fetches fresh data from Ultravox and updates the local record

Response

Success (200)

{
  "tool": {
    "id": "local-uuid",
    "ultravox_tool_id": "ultravox-tool-uuid",
    "name": "my-tool",
    "description": "Tool description",
    "tool_type": "http",
    "ownership": "user",
    "definition": { },
    "http_base_url": "https://api.example.com/endpoint",
    "http_method": "POST",
    "dynamic_parameters": [],
    "static_parameters": [],
    "is_active": true,
    "managed_by_virsyn": false,
    "last_synced_at": "2025-01-15T12:00:00Z",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-15T12:00:00Z"
  },
  "refreshed": false
}

When refresh=true is used and the Ultravox fetch succeeds, refreshed will be true and the tool data reflects the latest state from Ultravox.

Error Responses

Status	Condition
400	Neither tool_id nor id was provided
401	Missing or invalid authorization header
403	User is not an agency user
404	Tool not found (or does not belong to the user's agency)
405	HTTP method is not GET
500	Internal server error

Behavior

• Authenticates the user via Supabase JWT and verifies they belong to an agency
• Requires at least one identifier: tool_id (Ultravox tool ID) or id (local database UUID)
• Queries the agency_tools table scoped to the user's agency_id
• If refresh=true:
  • Retrieves the agency's Ultravox API key via the get_agency_credentials RPC function
  • Fetches the tool from Ultravox via GET https://api.ultravox.ai/api/tools/{ultravox_tool_id}
  • Updates the local record with fresh name, description, ownership, definition, http_base_url, http_method, dynamic_parameters, static_parameters, and last_synced_at
  • Clears any previous sync_error
  • If the Ultravox fetch fails, falls back to the cached local data silently
• Returns the tool record with a refreshed boolean indicating whether live data was fetched

Database Tables Read/Written

Table	Operation	Purpose
users	Read	Resolve agency membership
agency_tools	Read	Fetch the tool record
agency_tools	Write	Update with refreshed data from Ultravox (when refresh=true)

RPC Functions Called

Function	Purpose
get_agency_credentials	Retrieve Ultravox API key (only when refresh=true)

External APIs Called

API	Method	Endpoint	Purpose
Ultravox	GET	/api/tools/{toolId}	Fetch latest tool data (only when refresh=true)

Related Functions

• List Tools -- Retrieve all tools for the agency
• Sync Tools -- Bulk sync all tools from Ultravox