{ "openapi": "3.0.0", "info": { "version": "2.0.0", "title": "Vida API", "description": "Vida API Documentation" }, "servers": [ { "url": "https://api.vida.dev", "description": "Vida Production", "variables": { "baseUrl": { "default": "api.vida.dev", "description": "Production API Root" } } } ], "paths": { "/api/v2/agent/functions": { "get": { "tags": [ "Agents" ], "summary": "List agent functions", "description": "Lists the functions the selected account can add to an agent. Check allowed and missingRequirement before changing the staging configuration.", "parameters": [ { "name": "targetAccountId", "in": "query", "description": "Account whose function access should be evaluated.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "functions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Stable function identifier stored in actions[].name.", "example": "callTransfer" }, "label": { "type": "string", "description": "Display name.", "example": "Call Transfer" }, "details": { "type": "string", "description": "What the function lets the agent do." }, "placeholder": { "type": "string", "description": "Guidance for authored function instructions." }, "limit": { "type": "integer", "nullable": true, "description": "Maximum number of this function that may be configured." }, "hasSettings": { "type": "boolean", "description": "Whether related agent settings are available." }, "requirePaid": { "type": "boolean", "description": "Whether this function requires a paid account." }, "requireComputer": { "type": "boolean", "description": "Whether this function delegates to a configured Computer Agent." }, "allowed": { "type": "boolean", "description": "Whether the selected account can currently use the function." }, "reason": { "type": "string", "nullable": true, "description": "Why the function is unavailable." }, "missingRequirement": { "type": "string", "nullable": true, "description": "Setup needed before the function can be used." }, "docsPage": { "type": "string", "nullable": true, "description": "Function guide URL." } } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agent/voices": { "get": { "tags": [ "Agents" ], "summary": "List agent voices", "description": "Lists the voices the selected account can configure. Use id as agentVoice, and check languages, compatibleS2SEngines, supportsStandardTts, and accountAvailability before saving.", "parameters": [ { "name": "targetAccountId", "in": "query", "description": "Account whose voice availability should be evaluated.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Voice catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "voices": { "type": "array", "items": { "$ref": "#/components/schemas/AgentVoice" } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/tokens": { "get": { "tags": [ "Authorization" ], "summary": "List tokens", "description": "List all your existing tokens.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "token": { "description": "Token", "type": "string", "example": "9fe4f9...." }, "description": { "description": "Friendly description of token", "type": "string", "example": "Main app" }, "type": { "description": "Token type", "type": "string", "example": "admin" }, "timestamp": { "description": "Timestamp when created", "type": "string", "example": "1678829072" }, "userId": { "description": "User Id that owns token", "type": "number", "example": 3 } } } } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Authorization" ], "summary": "Create a token", "description": "Create a new token for your account", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Token created successfully" }, "token": { "type": "object", "properties": { "token": { "description": "Token", "type": "string", "example": "9fe4f9...." }, "description": { "description": "Friendly description of token", "type": "string", "example": "Main app" }, "type": { "description": "Token type", "type": "string", "example": "admin" }, "timestamp": { "description": "Timestamp when created", "type": "string", "example": "167882907" }, "userId": { "description": "User Id that owns token", "type": "number", "example": 3 } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "description" ], "properties": { "type": { "description": "Permission for token. Only admin currently supported", "type": "string", "default": "admin" }, "description": { "description": "Friendly description for token", "type": "string", "example": "Main app" } } } } } } }, "delete": { "tags": [ "Authorization" ], "summary": "Delete a token", "description": "Delete a token from your account", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Token deleted successfully" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "description": "Token for deletion", "type": "string", "default": "9fe4f9...." } } } } } } } }, "/api/v2/sip/captures": { "get": { "tags": [ "SIP" ], "summary": "Fetch SIP Captures by SIP Call-ID", "description": "Search Vida SIP Captures by SIP Call-ID and export PCAP, JSON, or text transcript.", "parameters": [ { "name": "sipCallId", "in": "query", "description": "SIP Call-ID header value", "required": true, "example": "abc123@pbx.example.com", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Epoch millis start of search window", "required": false, "example": 1727395200000, "schema": { "type": "number" } }, { "name": "to", "in": "query", "description": "Epoch millis end of search window", "required": false, "example": 1727481600000, "schema": { "type": "number" } }, { "name": "format", "in": "query", "description": "text | pcap | json | transaction", "required": false, "example": "text", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized Request" }, "404": { "description": "No results found" }, "500": { "description": "Server error" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/sip/ipWhitelist": { "get": { "tags": [ "SIP" ], "summary": "List SIP IP Whitelist", "description": "List all your existing SIP IP whitelist entries.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "whitelist": { "type": "array", "items": { "type": "object", "properties": { "userId": { "description": "User Id", "type": "number", "example": 3 }, "label": { "description": "Friendly label for IP", "type": "string", "example": "Office IP" }, "timestamp": { "description": "Timestamp when created", "type": "number", "example": 1678829072 }, "ip": { "description": "Whitelisted IP", "type": "string", "example": "192.168.1.1" } } } } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "SIP" ], "summary": "Add IP to SIP IP Whitelist", "description": "Add a new IP address to your SIP IP whitelist.", "responses": { "200": { "description": "OK" }, "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "IP entry created successfully" }, "whitelist": { "type": "array", "items": { "type": "object", "properties": { "userId": { "description": "User Id", "type": "number", "example": 3 }, "label": { "description": "Friendly label for IP", "type": "string", "example": "Office IP" }, "timestamp": { "description": "Timestamp when created", "type": "number", "example": 1678829072 }, "ip": { "description": "Whitelisted IP", "type": "string", "example": "192.168.1.1" } } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ip", "label" ], "properties": { "ip": { "description": "IP address to whitelist", "type": "string", "example": "192.168.1.1" }, "label": { "description": "Friendly label for IP", "type": "string", "example": "Office IP" } } } } } } }, "delete": { "tags": [ "SIP" ], "summary": "Remove IP from SIP IP Whitelist", "description": "Remove an existing IP address from your SIP IP whitelist.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "IP entry deleted successfully" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ip" ], "properties": { "ip": { "description": "IP address to remove", "type": "string", "example": "192.168.1.1" } } } } } } } }, "/api/v2/sip/outboundRoutes": { "get": { "tags": [ "SIP" ], "summary": "List SIP Outbound Routes", "description": "List all existing SIP outbound routes for a user.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "routes": { "type": "array", "items": { "type": "string", "example": "1.1.1.1:5060;transport=udp" } } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "SIP" ], "summary": "Add SIP Outbound Route", "description": "Add a new outbound route for SIP. IP or domain Required (port and transport optional).", "responses": { "200": { "description": "OK" }, "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Route added successfully" }, "routes": { "type": "array", "items": { "type": "string", "example": "1.1.1.1:5060;transport=udp" } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "route" ], "properties": { "route": { "description": "Outbound route to add", "type": "string", "example": "1.1.1.1:5060;transport=udp" } } } } } } }, "delete": { "tags": [ "SIP" ], "summary": "Remove SIP Outbound Route", "description": "Remove an existing SIP outbound route.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Route removed successfully" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "route" ], "properties": { "route": { "description": "Outbound route to remove", "type": "string", "example": "1.1.1.1:5060;transport=udp" } } } } } } } }, "/api/v2/sip/registration/available": { "post": { "tags": [ "SIP" ], "summary": "Check SIP registration AOR availability", "description": "Validate whether an Address of Record (AOR) is free for the authenticated account.", "responses": { "200": { "description": "Availability response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "available": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "AOR is available" } } } } } }, "400": { "description": "Missing AOR details" }, "401": { "description": "Unauthorized Request" }, "500": { "description": "Server error while checking availability" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "aor": { "description": "Full SIP AOR to validate", "type": "string", "example": "1001@sip.example.com" }, "username": { "description": "Username portion used to build the AOR when aor is omitted", "type": "string", "example": "1001" }, "sipRealm": { "description": "SIP realm combined with username to build the AOR", "type": "string", "example": "sip.example.com" } } } } } } } }, "/api/v2/sip/registration": { "post": { "tags": [ "SIP" ], "summary": "Create or update SIP registration", "description": "Create a new SIP registration or update the existing registration for the authenticated account.", "responses": { "200": { "description": "Registration updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Registration updated successfully" } } } } } }, "201": { "description": "Registration created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Registration created successfully" } } } } } }, "400": { "description": "Invalid registration payload" }, "401": { "description": "Unauthorized Request" }, "409": { "description": "Duplicate AOR" }, "500": { "description": "Failed to add/update registration" }, "502": { "description": "Bad Gateway" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "aor": { "description": "Full SIP Address of Record", "type": "string", "example": "1001@sip.example.com" }, "username": { "description": "SIP username", "type": "string", "example": "1001" }, "authUsername": { "description": "SIP auth username (Authorization header)", "type": "string", "example": "auth-1001" }, "password": { "description": "SIP password", "type": "string", "example": "supersecret" }, "sipRealm": { "description": "SIP realm / domain", "type": "string", "example": "sip.example.com" }, "proxy": { "description": "Outbound proxy", "type": "string", "example": "sip.example.com:5061" }, "port": { "description": "Registration port", "type": "number", "example": 5060 }, "transport": { "description": "Transport protocol", "type": "string", "example": "TLS" }, "subscribe": { "description": "Whether to subscribe for presence", "type": "boolean", "example": false } } } } } } }, "get": { "tags": [ "SIP" ], "summary": "Get SIP registration", "description": "Retrieve the SIP registration associated with the authenticated account.", "responses": { "200": { "description": "Registration found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "registration": { "type": "object", "description": "Registration details", "properties": { "aor": { "type": "string", "example": "1001@sip.example.com" }, "username": { "type": "string", "example": "1001" }, "proxy": { "type": "string", "example": "sip.example.com:5061" }, "transport": { "type": "string", "example": "TLS" } } } } } } } }, "401": { "description": "Unauthorized Request" }, "404": { "description": "Registration not found" }, "500": { "description": "Failed to retrieve registration" } }, "security": [ { "apiKeyAuth": [] } ] }, "delete": { "tags": [ "SIP" ], "summary": "Delete SIP registration", "description": "Remove the SIP registration for the authenticated account.", "responses": { "200": { "description": "Registration deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Registration deleted successfully" } } } } } }, "401": { "description": "Unauthorized Request" }, "404": { "description": "Registration not found" }, "500": { "description": "Failed to delete registration" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/phoneNumbers": { "get": { "tags": [ "Phone Numbers" ], "summary": "List assigned phone numbers", "description": "Returns phone numbers assigned to the selected agent account and identifies its primary number.", "parameters": [ { "name": "targetAccountId", "in": "query", "description": "Agent account whose assigned phone numbers should be returned.", "required": true, "example": 3026480, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Assigned phone numbers returned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "primaryNumber": { "type": "string", "nullable": true, "example": "+12145551234" }, "phoneNumbers": { "type": "array", "items": { "type": "object", "properties": { "phoneNumber": { "type": "string", "example": "+12145551234" }, "country": { "type": "string", "example": "US" }, "region": { "type": "string", "nullable": true, "example": "TX" }, "city": { "type": "string", "nullable": true, "example": "Dallas" }, "lineStatus": { "type": "string", "nullable": true, "example": "ONLINE" }, "isPrimary": { "type": "boolean", "example": true } } } } } } } } }, "401": { "description": "Unauthorized request" }, "500": { "description": "Assigned phone numbers could not be returned" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/phoneNumber/assign": { "post": { "tags": [ "Phone Numbers" ], "summary": "Assign phone number to your account", "description": "Assign phone number to your account for use", "responses": { "200": { "description": "Successfully assigned phone number to account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Unable to assign phone number", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A descriptive error message" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "number", "country" ], "properties": { "number": { "description": "Phone Number to assign to your account", "type": "string", "example": "+12145551234" }, "country": { "description": "Country for the phone number to assign", "type": "string", "example": "US" } } } } } } } }, "/api/v2/phoneNumber/byo/assign": { "post": { "tags": [ "Phone Numbers" ], "summary": "Assign a BYO phone number", "description": "Assign a phone number you are supplying yourself to an agent. Requires reseller account.", "responses": { "200": { "description": "Successfully assigned phone number to account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Unable to assign phone number", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A descriptive error message" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "number" ], "properties": { "number": { "description": "Phone Number to assign to your account", "type": "string", "example": "+12145551234" }, "providerId": { "description": "Numbering provider to assign the number through (e.g. Bird). Case insensitive. Omit it to assign the number with no provider attached.", "type": "string", "example": "Bird" }, "channelId": { "description": "For Bird BYO: the id of the existing SMS channel for this number. Requires providerId.", "type": "string", "example": "614208aa-1234" } } } } } } } }, "/api/v2/phoneNumber/return": { "post": { "tags": [ "Phone Numbers" ], "summary": "Return / Unassign Phone Number", "description": "Return a phone number and unassigns the number from the agent account. If provided by an external integrated number supplier, will return to them too. Requires reseller account.", "responses": { "200": { "description": "Successfully returned phone number", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Unable to return phone number", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A descriptive error message" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "number" ], "properties": { "number": { "description": "Phone Number to unassign from your account", "type": "string", "example": "+12145551234" } } } } } } } }, "/api/v2/phoneNumber/search/local/locality": { "post": { "tags": [ "Phone Numbers" ], "summary": "Search for local numbers by locality", "description": "Search for a phone number based on city, region, and country.", "responses": { "200": { "description": "Successfully retrieved available numbers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "No phone numbers available for the search area. Please try a different area.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A descriptive error message" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phoneNumber", "code" ], "properties": { "city": { "description": "City you are searching for. If the particular city is unavailable, phone numbers from a 10 mile radius will be returned", "type": "string", "example": "Austin" }, "region": { "description": "Region for the search. If searching within the U.S., this will be the state", "type": "string", "example": "TX" }, "country": { "description": "Country for the search", "type": "string", "example": "US" } } } } } } } }, "/api/v2/phoneNumber/search/local/prefix": { "post": { "tags": [ "Phone Numbers" ], "summary": "Search for local numbers by prefix", "description": "Search for a phone number based on prefix.", "responses": { "200": { "description": "Successfully retrieved available numbers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "No phone numbers available for the search area. Please try a different area.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A descriptive error message" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phoneNumber", "code" ], "properties": { "prefix": { "description": "Prefix you are searching for", "type": "string", "example": "216" }, "country": { "description": "Country used for the search", "type": "string", "example": "US" }, "strict": { "description": "If strict search is to be used. If no results found, will other numbers in same general area.", "type": "boolean", "default": true } } } } } } } }, "/api/v2/phoneNumber/search/local/phrase": { "post": { "tags": [ "Phone Numbers" ], "summary": "Search for local numbers by phrase", "description": "Search for a phone number based on phrase.", "responses": { "200": { "description": "Successfully retrieved available numbers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "No phone numbers available for the search area. Please try a different area.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A descriptive error message" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phrase", "country" ], "properties": { "phrase": { "description": "String to search for. This supports asterisk wildcards *", "type": "string", "example": "*bitcoin*" }, "country": { "description": "Country used for the search", "type": "string", "example": "US" }, "region": { "description": "Region for the search. If searching within the U.S., this will be the state", "type": "string", "example": "TX" }, "city": { "description": "City you are searching for. If the particular city is unavailable, phone numbers from a 10 mile radius will be returned", "type": "string", "example": "Austin" } } } } } } } }, "/api/v2/conversations": { "get": { "tags": [ "Messaging" ], "summary": "List Priority Inbox", "description": "Fetch rooms in priority inbox", "parameters": [ { "name": "pagination", "in": "query", "description": "Whether to provide pagination", "required": true, "example": true, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Page number to fetch", "required": false, "example": 0, "schema": { "type": "number" } }, { "name": "pageSize", "in": "query", "description": "How many rooms per page", "required": false, "example": 20, "schema": { "type": "number" } }, { "name": "unread", "in": "query", "description": "Only return unread rooms", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "number", "example": 20 }, "pageNumber": { "type": "number", "example": 0 }, "totalRooms": { "type": "number", "example": 100 }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "roomId": { "description": "Room Id", "type": "string", "example": "3:15" }, "name": { "description": "Other users full name", "type": "string", "example": "John Doe" }, "id": { "description": "userId of other user", "type": "number", "example": 15 }, "image": { "description": "Link to other users image", "type": "string", "example": "https://somepublicURl" }, "vidaPhoneNumber": { "description": "Other user Vida Phone Number", "type": "string", "example": "+12165169995" }, "unregistered": { "description": "If the other user is registered on Vida platform or offnet", "type": "boolean", "example": false }, "unregisteredDisplayName": { "description": "Display name for unregistered user which is often their phone number or email", "type": "string", "example": "+15125551234" }, "destinationInboxType": { "description": "Indicator which inbox on the other user side the conversation is in", "type": "string", "example": "+15125551234" }, "lastMessage": { "description": "Last message text in the room", "type": "string", "example": "That was awesome, thanks!" }, "lastMessageTimestamp": { "description": "Epoch of the last messages timestamp", "type": "number", "example": 1710510072 } } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/junkConversations": { "get": { "tags": [ "Messaging" ], "summary": "List Junk Inbox", "description": "Fetch rooms in junk inbox", "parameters": [ { "name": "pagination", "in": "query", "description": "Whether to provide pagination", "required": true, "example": true, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Page number to fetch", "required": false, "example": 0, "schema": { "type": "number" } }, { "name": "pageSize", "in": "query", "description": "How many rooms per page", "required": false, "example": 20, "schema": { "type": "number" } }, { "name": "unread", "in": "query", "description": "Only return unread rooms", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "pageSize": { "type": "number", "example": 20 }, "pageNumber": { "type": "number", "example": 0 }, "totalRooms": { "type": "number", "example": 100 }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "roomId": { "description": "Room Id", "type": "string", "example": "3:15" }, "name": { "description": "Other users full name", "type": "string", "example": "John Doe" }, "id": { "description": "userId of other user", "type": "number", "example": 15 }, "image": { "description": "Link to other users image", "type": "string", "example": "https://somepublicURl" }, "vidaPhoneNumber": { "description": "Other user Vida Phone Number", "type": "string", "example": "+12165169995" }, "unregistered": { "description": "If the other user is registered on Vida platform or offnet", "type": "boolean", "example": false }, "unregisteredDisplayName": { "description": "Display name for unregistered user which is often their phone number or email", "type": "string", "example": "+15125551234" }, "destinationInboxType": { "description": "Indicator which inbox on the other user side the conversation is in", "type": "string", "example": "+15125551234" }, "lastMessage": { "description": "Last message text in the room", "type": "string", "example": "That was awesome, thanks!" }, "lastMessageTimestamp": { "description": "Epoch of the last messages timestamp", "type": "number", "example": 1710510072 } } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/messages/recent": { "get": { "tags": [ "Messaging" ], "summary": "Fetch Recent Messages", "description": "Fetch recent messages across all inboxes.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "from": { "description": "From User Id", "type": "number", "example": 1234567890 }, "fromUser": { "description": "From User Name", "type": "string", "example": "user_test" }, "to": { "description": "To User Id", "type": "number", "example": 878589 }, "toUser": { "description": "To User Name", "type": "string", "example": "support2" }, "timestamp": { "description": "Epoch of the last message's timestamp", "type": "number", "example": 1718463395 }, "date": { "description": "Friendly Date", "type": "string", "example": "2024-06-15T14:56:35.000Z" }, "message": { "description": "Message text", "type": "string", "example": "Hi there! Lyle is currently unavailable. Could you please let me know the nature of your call or message and any specific details you'd like me to pass on to him? Thanks!" }, "content-type": { "description": "Content type of the message", "type": "string", "example": "text/plain" }, "disposition-notification": { "description": "Disposition notification status", "type": "string", "example": null }, "roomId": { "description": "Room Id", "type": "string", "example": "1:878589" }, "status": { "description": "Status of the message", "type": "string", "example": "success" }, "attachments": { "description": "Array of media attachment URLs", "type": "array", "items": { "type": "object", "properties": { "content-type": { "type": "string", "example": "audio/mp3" }, "filename": { "type": "string", "example": "mp3" }, "content-url": { "type": "string", "example": "https://example.com/media/recording.mp3" }, "attachmentType": { "type": "string", "example": "call" } } } }, "isLive": { "description": "Whether the message is live", "type": "boolean", "example": false }, "aiAgent": { "description": "Whether an AI agent is involved", "type": "boolean", "example": true }, "aiLeadRating": { "description": "AI lead rating", "type": "number", "example": null }, "aiLeadRatingReason": { "description": "Reason for AI lead rating", "type": "string", "example": null }, "aiAgentOverride": { "description": "AI agent override status", "type": "string", "example": null }, "source": { "description": "Source medium for the message", "type": "string", "example": "email" }, "uuid": { "description": "Unique ID for message", "type": "string", "example": "a4977f49-80a6-41f0-9add-93a270cdd781" }, "fromNumber": { "description": "Phone number of the sender", "type": "string", "example": "+15125551234" }, "toNumber": { "description": "Phone number of the recipient", "type": "string", "example": "+15125559876" }, "notify": { "description": "Notification flag", "type": "boolean", "example": false }, "targetInbox": { "description": "Target inbox", "type": "string", "example": "inbox" }, "type": { "description": "Type of message", "type": "string", "example": "call" }, "duration": { "description": "Duration of the call", "type": "number", "example": 9 }, "direction": { "description": "Direction of the call", "type": "string", "example": "inbound" }, "missedCall": { "description": "Whether it was a missed call", "type": "boolean", "example": false }, "bypassAgent": { "description": "Whether the agent was bypassed", "type": "boolean", "example": false }, "cnamSpam": { "description": "Whether the call was marked as spam by CNAM", "type": "boolean", "example": false }, "selfCall": { "description": "Whether the call was self-initiated", "type": "boolean", "example": true }, "callingUserIsContact": { "description": "Whether the calling user is a contact", "type": "boolean", "example": false }, "agentOutcome": { "description": "Outcome from the agent", "type": "string", "example": null }, "summary": { "description": "Summary of the message", "type": "string", "example": null }, "callDialog": { "description": "Array of dialog entries with roles and contents for Calls", "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "example": "assistant" }, "content": { "type": "string", "example": "Hello! This is the answering assistant. How can I help you?" } } } }, "chatDialog": { "description": "Array of dialog entries with roles and contents for Chats", "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "example": "assistant" }, "content": { "type": "string", "example": "Hello! This is the answering assistant. How can I help you?" } } } }, "agentReplyCount": { "description": "The number of agent responses in the conversation. Useful for billing.", "type": "number", "example": 10 }, "campaign": { "description": "Campaign status", "type": "boolean", "example": true }, "diversion": { "description": "Diversion status", "type": "string", "example": null }, "voicemailRecording": { "description": "Voicemail recording details", "type": "string", "example": null }, "eventType": { "description": "Type of event", "type": "string", "example": "inbound-call" }, "forcedCampaign": { "description": "Forced campaign flag", "type": "boolean", "example": true } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/messages/{roomId}": { "get": { "tags": [ "Messaging" ], "summary": "Fetch Room Messages", "description": "Fetch all messages for a particular room Id", "parameters": [ { "name": "roomId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Room Id to fetch messages for", "example": "3:15" }, { "name": "targetAccountId", "in": "query", "description": "Selected account that owns the room. Include this when the API token can access more than one account.", "required": false, "schema": { "type": "integer" }, "example": 3026480 } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "message": { "description": "Message text", "type": "string", "example": "Hey there!" }, "from": { "description": "From User Id", "type": "number", "example": 15 }, "fromUser": { "description": "From User Name", "type": "string", "example": "Brandon" }, "to": { "description": "From User Id", "type": "number", "example": 35554545 }, "toUser": { "description": "To User Name", "type": "string", "example": "Jillian" }, "timestamp": { "description": "Epoch of the last messages timestamp", "type": "number", "example": 1699633022 }, "date": { "description": "Friendly Date", "type": "string", "example": "2023-11-10T16:17:02.000Z" }, "roomId": { "description": "Room Id", "type": "string", "example": "15:35554545" }, "status": { "description": "If message was delivered. Status of success indicates delivered", "type": "string", "example": "success" }, "attachments": { "description": "Array of media attachment Urls.", "type": "string", "example": "[]" }, "drip": { "description": "If this message was a paid drip", "type": "boolean", "example": false }, "uuid": { "description": "Unique id for message", "type": "string", "example": "3b38f0af-7341-49fd-acce-1749c904e00d" }, "source": { "description": "Source medium for the message. Could have sourced from a vida client, sms, voice, email", "type": "string", "example": "sms" }, "roomInitiator": { "description": "User name who first initiated contact for the room", "type": "string", "example": "brandon" } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agent/receiveMessage": { "post": { "tags": [ "Messaging" ], "summary": "Send message to an agent from your own platform", "description": "Send a message from your platform to an agent. Must pass outboundMessageWebhookUrl or configure on the organization to receive agent responses. Reseller or partners only. ", "responses": { "200": { "description": "Message queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "messageUuid": { "type": "string", "example": "uuid" } } } } } }, "400": { "description": "Failed to queue message", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid Vida user" } } } } } }, "403": { "description": "Forbidden" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targetAgent", "sourceAddress", "message" ], "properties": { "targetAgent": { "description": "Agent account ID, phone number, or username", "type": "string", "example": "agent123" }, "sourceAddress": { "description": "Sender phone number or address", "type": "string", "example": "+15551231234" }, "message": { "description": "Message text", "type": "string", "example": "Hello there" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "url": { "type": "string" } } }, "example": [ { "type": "image", "url": "https://example.com/image.png" } ] }, "context": { "type": "object", "example": { "threadId": "abc123" } }, "metadata": { "type": "object", "example": { "key": "value" } }, "outboundMessageWebhookUrl": { "description": "Webhook URL (POST) to deliver agent responses to. If not specified will look for default outboundMessageWebhookUrl webhook settings.", "type": "string", "example": "https://example.com/hook" } } } } } } } }, "/api/v2/agent/publish": { "post": { "tags": [ "Agents" ], "summary": "Publish an Agent", "description": "Publish your staging agent to your active default agent. ", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Agent camp931829b5857f published" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agent/revert": { "post": { "tags": [ "Agents" ], "summary": "Revert an Agent", "description": "Revert staging agent to current default active agent settings", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Agent camp931829b5857f unpublished" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agent": { "post": { "tags": [ "Agents" ], "summary": "Update staging agent configuration", "description": "Updates the selected account staging configuration. Omitted settings retain their current values. Publish separately when the staged changes are ready to become live.", "parameters": [ { "name": "targetAccountId", "in": "query", "description": "Account whose staging configuration should be updated.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Staging configuration updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Campaign updated successfully" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConfigurationWrite" } } } } } }, "/api/v2/agent/{agentConfigId}/versions": { "get": { "tags": [ "Agents" ], "summary": "List Agent Versions", "description": "Lists saved snapshots stored for the live configuration. Use the live agentConfigId returned by GET /api/v2/agentEventRules/default. Pass includeData=true to include each full snapshot.", "parameters": [ { "name": "agentConfigId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Live agent configuration ID whose saved versions should be listed.", "example": "campa3cfdc312750b193de0..." }, { "name": "includeData", "in": "query", "description": "If true the response includes the entire snapshot JSON for each version.", "required": false, "example": "true", "schema": { "type": "boolean" } }, { "name": "targetAccountId", "in": "query", "description": "Account that owns the agent configuration.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "versions": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "example": "Auto-1750194180352" }, "versionId": { "type": "integer", "example": 1750194180352 }, "snapshot": { "type": "object", "description": "Only present when includeData=true" } } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Agents" ], "summary": "Save agent version", "description": "Saves the selected account current staging or live configuration as a named version. Versions are stored under the live agent configuration.", "parameters": [ { "name": "agentConfigId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Live agent configuration ID used for this account version history." }, { "name": "targetAccountId", "in": "query", "description": "Account whose configuration should be saved.", "required": true, "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Snapshot stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "createdVersion": { "type": "object", "properties": { "title": { "type": "string", "example": "Holiday-2025" }, "versionId": { "type": "integer", "example": 1750195000123 } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "example": "Holiday-2025" }, "source": { "type": "string", "enum": [ "staging", "default" ], "default": "staging" } } } } } } } }, "/api/v2/agent/{agentConfigId}/versions/{versionId}": { "post": { "tags": [ "Agents" ], "summary": "Replace saved agent version", "description": "Replaces one saved version with a complete agent configuration snapshot. Read the existing snapshot first and preserve settings you do not intend to change.", "parameters": [ { "name": "agentConfigId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Live agent configuration ID that owns this version." }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Epoch-ms score identifying the snapshot", "example": 1750195000123 }, { "name": "targetAccountId", "in": "query", "description": "Account that owns this version.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Version replaced", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "versionId": { "type": "integer", "example": 1750195000123 } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "snapshot" ], "properties": { "snapshot": { "$ref": "#/components/schemas/AgentConfigurationWrite" } } } } } } }, "delete": { "tags": [ "Agents" ], "summary": "Delete saved agent version", "description": "Deletes a saved version. A version used by an active experiment or Task cannot be deleted.", "parameters": [ { "name": "agentConfigId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Live agent configuration ID that owns this version." }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric saved-version identifier.", "example": 1750195000123 }, { "name": "targetAccountId", "in": "query", "description": "Account that owns this version.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Version deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "versionId": { "type": "integer", "example": 1750195000123 }, "deleted": { "type": "integer", "example": 1 } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agent/{agentConfigId}/versions/{versionId}/restore": { "post": { "tags": [ "Agents" ], "summary": "Restore saved agent version", "description": "Copies a saved version into staging by default. Use target=default only when an immediate live restore is intentional; staging restores still require publish.", "parameters": [ { "name": "agentConfigId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Live agent configuration ID used for this account version history." }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Epoch-ms score of the snapshot", "example": 1750195000123 }, { "name": "targetAccountId", "in": "query", "description": "Account whose configuration should be restored.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Snapshot restored", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "restored": { "$ref": "#/components/schemas/AgentConfigurationRead" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "staging", "default" ], "default": "staging" } } } } } } } }, "/api/v2/agent/{agentConfigId}/versions/{versionId}/title": { "put": { "tags": [ "Agents" ], "summary": "Rename saved agent version", "description": "Changes only the display title of a saved version.", "parameters": [ { "name": "agentConfigId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Live agent configuration ID that owns this version." }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Epoch-ms score of the snapshot", "example": 1750195000123 }, { "name": "targetAccountId", "in": "query", "description": "Account that owns this version.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Title updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "versionId": { "type": "integer", "example": 1750195000123 }, "newTitle": { "type": "string", "example": "Holiday-2025" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "example": "Holiday-2025" } } } } } } } }, "/api/v2/checkAgentUrl": { "get": { "tags": [ "Agent URLs" ], "summary": "Check agent url availability", "description": "Check if an agent url is available for use", "parameters": [ { "name": "targetUsername", "in": "query", "description": "Target username", "required": true, "example": "brandon", "schema": { "type": "string" } }, { "name": "slug", "in": "query", "description": "Desired slug name", "required": true, "example": "weloveVida", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Slug created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "available": { "type": "boolean", "example": true }, "slug": { "type": "string", "example": "welovevida" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agentUrl": { "get": { "tags": [ "Agent URLs" ], "summary": "Fetch existing agent url", "description": "Check if existing agent url exists for a user or create new one", "parameters": [ { "name": "targetUsername", "in": "query", "description": "Target username", "required": true, "example": "brandon", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Slug retrieved/fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "slug": { "type": "string", "example": "welovevida" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Agent URLs" ], "summary": "Create agent url", "description": "Create a new url for an agent and replace existing one if exists", "responses": { "200": { "description": "Agent URL Created Successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "slug": { "type": "string", "example": "welovevida" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targetUsername", "slug" ], "properties": { "targetUsername": { "description": "Target username for the agent URL", "type": "string", "example": "brandon" }, "slug": { "description": "Desired slug name", "type": "string", "example": "welovevida" } } } } } } } }, "/api/v2/agent/{agentConfigId}": { "get": { "tags": [ "Agents" ], "summary": "Get Agent", "description": "Returns one agent configuration by its agentConfigId. Use the staging or live endpoints when you want the selected account current slot without first knowing its identifier.", "parameters": [ { "name": "agentConfigId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent configuration ID.", "example": "campa931829b5857f...." }, { "name": "targetAccountId", "in": "query", "description": "Account used to authorize this read.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "campaign": { "$ref": "#/components/schemas/AgentConfigurationRead" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agent/outboundCall": { "post": { "tags": [ "Agents" ], "summary": "Queue outbound call(s) from your Agent", "description": "Queue call Tasks for one target or up to 10,000 targets. The endpoint accepts Task goals, retry policies, organization defaults, external correlation IDs, metadata, and Contact List enrollment. Submissions over 1,000 targets require Idempotency-Key and return 202. Use meta.contact for structured Contact data such as name, email, address and customFields. In a batch, put lead-specific metadata on each target object. See [Contact fields](https://vida.io/docs/api-reference/platform-guides/contacts-and-objectives#contact-fields) for the complete metadata field reference.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "string" }, "maxLength": { "type": "number", "example": 200 } } }, "description": "Required for submissions over 1,000 targets. Repeating the same key and payload safely resumes or returns that submission." } ], "responses": { "200": { "description": "Queued successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Outbound call initiated." }, "inserted": { "type": "integer", "example": 3 }, "batchId": { "type": "string", "example": "f52b1e01-5cbc-483c-9939-3bf7d37e1426" }, "tasks": { "type": "array", "items": { "type": "object" } } } } } } }, "202": { "description": "Large call Task submission accepted for asynchronous creation" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "409": { "description": "Idempotency conflict or overlapping active retryable Task" }, "500": { "description": "Server Error" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "string", "description": "Phone in E.164 or VIDA username", "example": "+1234567890" }, "context": { "type": "string", "description": "Context for the agent to use during the call", "example": "Name: Lyle Pratt. Interested in product demo." }, "taskContext": { "type": "string", "description": "Task-specific context injected only for this call" }, "greeting": { "type": "string", "description": "Custom greeting to use at call start" }, "waitToGreet": { "type": "boolean", "description": "Delay greeting until caller speaks" }, "accountId": { "type": "integer", "description": "Optional agent account id override for the call" }, "scheduledFor": { "type": "integer", "description": "Unix seconds in the future to schedule the call" }, "goal": { "type": "object", "nullable": true, "description": "Task-specific goal with completionCriteria. Omit or pass null to use the organization default." }, "retryPolicy": { "type": "object", "nullable": true, "description": "Task-specific cadence using delaysSeconds or mixed-channel steps, retryOn, and optional responseTimeoutSeconds. Omit or pass null to use the organization default." }, "meta": { "type": "object", "additionalProperties": true, "properties": { "contact": { "$ref": "#/components/schemas/TaskContactFields" } }, "description": "Optional Task metadata. meta.contact fills missing structured Contact fields at creation; existing values are preserved. For multiple targets, set contact data in meta.contact on each target object. Per-item meta replaces the entire top-level meta object; it is not deep-merged. To call target first and bridge them elsewhere, use meta.bridgeAfterAnswer." }, "externalTaskId": { "type": "string", "description": "Reusable customer correlation/grouping ID; not an idempotency key" }, "contactListName": { "type": "string", "description": "Optional Contact List to enroll the contact into" } } }, { "type": "object", "required": [ "targets" ], "properties": { "targets": { "description": "Array of destinations or objects with per-item options", "oneOf": [ { "type": "array", "items": { "type": "string", "example": "+1234567890" } }, { "type": "array", "items": { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "string", "example": "+1234567890" }, "context": { "type": "string" }, "taskContext": { "type": "string" }, "accountId": { "type": "integer" }, "scheduledFor": { "type": "integer" }, "greeting": { "type": "string" }, "waitToGreet": { "type": "boolean" }, "goal": { "type": "object", "description": "Goal for this Task" }, "retryPolicy": { "type": "object", "description": "Per-target retry override; null uses the organization default" }, "meta": { "type": "object", "additionalProperties": true, "properties": { "contact": { "$ref": "#/components/schemas/TaskContactFields" } }, "description": "Optional Task metadata. meta.contact fills missing structured Contact fields at creation; existing values are preserved. For multiple targets, set contact data in meta.contact on each target object. Per-item meta replaces the entire top-level meta object; it is not deep-merged." }, "contactListName": { "type": "string" }, "externalTaskId": { "type": "string", "description": "Identifier applied to this task" } } } } ] }, "context": { "type": "string", "description": "Context applied to all items when targets is an array of strings" }, "taskContext": { "type": "string", "description": "Task-specific context applied to all items when targets is an array of strings" }, "greeting": { "type": "string", "description": "Greeting applied to all items when targets is an array of strings" }, "waitToGreet": { "type": "boolean", "description": "Delay greeting until caller speaks for all items when targets is an array of strings" }, "accountId": { "type": "integer", "description": "Account id applied to all items when not provided per item" }, "scheduledFor": { "type": "integer", "description": "Schedule applied to all items when not provided per item" }, "goal": { "type": "object", "description": "Goal applied to each Task unless that item provides its own" }, "retryPolicy": { "type": "object", "description": "Task-specific retry override applied to all items; omitted or null values use the organization default" }, "scheduleSpacingSec": { "type": "integer", "description": "If provided, stagger scheduledFor by this many seconds per index", "example": 30 }, "meta": { "type": "object", "additionalProperties": true, "properties": { "contact": { "$ref": "#/components/schemas/TaskContactFields" } }, "description": "Optional Task metadata. meta.contact fills missing structured Contact fields at creation; existing values are preserved. For multiple targets, set contact data in meta.contact on each target object. Per-item meta replaces the entire top-level meta object; it is not deep-merged." }, "externalTaskId": { "type": "string", "description": "Reusable correlation/grouping ID applied to all created Tasks" }, "contactListName": { "type": "string", "description": "Contact List to enroll every contact into" } } } ] }, "examples": { "single": { "summary": "Single target", "value": { "target": "+15551234567", "context": "Call back about pricing", "meta": { "contact": { "name": "Example Person", "email": "lead@example.com", "address": { "state": "LA", "zip": "71101" }, "customFields": { "vendorLeadCode": "lead-123" } } } } }, "bridgeAfterAnswer": { "summary": "Call the customer, then bridge them to another number", "value": { "target": "+15551111111", "meta": { "bridgeAfterAnswer": { "destination": "+15552222222", "monitor": true } } } }, "batchStrings": { "summary": "Multiple string targets with shared context", "value": { "targets": [ "+15551230001", "+15551230002", "+15551230003" ], "context": "Follow up on demo request", "scheduleSpacingSec": 15 } }, "batchObjects": { "summary": "Multiple object targets with per-item overrides", "value": { "targets": [ { "target": "+15551230001", "context": "VIP", "scheduledFor": 1730000000 }, { "target": "+15551230002" } ], "accountId": 1234 } } } } } } } }, "/api/v2/agent/outboundSms": { "post": { "tags": [ "Agents" ], "summary": "Queue outbound SMS text message(s) from your Agent", "description": "Queue SMS Tasks for one target and message or up to 10,000 targets. The endpoint accepts Task goals, retry policies, organization defaults, external correlation IDs, metadata, and Contact List enrollment. Submissions over 1,000 targets require Idempotency-Key and return 202. Use meta.contact for structured Contact data such as name, email, address and customFields. In a batch, put lead-specific metadata on each target object. See [Contact fields](https://vida.io/docs/api-reference/platform-guides/contacts-and-objectives#contact-fields) for the complete metadata field reference.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "string" }, "maxLength": { "type": "number", "example": 200 } } }, "description": "Required for submissions over 1,000 targets. Repeating the same key and payload safely resumes or returns that submission." } ], "responses": { "200": { "description": "Queued successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Outbound SMS initiated." }, "inserted": { "type": "integer", "example": 3 }, "batchId": { "type": "string", "example": "f52b1e01-5cbc-483c-9939-3bf7d37e1426" }, "tasks": { "type": "array", "items": { "type": "object" } } } } } } }, "202": { "description": "Large SMS Task submission accepted for asynchronous creation" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "409": { "description": "Idempotency conflict or overlapping active retryable Task" }, "500": { "description": "Server Error" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "type": "object", "required": [ "target", "content" ], "properties": { "target": { "type": "string", "description": "Phone in E.164 or VIDA username", "example": "+1234567890" }, "content": { "type": "string", "description": "Message body", "example": "Hello from Acme. Your appointment is tomorrow at 10am." }, "context": { "type": "string", "description": "Optional context for the agent handling the conversation" }, "taskContext": { "type": "string", "description": "Task-specific context for this message" }, "accountId": { "type": "integer", "description": "Optional agent account id override for the message" }, "agentId": { "type": "integer", "description": "Optional campaign id override" }, "scheduledFor": { "type": "integer", "description": "Unix seconds to schedule delivery" }, "goal": { "type": "object", "nullable": true, "description": "Task-specific goal with completionCriteria. Omit or pass null to use the organization default." }, "retryPolicy": { "type": "object", "nullable": true, "description": "Task-specific cadence using delaysSeconds or mixed-channel steps, retryOn, and optional responseTimeoutSeconds. Omit or pass null to use the organization default." }, "meta": { "type": "object", "additionalProperties": true, "properties": { "contact": { "$ref": "#/components/schemas/TaskContactFields" } }, "description": "Optional Task metadata. meta.contact fills missing structured Contact fields at creation; existing values are preserved. For multiple targets, set contact data in meta.contact on each target object. Per-item meta replaces the entire top-level meta object; it is not deep-merged." }, "externalTaskId": { "type": "string", "description": "Reusable customer correlation/grouping ID; not an idempotency key" }, "contactListName": { "type": "string", "description": "Optional Contact List to enroll the contact into" } } }, { "type": "object", "required": [ "targets" ], "properties": { "targets": { "description": "Array of destinations or objects with per-item options", "oneOf": [ { "type": "array", "items": { "type": "string", "example": "+1234567890" } }, { "type": "array", "items": { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "string", "example": "+1234567890" }, "content": { "type": "string", "description": "Per-item message body" }, "context": { "type": "string" }, "taskContext": { "type": "string" }, "accountId": { "type": "integer" }, "agentId": { "type": "integer" }, "scheduledFor": { "type": "integer" }, "goal": { "type": "object", "description": "Goal for this Task" }, "retryPolicy": { "type": "object", "description": "Per-target retry override; null uses the organization default" }, "meta": { "type": "object", "additionalProperties": true, "properties": { "contact": { "$ref": "#/components/schemas/TaskContactFields" } }, "description": "Optional Task metadata. meta.contact fills missing structured Contact fields at creation; existing values are preserved. For multiple targets, set contact data in meta.contact on each target object. Per-item meta replaces the entire top-level meta object; it is not deep-merged." }, "contactListName": { "type": "string" }, "externalTaskId": { "type": "string", "description": "Identifier applied to this task" } } } } ] }, "content": { "type": "string", "description": "Message applied to all when targets is an array of strings" }, "context": { "type": "string", "description": "Context applied to all items when not provided per item" }, "taskContext": { "type": "string", "description": "Task-specific context applied to all items when not provided per item" }, "accountId": { "type": "integer", "description": "Agent account id applied to all items when not provided per item" }, "agentId": { "type": "integer", "description": "Agent id applied to all items" }, "scheduledFor": { "type": "integer", "description": "Schedule applied to all items" }, "goal": { "type": "object", "description": "Goal applied to each Task unless that item provides its own" }, "retryPolicy": { "type": "object", "description": "Task-specific retry override applied to all items; omitted or null values use the organization default" }, "scheduleSpacingSec": { "type": "integer", "description": "If provided, stagger scheduledFor by this many seconds per index", "example": 15 }, "meta": { "type": "object", "additionalProperties": true, "properties": { "contact": { "$ref": "#/components/schemas/TaskContactFields" } }, "description": "Optional Task metadata. meta.contact fills missing structured Contact fields at creation; existing values are preserved. For multiple targets, set contact data in meta.contact on each target object. Per-item meta replaces the entire top-level meta object; it is not deep-merged." }, "externalTaskId": { "type": "string", "description": "Reusable correlation/grouping ID applied to all created Tasks" }, "contactListName": { "type": "string", "description": "Contact List to enroll every contact into" } } } ] }, "examples": { "single": { "summary": "Single target", "value": { "target": "+15551234567", "content": "Hi, quick reminder for tomorrow at 10am.", "context": "Reminder campaign", "meta": { "contact": { "name": "Example Person", "address": { "state": "LA" }, "customFields": { "vendorLeadCode": "lead-123" } } } } }, "batchStrings": { "summary": "Multiple string targets with shared content", "value": { "targets": [ "+15551230001", "+15551230002", "+15551230003" ], "content": "Thanks for signing up. Reply YES to confirm.", "context": "Onboarding nudge", "scheduleSpacingSec": 10 } }, "batchObjects": { "summary": "Multiple object targets with per-item overrides", "value": { "targets": [ { "target": "+15551230001", "content": "VIP reminder 9am", "context": "VIP", "scheduledFor": 1730000000 }, { "target": "+15551230002", "content": "Standard reminder 10am" } ], "agentId": 1234 } } } } } } } }, "/api/v2/agent/outboundEmail": { "post": { "tags": [ "Agents" ], "summary": "Queue outbound email(s) from your Agent", "description": "Queue email Tasks for an email-enabled agent account. Pass target or to/cc/bcc for one email, or use up to 10,000 targets for separate emails. Organization default goals and retries apply when configured; use POST /api/v2/tasks to supply a Task-specific goal or retry policy. Submissions over 1,000 targets require Idempotency-Key and return 202. Use meta.contact for structured Contact data such as name, email, address and customFields. In a batch, put lead-specific metadata on each target object. See [Contact fields](https://vida.io/docs/api-reference/platform-guides/contacts-and-objectives#contact-fields) for the complete metadata field reference.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "string" }, "maxLength": { "type": "number", "example": 200 } } }, "description": "Required for submissions over 1,000 targets. Repeating the same key and payload safely resumes or returns that submission." } ], "responses": { "200": { "description": "Queued successfully" }, "202": { "description": "Large email Task submission accepted for asynchronous creation" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Server Error" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "type": "object", "required": [ "content" ], "properties": { "target": { "type": "string", "description": "Destination email address", "example": "person@example.com" }, "to": { "description": "Destination email address or array of destination email addresses for one email" }, "cc": { "description": "CC email address or array of CC email addresses for one email" }, "bcc": { "description": "BCC email address or array of BCC email addresses for one email" }, "content": { "type": "string", "description": "Email body. Raw HTML is supported." }, "subject": { "type": "string", "description": "Email subject line" }, "attachments": { "type": "array", "description": "SendGrid-style attachment objects with base64 content" }, "context": { "type": "string", "description": "Optional context for the task" }, "taskContext": { "type": "string", "description": "Task-specific context" }, "accountId": { "type": "integer", "description": "Optional agent account id override" }, "agentId": { "type": "integer", "description": "Optional campaign id override" }, "roomId": { "type": "string", "description": "Room id when replying to an existing email message" }, "replyToMessageUuid": { "type": "string", "description": "Email message uuid to reply to; used with roomId for thread headers" }, "scheduledFor": { "type": "integer", "description": "Unix seconds to schedule delivery" }, "meta": { "type": "object", "additionalProperties": true, "properties": { "contact": { "$ref": "#/components/schemas/TaskContactFields" } }, "description": "Optional Task metadata. meta.contact fills missing structured Contact fields at creation; existing values are preserved. For multiple targets, set contact data in meta.contact on each target object. Per-item meta replaces the entire top-level meta object; it is not deep-merged." }, "externalTaskId": { "type": "string", "description": "Reusable customer correlation/grouping ID; not an idempotency key" }, "contactListName": { "type": "string", "description": "Optional Contact List to enroll the contact into" } } }, { "type": "object", "required": [ "targets" ], "properties": { "targets": { "description": "Email addresses or per-recipient objects. Supply distinct meta.contact data per lead.", "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "string" }, "content": { "type": "string" }, "subject": { "type": "string" }, "meta": { "type": "object", "additionalProperties": true, "properties": { "contact": { "$ref": "#/components/schemas/TaskContactFields" } }, "description": "Per-recipient metadata replaces the entire top-level meta object." } } } } ] }, "content": { "type": "string", "description": "Email body applied to string targets" }, "subject": { "type": "string", "description": "Subject applied to string targets" }, "cc": { "description": "CC applied to string targets" }, "bcc": { "description": "BCC applied to string targets" }, "attachments": { "type": "array", "description": "Attachments applied to string targets" }, "context": { "type": "string" }, "taskContext": { "type": "string" }, "accountId": { "type": "integer" }, "agentId": { "type": "integer" }, "scheduledFor": { "type": "integer" }, "scheduleSpacingSec": { "type": "integer", "description": "If provided, stagger scheduledFor by this many seconds per index" }, "meta": { "type": "object", "additionalProperties": true, "properties": { "contact": { "$ref": "#/components/schemas/TaskContactFields" } }, "description": "Optional Task metadata. meta.contact fills missing structured Contact fields at creation; existing values are preserved. For multiple targets, set contact data in meta.contact on each target object. Per-item meta replaces the entire top-level meta object; it is not deep-merged." }, "externalTaskId": { "type": "string", "description": "Reusable correlation/grouping ID applied to all created Tasks" }, "contactListName": { "type": "string", "description": "Contact List to enroll every contact into" } } } ] }, "examples": { "single": { "summary": "Email a lead and populate their Contact", "value": { "target": "lead@example.com", "subject": "Your requested information", "content": "Here is the information you requested.", "meta": { "contact": { "name": "Example Person", "phone": "+15551234567", "address": { "state": "LA", "zip": "71101" }, "customFields": { "vendorLeadCode": "lead-123" } } } } } } } } } } }, "/api/v2/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List Webhooks", "description": "List all your existing webhook destinations.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "webhooks": { "type": "array", "items": { "type": "object", "properties": { "userId": { "description": "User Id", "type": "number", "example": 3 }, "label": { "description": "Friendly label for webhook", "type": "string", "example": "Zapier Hook" }, "timestamp": { "description": "Timestamp when created", "type": "number", "example": 1678829072 }, "url": { "description": "Webhook URL", "type": "string", "example": "https://hooks.zapier.com/hooks/catch/123456/abcdef" }, "type": { "description": "Webhook type", "type": "string", "example": "conversation" } } } } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Add Webhook", "description": "Add a new webhook destination.", "responses": { "200": { "description": "OK" }, "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook created successfully" }, "webhooks": { "type": "array", "items": { "type": "object", "properties": { "userId": { "description": "User Id", "type": "number", "example": 3 }, "label": { "description": "Friendly label for webhook", "type": "string", "example": "Zapier Hook" }, "timestamp": { "description": "Timestamp when created", "type": "number", "example": 1678829072 }, "url": { "description": "Webhook URL", "type": "string", "example": "https://hooks.zapier.com/hooks/catch/123456/abcdef" }, "type": { "description": "Webhook type", "type": "string", "example": "conversation" } } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "label", "type" ], "properties": { "url": { "description": "Webhook URL", "type": "string", "example": "https://hooks.zapier.com/hooks/catch/123456/abcdef" }, "label": { "description": "Friendly label for webhook", "type": "string", "example": "Zapier Hook" }, "type": { "description": "Webhook type", "type": "string", "enum": [ "conversation", "incoming", "contact", "agent", "onboarding", "opt_out" ], "example": "conversation" } } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Remove Webhook", "description": "Remove an existing webhook destination.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook deleted successfully" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "description": "Webhook URL to remove", "type": "string", "example": "https://hooks.zapier.com/hooks/catch/123456/abcdef" } } } } } } } }, "/api/v2/context": { "get": { "tags": [ "Knowledge" ], "summary": "Fetch Context", "description": "Fetch additional information context stored for conversations with a particular person.", "parameters": [ { "name": "target", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Phone number in E.164 format or VIDA username of the user" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "context": { "type": "string", "example": "Customer Name: John Doe, Car Model: Toyota Camry, Last Oil Change: 2023-05-15" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Knowledge" ], "summary": "Add Context", "description": "Injects additional information context your agent can use in conversations with a specific person.", "responses": { "200": { "description": "OK" }, "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Context added successfully" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "context" ], "properties": { "target": { "description": "Phone number in E.164 format or VIDA username of the user", "type": "string", "example": "+1234567890 or john_doe" }, "context": { "description": "Context information to inject", "type": "string", "example": "Customer Name: John Doe, Car Model: Toyota Camry, Last Oil Change: 2023-05-15" } } } } } } } }, "/api/v2/contact/list": { "get": { "tags": [ "Contacts" ], "summary": "List Contact Lists", "description": "Returns the distinct persisted Contact List labels for the organization.", "responses": { "default": { "description": "" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/contact/list/{listName}": { "get": { "tags": [ "Contacts" ], "summary": "List Contacts in a Contact List", "description": "Returns one bounded page of logical Contacts in the List. Existing physical duplicate rows are collapsed before membership is evaluated.", "parameters": [ { "name": "listName", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number starting at 1. Defaults to 1.", "schema": { "type": "integer" } }, { "name": "pageSize", "in": "query", "description": "Page size. Defaults to 20 and is capped at 100.", "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "description": "updatedAt, createdAt, id, name, email, or phone.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "asc or desc.", "schema": { "type": "string" } } ], "responses": { "default": { "description": "" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Contacts" ], "summary": "Add or refresh a Contact List membership", "description": "Creates the List implicitly when its first Contact is added. Re-adding a Contact refreshes one normalized membership timestamp.", "parameters": [ { "name": "listName", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Contact id." }, "score": { "type": "integer", "description": "Optional membership timestamp." } } } } } } }, "delete": { "tags": [ "Contacts" ], "summary": "Remove a Contact List membership", "description": "Removes every membership entry with the requested label. It does not infer or remove matching custom state.", "parameters": [ { "name": "listName", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Contact id." } } } } } } } }, "/api/v2/contact": { "get": { "tags": [ "Contacts" ], "summary": "Search and paginate Contacts", "description": "Searches logical organization Contacts in Postgres using the standard page and pageSize pagination contract.", "parameters": [ { "name": "q", "in": "query", "description": "Case-insensitive name, email, or phone search.", "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "Exact Contact id.", "schema": { "type": "string" } }, { "name": "phone", "in": "query", "description": "Exact phone.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "description": "Exact email.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Exact status.", "schema": { "type": "string" } }, { "name": "source", "in": "query", "description": "Exact contactSource.", "schema": { "type": "string" } }, { "name": "leadSource", "in": "query", "description": "Exact leadSource.", "schema": { "type": "string" } }, { "name": "list", "in": "query", "description": "Exact Contact List membership.", "schema": { "type": "string" } }, { "name": "customFieldPath", "in": "query", "description": "Exact nested path below customFields, for example objective.lastOutcome.", "schema": { "type": "string" } }, { "name": "customFieldValue", "in": "query", "description": "Exact string value required with customFieldPath.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number starting at 1. Defaults to 1.", "schema": { "type": "integer" } }, { "name": "pageSize", "in": "query", "description": "Page size. Defaults to 20 and is capped at 100.", "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "description": "updatedAt, createdAt, id, name, email, or phone.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "asc or desc.", "schema": { "type": "string" } } ], "responses": { "default": { "description": "" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Contacts" ], "summary": "Create or update a Contact", "description": "Creates a Contact or updates the matching Contact, then returns the persisted Contact. Resolve an existing person using id or target; provide phone or email to create one when no person is found. Provided top-level fields replace existing values; use PATCH for nested merges. See [Contact fields](https://vida.io/docs/api-reference/platform-guides/contacts-and-objectives#contact-fields) for the complete field reference.", "responses": { "default": { "description": "" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreate" }, "example": { "phone": "+15551234567", "name": "Example Person", "email": "lead@example.com", "address": { "state": "LA", "zip": "71101" }, "customFields": { "vendorLeadCode": "lead-123" } } } } } }, "delete": { "tags": [ "Contacts" ], "summary": "Delete a Contact", "description": "Permanently deletes the Contact identified by id from the selected organization.", "responses": { "default": { "description": "" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Contact id." } } } } } } } }, "/api/v2/contact/{contactId}/list/{listName}/state": { "patch": { "tags": [ "Contacts" ], "summary": "Enroll a Contact in an objective and merge its state", "description": "Atomically ensures List membership and recursively merges the request into customFields[listName]. Explicit null removes a field. A non-object collision returns 409.", "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "listName", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "409": { "description": "The matching customFields key contains non-object data." } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "delete": { "tags": [ "Contacts" ], "summary": "Remove a Contact from an objective and delete its state", "description": "Atomically removes every matching List membership and customFields[listName].", "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "listName", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/contact/{contactId}/logs": { "get": { "tags": [ "Contacts" ], "summary": "Fetch recent communication logs for a Contact", "description": "Returns a concise newest-first activity index without full transcripts. Logs with roomId and uuid include conversationRef for the existing conversation-detail API.", "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "One-based page number.", "schema": { "type": "integer" } }, { "name": "pageSize", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer" } }, { "name": "start", "in": "query", "description": "Unix timestamp; defaults to 90 days before end.", "schema": { "type": "integer" } }, { "name": "end", "in": "query", "description": "Unix timestamp; defaults to now.", "schema": { "type": "integer" } }, { "name": "type", "in": "query", "description": "Exact log type.", "schema": { "type": "string" } }, { "name": "eventType", "in": "query", "description": "Exact eventType.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "description": "Exact inbound or outbound direction.", "schema": { "type": "string" } } ], "responses": { "default": { "description": "" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/contact/{contactId}": { "get": { "tags": [ "Contacts" ], "summary": "Fetch one Contact", "description": "Returns one Contact in the selected organization by its stable Contact ID.", "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "" } }, "security": [ { "apiKeyAuth": [] } ] }, "patch": { "tags": [ "Contacts" ], "summary": "Partially update a Contact", "description": "Recursively merges allowed Contact fields. Explicit null removes a field; arrays and scalars replace. The final customFields object allows at most 20 top-level keys and 8192 UTF-8 bytes. Send Contact fields directly in the request body. See [Contact fields](https://vida.io/docs/api-reference/platform-guides/contacts-and-objectives#contact-fields).", "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactFields" }, "example": { "address": { "zip": "71101" }, "customFields": { "vendorLeadCode": "lead-123" }, "notes": null } } } } } }, "/api/v2/tasks": { "get": { "tags": [ "Tasks" ], "summary": "Fetch all tasks", "description": "Retrieve Tasks for the current organization. Each retry cadence remains one Task; attemptHistory contains its individual attempts. Exact filters may be combined, and meta. filters nested metadata values.", "parameters": [ { "name": "targetAccountId", "description": "Scope results to one agent account in the organization", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "description": "Max number of tasks to return (1-1000)", "example": 100, "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "description": "Offset for pagination", "example": 0, "in": "query", "schema": { "type": "integer" } }, { "name": "since", "description": "Filter by updatedAt >= since (unix seconds)", "example": 1712345678, "in": "query", "schema": { "type": "integer" } }, { "name": "until", "description": "Filter by updatedAt <= until (unix seconds)", "example": 1712349999, "in": "query", "schema": { "type": "integer" } }, { "name": "sort", "description": "Sort field (createdAt, updatedAt, scheduledFor)", "example": "createdAt", "in": "query", "schema": { "type": "string" } }, { "name": "order", "description": "Sort order (asc or desc)", "example": "desc", "in": "query", "schema": { "type": "string" } }, { "name": "id", "description": "Exact Task UUID", "in": "query", "schema": { "type": "string" } }, { "name": "type", "description": "Exact Task type", "schema": { "type": "string", "enum": [ "call", "text", "email", "ping", "computer", "repeating", "cronOneOff" ] }, "in": "query" }, { "name": "state", "description": "Exact Task state", "schema": { "type": "string", "enum": [ "pending", "processing", "running", "finished", "errored", "canceled", "active", "paused" ] }, "in": "query" }, { "name": "contactId", "description": "Exact Contact ID stored on the Task", "in": "query", "schema": { "type": "string" } }, { "name": "agentId", "description": "Exact agent/campaign ID stored on the Task", "in": "query", "schema": { "type": "string" } }, { "name": "convoId", "description": "Exact conversation UUID", "in": "query", "schema": { "type": "string" } }, { "name": "room", "description": "Exact conversation room ID", "in": "query", "schema": { "type": "string" } }, { "name": "accountId", "description": "Exact agent account ID", "in": "query", "schema": { "type": "integer" } }, { "name": "scheduledFor", "description": "Exact scheduled Unix timestamp", "in": "query", "schema": { "type": "integer" } }, { "name": "createdAt", "description": "Exact created Unix timestamp", "in": "query", "schema": { "type": "integer" } }, { "name": "updatedAt", "description": "Exact updated Unix timestamp", "in": "query", "schema": { "type": "integer" } }, { "name": "batchId", "description": "Exact server-generated submission batch UUID", "in": "query", "schema": { "type": "string" } }, { "name": "externalTaskId", "description": "Exact reusable caller-defined correlation/grouping id", "in": "query", "schema": { "type": "string" } }, { "name": "contactListName", "description": "Exact Contact List associated with the task", "in": "query", "schema": { "type": "string" } }, { "name": "meta.source", "description": "Exact metadata match. Replace source with a nested metadata path such as meta.crm.leadId.", "example": "crm", "in": "query", "schema": { "type": "string" } }, { "name": "outcome", "description": "Task outcome (goal_met, terminal_negative, goal_incomplete, or retries_exhausted)", "example": "goal_met", "in": "query", "schema": { "type": "string" } }, { "name": "q", "description": "Search by phone number, externalTaskId, or task id", "example": "+12025550123", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of tasks", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "total": { "type": "number", "example": 123 }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "task1" }, "type": { "type": "string", "example": "call" }, "state": { "type": "string", "example": "pending" }, "target": { "type": "string", "example": "+15551234567" }, "createdAt": { "type": "number", "example": 1712345678 } } } } }, "xml": { "name": "main" } } }, "application/xml": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "total": { "type": "number", "example": 123 }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "task1" }, "type": { "type": "string", "example": "call" }, "state": { "type": "string", "example": "pending" }, "target": { "type": "string", "example": "+15551234567" }, "createdAt": { "type": "number", "example": 1712345678 } } } } }, "xml": { "name": "main" } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Target account is outside the organization" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Tasks" ], "summary": "Create a new task", "description": "Creates communication, scheduled, or Computer Agent work. Computer Tasks run only on provisioned Computer Agents and preserve their complete work in a linked conversation.", "responses": { "201": { "description": "Task created successfully" }, "400": { "description": "Invalid Task, goal, or retry policy" }, "401": { "description": "Unauthorized" }, "409": { "description": "An active retryable Task already exists for this agent and contact" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreate" } } } } } }, "/api/v2/tasks/csv": { "post": { "tags": [ "Tasks" ], "summary": "Create multiple tasks via CSV upload", "description": "Upload up to 10,000 Tasks. Standard Task headers are case-insensitive; custom meta paths retain their casing. Recognized columns are type, target, context, taskContext, greeting, waitToGreet, accountId, scheduledFor, message, externalTaskId, goal.description, goal.completionCriteria, retryPolicy.delaysSeconds, retryPolicy.retryOn, and retryPolicy.responseTimeoutSeconds. Arbitrary nested meta. columns are also accepted. For call, text and email Tasks, meta.contact fields populate missing structured Contact fields in the Task organization at creation, including meta.contact.name, meta.contact.email, meta.contact.address.state and meta.contact.customFields.vendorLeadCode. Existing values are preserved, nested objects fill missing leaves, and null or blank values are ignored. Names in context do not populate Contact fields. Target remains the delivery destination and the global profile and outbound caller ID are unchanged. CSV metadata cells are strings; use JSON Task creation for boolean, numeric or array Contact values. Retry list columns accept JSON arrays or pipe-separated values. Email tasks can use meta.email.subject.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "string" }, "maxLength": { "type": "number", "example": 200 } } }, "description": "Required for uploads over 1,000 rows. Repeating the same key and payload safely resumes or returns that submission; reusing it for a different payload returns 409." } ], "responses": { "200": { "description": "Tasks queued" }, "202": { "description": "Large Task submission accepted for asynchronous creation" }, "400": { "description": "Invalid CSV or missing required fields" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "409": { "description": "Idempotency-Key was already used for a different payload" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "csv" ], "properties": { "csv": { "type": "string", "format": "binary", "description": "CSV file" }, "contactListName": { "type": "string", "description": "Optional Contact List to enroll every task contact into" } } }, "encoding": { "csv": { "contentType": "text/csv" } } } } } } }, "/api/v2/tasks/stats": { "get": { "tags": [ "Tasks" ], "summary": "Task statistics", "description": "Get Task counts by state and conversion results for each attempt number.", "parameters": [ { "name": "targetAccountId", "description": "Scope statistics to one agent account in the organization", "in": "query", "schema": { "type": "integer" } }, { "name": "batchId", "description": "Limit counts to one server-generated submission batch UUID", "in": "query", "schema": { "type": "string" } }, { "name": "contactListName", "description": "Limit counts to tasks associated with one Contact List", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "total": { "type": "number", "example": 10 }, "byState": { "type": "object", "properties": { "pending": { "type": "number", "example": 2 }, "running": { "type": "number", "example": 3 }, "finished": { "type": "number", "example": 5 } } }, "attemptCohortSize": { "type": "number", "example": 8 }, "byAttempt": { "type": "array", "items": { "type": "object", "properties": { "attemptNumber": { "type": "number", "example": 1 }, "reached": { "type": "number", "example": 8 }, "goalMet": { "type": "number", "example": 2 }, "conditionalGoalMetRate": { "type": "number", "example": 0.25 }, "incrementalGoalMetRate": { "type": "number", "example": 0.25 }, "cumulativeGoalMetRate": { "type": "number", "example": 0.25 }, "byChannel": { "type": "object", "properties": { "call": { "type": "number", "example": 8 } } }, "byDisposition": { "type": "object", "properties": { "no_answer": { "type": "number", "example": 6 }, "goal_met": { "type": "number", "example": 2 } } }, "byOutcome": { "type": "object", "properties": { "not_evaluated": { "type": "number", "example": 6 }, "goal_met": { "type": "number", "example": 2 } } } } } } }, "xml": { "name": "main" } } }, "application/xml": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "total": { "type": "number", "example": 10 }, "byState": { "type": "object", "properties": { "pending": { "type": "number", "example": 2 }, "running": { "type": "number", "example": 3 }, "finished": { "type": "number", "example": 5 } } }, "attemptCohortSize": { "type": "number", "example": 8 }, "byAttempt": { "type": "array", "items": { "type": "object", "properties": { "attemptNumber": { "type": "number", "example": 1 }, "reached": { "type": "number", "example": 8 }, "goalMet": { "type": "number", "example": 2 }, "conditionalGoalMetRate": { "type": "number", "example": 0.25 }, "incrementalGoalMetRate": { "type": "number", "example": 0.25 }, "cumulativeGoalMetRate": { "type": "number", "example": 0.25 }, "byChannel": { "type": "object", "properties": { "call": { "type": "number", "example": 8 } } }, "byDisposition": { "type": "object", "properties": { "no_answer": { "type": "number", "example": 6 }, "goal_met": { "type": "number", "example": 2 } } }, "byOutcome": { "type": "object", "properties": { "not_evaluated": { "type": "number", "example": 6 }, "goal_met": { "type": "number", "example": 2 } } } } } } }, "xml": { "name": "main" } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Target account is outside the organization" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/tasks/batches": { "post": { "tags": [ "Tasks" ], "summary": "Create a task batch", "description": "Create up to 10,000 Tasks from either an explicit tasks array or a Contact List plus one Task template. Each Task uses the same fields and retry contract as POST /api/v2/tasks. Submissions over 1,000 Tasks require Idempotency-Key and return 202 while they are created.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "string" }, "maxLength": { "type": "number", "example": 200 } } }, "description": "Required for submissions over 1,000 Tasks. Repeating the same key and payload safely resumes or returns that submission; reusing it for a different payload returns 409." } ], "responses": { "201": { "description": "Task batch created" }, "202": { "description": "Large Task submission accepted for asynchronous creation" }, "400": { "description": "Invalid Task template or Contact List" }, "401": { "description": "Unauthorized" }, "409": { "description": "Idempotency-Key was already used for a different payload" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "minItems": 1, "maxItems": 10000, "description": "Explicit Task objects. Each requires type; call, text, and email also require target.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "call", "text", "email", "ping" ] }, "target": { "type": "string" }, "accountId": { "type": "integer" }, "context": { "type": "string" }, "taskContext": { "type": "string" }, "greeting": { "type": "string" }, "waitToGreet": { "type": "boolean" }, "message": { "type": "string" }, "scheduledFor": { "type": "integer" }, "externalTaskId": { "type": "string", "description": "Reusable correlation/grouping ID, not an idempotency key" }, "contactListName": { "type": "string" }, "goal": { "type": "object", "nullable": true, "description": "Requires completionCriteria; omitted or null inherits the organization default" }, "retryPolicy": { "type": "object", "nullable": true, "description": "Supports delaysSeconds or mixed-channel steps plus retryOn and responseTimeoutSeconds; omitted or null inherits the organization default" }, "meta": { "type": "object", "properties": { "contact": { "$ref": "#/components/schemas/TaskContactFields" } }, "additionalProperties": true } } } }, "contactListName": { "type": "string", "description": "Create one Task for every eligible Contact List member" }, "task": { "type": "object", "description": "Task template without target for the selected Contact List. Supports call, text, and email and the same goal/retryPolicy fields as POST /api/v2/tasks." } } } } } } }, "get": { "tags": [ "Tasks" ], "summary": "Recent task batches", "description": "List recent server-generated submission batches. Single-task batches are excluded unless includeSingles is true.", "parameters": [ { "name": "targetAccountId", "description": "Scope batches to one agent account in the organization", "in": "query", "schema": { "type": "integer" } }, { "name": "accountId", "description": "Exact agent account ID", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "description": "Maximum batches to return (1-100)", "example": 50, "in": "query", "schema": { "type": "integer" } }, { "name": "includeSingles", "description": "Include batches containing one task", "example": false, "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Recent Task batches", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "batches": { "type": "array", "items": { "type": "object", "properties": { "batchId": { "type": "string", "example": "f52b1e01-5cbc-483c-9939-3bf7d37e1426" }, "submittedAt": { "type": "number", "example": 1712345678 }, "source": { "type": "string", "example": "api/tasks" }, "total": { "type": "number", "example": 100 }, "byState": { "type": "object", "properties": { "pending": { "type": "number", "example": 80 }, "finished": { "type": "number", "example": 20 } } } } } } }, "xml": { "name": "main" } } }, "application/xml": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "batches": { "type": "array", "items": { "type": "object", "properties": { "batchId": { "type": "string", "example": "f52b1e01-5cbc-483c-9939-3bf7d37e1426" }, "submittedAt": { "type": "number", "example": 1712345678 }, "source": { "type": "string", "example": "api/tasks" }, "total": { "type": "number", "example": 100 }, "byState": { "type": "object", "properties": { "pending": { "type": "number", "example": 80 }, "finished": { "type": "number", "example": 20 } } } } } } }, "xml": { "name": "main" } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Target account is outside the organization" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/tasks/batches/{batchId}": { "get": { "tags": [ "Tasks" ], "summary": "Fetch task batch status", "description": "Fetch the creation status of an asynchronous Task submission. Status records are available for seven days. Possible statuses are queued, processing, canceled, completed, completed_with_errors, and failed. Up to 100 row errors are returned.", "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Server-generated asynchronous batch UUID" } ], "responses": { "200": { "description": "Task batch submission status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "batchId": { "type": "string", "example": "f52b1e01-5cbc-483c-9939-3bf7d37e1426" }, "status": { "type": "string", "example": "processing" }, "source": { "type": "string", "example": "api/tasks" }, "submitted": { "type": "number", "example": 2500 }, "processed": { "type": "number", "example": 1250 }, "inserted": { "type": "number", "example": 1248 }, "rejected": { "type": "number", "example": 2 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "rowIndex": { "type": "number", "example": 14 }, "externalTaskId": { "type": "string", "example": "lead-14" }, "message": { "type": "string", "example": "Invalid target" } } } }, "createdAt": { "type": "number", "example": 1712345678 }, "updatedAt": { "type": "number", "example": 1712345700 } }, "xml": { "name": "main" } } }, "application/xml": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "batchId": { "type": "string", "example": "f52b1e01-5cbc-483c-9939-3bf7d37e1426" }, "status": { "type": "string", "example": "processing" }, "source": { "type": "string", "example": "api/tasks" }, "submitted": { "type": "number", "example": 2500 }, "processed": { "type": "number", "example": 1250 }, "inserted": { "type": "number", "example": 1248 }, "rejected": { "type": "number", "example": 2 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "rowIndex": { "type": "number", "example": 14 }, "externalTaskId": { "type": "string", "example": "lead-14" }, "message": { "type": "string", "example": "Invalid target" } } } }, "createdAt": { "type": "number", "example": 1712345678 }, "updatedAt": { "type": "number", "example": 1712345700 } }, "xml": { "name": "main" } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Task batch submission not found or expired" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/tasks/dailyCounts": { "get": { "tags": [ "Tasks" ], "summary": "Daily counts", "description": "Get the organization’s current daily call, text, and total Task counts.", "responses": { "200": { "description": "Daily counts", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "counts": { "type": "object", "properties": { "calls": { "type": "number", "example": 5 }, "texts": { "type": "number", "example": 12 }, "tasks": { "type": "number", "example": 17 }, "date": { "type": "string", "example": "2025-08-20" } } } }, "xml": { "name": "main" } } }, "application/xml": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "counts": { "type": "object", "properties": { "calls": { "type": "number", "example": 5 }, "texts": { "type": "number", "example": 12 }, "tasks": { "type": "number", "example": 17 }, "date": { "type": "string", "example": "2025-08-20" } } } }, "xml": { "name": "main" } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/tasks/limits": { "get": { "tags": [ "Tasks" ], "summary": "Fetch task limits", "description": "Retrieve the org’s current task limits configuration. Business hours use a timezone plus grouped windows; days are 0 (Sunday) through 6 (Saturday).", "responses": { "200": { "description": "Limits", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "limits": { "type": "object", "properties": { "businessHours": { "type": "object", "properties": { "timezone": { "type": "string", "example": "America/Chicago" }, "windows": { "type": "array", "items": { "type": "object", "properties": { "days": { "type": "array", "example": [ 5 ], "items": { "type": "number" } }, "start": { "type": "string", "example": "09:00" }, "end": { "type": "string", "example": "15:00" } } } } } }, "daily": { "type": "object", "properties": { "calls": { "type": "number", "example": 100 }, "texts": { "type": "number", "example": 200 }, "tasks": { "type": "number", "example": 300 } } }, "maxConcurrentCalls": { "type": "number", "example": 10 }, "callsPerSecond": { "type": "number", "example": 1 }, "cooldowns": { "type": "object", "properties": { "calls": { "type": "number", "example": 86400 }, "texts": { "type": "number", "example": 300 } } }, "defaultRetryConfiguration": { "type": "object", "properties": { "goal": { "type": "object", "properties": { "completionCriteria": { "type": "string", "example": "The contact schedules an appointment." } } }, "retryPolicy": { "type": "object", "properties": { "delaysSeconds": { "type": "array", "example": [ 86400, 259200 ], "items": { "type": "number" } }, "retryOn": { "type": "array", "example": [ "no_answer", "voicemail", "goal_incomplete" ], "items": { "type": "string" } }, "responseTimeoutSeconds": { "type": "number", "example": 86400 } } } } } } } }, "xml": { "name": "main" } } }, "application/xml": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "limits": { "type": "object", "properties": { "businessHours": { "type": "object", "properties": { "timezone": { "type": "string", "example": "America/Chicago" }, "windows": { "type": "array", "items": { "type": "object", "properties": { "days": { "type": "array", "example": [ 5 ], "items": { "type": "number" } }, "start": { "type": "string", "example": "09:00" }, "end": { "type": "string", "example": "15:00" } } } } } }, "daily": { "type": "object", "properties": { "calls": { "type": "number", "example": 100 }, "texts": { "type": "number", "example": 200 }, "tasks": { "type": "number", "example": 300 } } }, "maxConcurrentCalls": { "type": "number", "example": 10 }, "callsPerSecond": { "type": "number", "example": 1 }, "cooldowns": { "type": "object", "properties": { "calls": { "type": "number", "example": 86400 }, "texts": { "type": "number", "example": 300 } } }, "defaultRetryConfiguration": { "type": "object", "properties": { "goal": { "type": "object", "properties": { "completionCriteria": { "type": "string", "example": "The contact schedules an appointment." } } }, "retryPolicy": { "type": "object", "properties": { "delaysSeconds": { "type": "array", "example": [ 86400, 259200 ], "items": { "type": "number" } }, "retryOn": { "type": "array", "example": [ "no_answer", "voicemail", "goal_incomplete" ], "items": { "type": "string" } }, "responseTimeoutSeconds": { "type": "number", "example": 86400 } } } } } } } }, "xml": { "name": "main" } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Tasks" ], "summary": "Update task limits", "description": "Updates organization Task settings such as business hours, per-target cooldowns, and default retry behavior. Reseller administrators can also update call capacity. Set businessHours or defaultRetryConfiguration to null to disable that behavior.", "responses": { "200": { "description": "Limits updated successfully" }, "400": { "description": "Invalid Task settings" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "businessHours": { "type": "object", "description": "Timezone plus grouped availability windows.", "example": { "timezone": "America/Chicago", "windows": [ { "days": [ 1, 2, 3, 4 ], "start": "08:00", "end": "18:00" }, { "days": [ 5 ], "start": "09:00", "end": "15:00" }, { "days": [ 6 ], "start": "09:00", "end": "12:00" } ] } }, "cooldowns": { "type": "object", "description": "Minimum seconds between Tasks for the same target and channel", "properties": { "calls": { "type": "integer", "minimum": 0 }, "texts": { "type": "integer", "minimum": 0 }, "tasks": { "type": "integer", "minimum": 0 } } }, "maxConcurrentCalls": { "type": "integer", "minimum": 1, "description": "Maximum simultaneous active Task calls" }, "callsPerSecond": { "type": "integer", "minimum": 1, "description": "Maximum Task call starts per second" }, "defaultRetryConfiguration": { "type": "object", "nullable": true, "description": "Complete organization default applied when a call, text, or email Task omits either its goal or retryPolicy. Defaults use same-channel delaysSeconds; null disables the organization default.", "required": [ "goal", "retryPolicy" ], "properties": { "goal": { "type": "object", "required": [ "completionCriteria" ], "properties": { "completionCriteria": { "type": "string" } } }, "retryPolicy": { "type": "object", "required": [ "delaysSeconds", "retryOn" ], "properties": { "delaysSeconds": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "integer", "minimum": 60, "maximum": 2592000 } }, "retryOn": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "busy", "delivery_failed", "goal_incomplete", "no_answer", "no_response", "no_speech", "rejected", "transient_failure", "voicemail" ] } }, "responseTimeoutSeconds": { "type": "integer", "minimum": 60, "maximum": 604800 } } } } } } } } } } } }, "/api/v2/tasks/{taskId}": { "get": { "tags": [ "Tasks" ], "summary": "Fetch a specific task", "description": "Retrieve one Task and all of its attempts. When the Task has an associated room, chatRef links directly to its scoped Vida chat. attemptHistory includes each attempt’s channel, timing, disposition, evaluation, outcomes, experiment assignment, provider reference, voicemail or delivery details, and conversation UUID when available. The Task and each attempt include logsRef; conversationRef links directly to one available communication conversation and transcript.", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task ID" }, { "name": "targetAccountId", "description": "Require the Task to belong to this agent account in the organization", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Task found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "task": { "type": "object", "properties": { "id": { "type": "string", "example": "task1" }, "batchId": { "type": "string", "example": "f52b1e01-5cbc-483c-9939-3bf7d37e1426" }, "externalTaskId": { "type": "string", "example": "lead-42" }, "type": { "type": "string", "example": "call" }, "state": { "type": "string", "example": "finished" }, "target": { "type": "string", "example": "+15551234567" }, "goal": { "type": "object", "properties": { "completionCriteria": { "type": "string", "example": "The contact agrees to a meeting" } } }, "retryPolicy": { "type": "object", "properties": { "delaysSeconds": { "type": "array", "example": [ 86400 ], "items": { "type": "number" } }, "retryOn": { "type": "array", "example": [ "no_answer", "goal_incomplete" ], "items": { "type": "string" } } } }, "attemptHistory": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "attempt-id" }, "number": { "type": "number", "example": 1 }, "state": { "type": "string", "example": "resolved" }, "channel": { "type": "string", "example": "call" }, "disposition": { "type": "string", "example": "goal_met" }, "scheduledAt": { "type": "number", "example": 1712345678 }, "dispatchedAt": { "type": "number", "example": 1712345680 }, "resolvedAt": { "type": "number", "example": 1712345900 }, "convoUUID": { "type": "string", "example": "conversation-uuid" }, "outcomes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "task_goal" }, "status": { "type": "string", "example": "evaluated" }, "value": { "type": "boolean", "example": true }, "terminal": { "type": "boolean", "example": true } } } }, "logsRef": { "type": "object", "properties": { "taskId": { "type": "string", "example": "task1" }, "attemptId": { "type": "string", "example": "attempt-id" }, "href": { "type": "string", "example": "/api/v2/tasks/task1/logs?attemptId=attempt-id" } } } } } }, "result": { "type": "object", "properties": { "disposition": { "type": "string", "example": "goal_met" }, "terminalReason": { "type": "string", "example": "goal_met" } } }, "chatRef": { "type": "object", "properties": { "roomId": { "type": "string", "example": "room-id" }, "targetAccountId": { "type": "number", "example": 3026480 }, "href": { "type": "string", "example": "/api/v2/messages/room-id?targetAccountId=3026480" } } }, "logsRef": { "type": "object", "properties": { "taskId": { "type": "string", "example": "task1" }, "href": { "type": "string", "example": "/api/v2/tasks/task1/logs" } } } } } }, "xml": { "name": "main" } } }, "application/xml": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "task": { "type": "object", "properties": { "id": { "type": "string", "example": "task1" }, "batchId": { "type": "string", "example": "f52b1e01-5cbc-483c-9939-3bf7d37e1426" }, "externalTaskId": { "type": "string", "example": "lead-42" }, "type": { "type": "string", "example": "call" }, "state": { "type": "string", "example": "finished" }, "target": { "type": "string", "example": "+15551234567" }, "goal": { "type": "object", "properties": { "completionCriteria": { "type": "string", "example": "The contact agrees to a meeting" } } }, "retryPolicy": { "type": "object", "properties": { "delaysSeconds": { "type": "array", "example": [ 86400 ], "items": { "type": "number" } }, "retryOn": { "type": "array", "example": [ "no_answer", "goal_incomplete" ], "items": { "type": "string" } } } }, "attemptHistory": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "attempt-id" }, "number": { "type": "number", "example": 1 }, "state": { "type": "string", "example": "resolved" }, "channel": { "type": "string", "example": "call" }, "disposition": { "type": "string", "example": "goal_met" }, "scheduledAt": { "type": "number", "example": 1712345678 }, "dispatchedAt": { "type": "number", "example": 1712345680 }, "resolvedAt": { "type": "number", "example": 1712345900 }, "convoUUID": { "type": "string", "example": "conversation-uuid" }, "outcomes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "task_goal" }, "status": { "type": "string", "example": "evaluated" }, "value": { "type": "boolean", "example": true }, "terminal": { "type": "boolean", "example": true } } } }, "logsRef": { "type": "object", "properties": { "taskId": { "type": "string", "example": "task1" }, "attemptId": { "type": "string", "example": "attempt-id" }, "href": { "type": "string", "example": "/api/v2/tasks/task1/logs?attemptId=attempt-id" } } } } } }, "result": { "type": "object", "properties": { "disposition": { "type": "string", "example": "goal_met" }, "terminalReason": { "type": "string", "example": "goal_met" } } }, "chatRef": { "type": "object", "properties": { "roomId": { "type": "string", "example": "room-id" }, "targetAccountId": { "type": "number", "example": 3026480 }, "href": { "type": "string", "example": "/api/v2/messages/room-id?targetAccountId=3026480" } } }, "logsRef": { "type": "object", "properties": { "taskId": { "type": "string", "example": "task1" }, "href": { "type": "string", "example": "/api/v2/tasks/task1/logs" } } } } } }, "xml": { "name": "main" } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Target account is outside the organization" }, "404": { "description": "Task not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Tasks" ], "summary": "Update a task", "description": "Updates a Task by ID. Repeating and cronOneOff Tasks support title, taskContext, state, and cronSchedule. Computer Tasks and retryable communication Tasks can only be canceled.", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task ID" }, { "name": "targetAccountId", "in": "query", "description": "Require the Task to belong to this agent account in the organization", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Task updated successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Target account is outside the organization" }, "404": { "description": "Task not found" }, "409": { "description": "Task cannot be updated in its current state" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "description": "Repeating and cronOneOff Tasks accept active or paused", "example": "paused" }, "title": { "type": "string" }, "context": { "type": "string", "description": "Contact/background context for communication Tasks" }, "taskContext": { "type": "string", "description": "Instructions for a repeating or cronOneOff Task", "example": "Review the last complete hour and report material changes" }, "cronSchedule": { "type": "object", "description": "Schedule for a repeating or cronOneOff Task" }, "greeting": { "type": "string" }, "waitToGreet": { "type": "boolean", "example": true }, "message": { "type": "string" }, "scheduledFor": { "type": "integer" }, "externalTaskId": { "type": "string" }, "meta": { "type": "object" } } } } } } }, "delete": { "tags": [ "Tasks" ], "summary": "Delete a task", "description": "Deletes a non-retry Task and its schedule when applicable. Active Computer Agent work is stopped first. Active retryable communication Tasks are canceled and kept for history; completed retryable Tasks cannot be deleted.", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task ID" }, { "name": "targetAccountId", "in": "query", "description": "Require the Task to belong to this agent account in the organization", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Task deleted successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Target account is outside the organization" }, "404": { "description": "Task not found" }, "409": { "description": "Terminal retryable Task history cannot be deleted" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/tasks/{taskId}/run": { "post": { "tags": [ "Tasks" ], "summary": "Run a scheduled Task", "description": "Starts one repeating or cronOneOff Task immediately or when due. A 202 response means the run was accepted, not completed.", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task ID" }, { "name": "targetAccountId", "in": "query", "description": "Require the Task to belong to this agent account in the organization", "schema": { "type": "integer" } } ], "responses": { "202": { "description": "Task run accepted" }, "400": { "description": "Invalid run mode" }, "401": { "description": "Unauthorized" }, "403": { "description": "Target account is outside the organization" }, "404": { "description": "Task not found in the selected account scope" }, "409": { "description": "Task cannot be run" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "force", "due" ], "default": "force" } } } } } } } }, "/api/v2/tasks/{taskId}/runs": { "get": { "tags": [ "Tasks" ], "summary": "List scheduled Task runs", "description": "Returns paginated terminal run summaries for one repeating or cronOneOff Task. Use the Task chatRef for live work and tool activity; an empty terminal history while work is active does not prove that no run started.", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task ID" }, { "name": "targetAccountId", "in": "query", "description": "Require the Task to belong to this agent account in the organization", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Task run history" }, "400": { "description": "Invalid filters or pagination" }, "401": { "description": "Unauthorized" }, "403": { "description": "Target account is outside the organization" }, "404": { "description": "Task not found in the selected account scope" }, "409": { "description": "Task does not have run history" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/tasks/{taskId}/logs": { "get": { "tags": [ "Tasks" ], "summary": "Fetch communication logs for a task", "description": "Return Task communication logs newest first. Full transcripts are omitted from this list; use conversationRef.href to fetch conversation details and the transcript when available.", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task ID" }, { "name": "targetAccountId", "description": "Require the Task to belong to this agent account in the organization", "in": "query", "schema": { "type": "integer" } }, { "name": "attemptId", "in": "query", "description": "Optional exact task attempt ID.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "One-based page number.", "schema": { "type": "integer" } }, { "name": "pageSize", "in": "query", "description": "Page size, capped at 100.", "schema": { "type": "integer" } }, { "name": "start", "in": "query", "description": "Optional Unix timestamp; defaults to task creation.", "schema": { "type": "integer" } }, { "name": "end", "in": "query", "description": "Optional Unix timestamp; defaults to now.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Task activity logs without embedded transcripts", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "taskId": { "type": "string", "example": "task1" }, "logs": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "example": "conversation-uuid" }, "roomId": { "type": "string", "example": "room-id" }, "taskId": { "type": "string", "example": "task1" }, "taskAttemptId": { "type": "string", "example": "attempt-id" }, "hasTranscript": { "type": "boolean", "example": true }, "conversationRef": { "type": "object", "properties": { "roomId": { "type": "string", "example": "room-id" }, "uuid": { "type": "string", "example": "conversation-uuid" }, "href": { "type": "string", "example": "/api/v2/conversation/room-id/conversation-uuid" } } } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "example": 1 }, "pageSize": { "type": "number", "example": 20 }, "totalCount": { "type": "number", "example": 1 } } } }, "xml": { "name": "main" } } }, "application/xml": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "taskId": { "type": "string", "example": "task1" }, "logs": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "example": "conversation-uuid" }, "roomId": { "type": "string", "example": "room-id" }, "taskId": { "type": "string", "example": "task1" }, "taskAttemptId": { "type": "string", "example": "attempt-id" }, "hasTranscript": { "type": "boolean", "example": true }, "conversationRef": { "type": "object", "properties": { "roomId": { "type": "string", "example": "room-id" }, "uuid": { "type": "string", "example": "conversation-uuid" }, "href": { "type": "string", "example": "/api/v2/conversation/room-id/conversation-uuid" } } } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "example": 1 }, "pageSize": { "type": "number", "example": 20 }, "totalCount": { "type": "number", "example": 1 } } } }, "xml": { "name": "main" } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Target account is outside the organization" }, "404": { "description": "Task not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/tasks/cancel": { "post": { "tags": [ "Tasks" ], "summary": "Cancel queued tasks", "description": "Atomically cancel pending Tasks without deleting their audit history. Provide exactly one selector: taskIds, batchId, or allPending=true. Running and terminal selected or batch Tasks are reported as skipped. Cancellation does not interrupt an in-flight attempt.", "parameters": [ { "name": "targetAccountId", "in": "query", "required": false, "description": "Limit cancellation to one agent account in the organization", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Cancellation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "requested": { "type": "number", "example": 3 }, "matched": { "type": "number", "example": 3 }, "canceled": { "type": "number", "example": 2 }, "skipped": { "type": "number", "example": 1 }, "batchId": { "type": "string", "example": "f52b1e01-5cbc-483c-9939-3bf7d37e1426" }, "canceledTaskIds": { "type": "array", "example": [ "task-id-1", "task-id-2" ], "items": { "type": "string" } } }, "xml": { "name": "main" } } }, "application/xml": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "requested": { "type": "number", "example": 3 }, "matched": { "type": "number", "example": 3 }, "canceled": { "type": "number", "example": 2 }, "skipped": { "type": "number", "example": 1 }, "batchId": { "type": "string", "example": "f52b1e01-5cbc-483c-9939-3bf7d37e1426" }, "canceledTaskIds": { "type": "array", "example": [ "task-id-1", "task-id-2" ], "items": { "type": "string" } } }, "xml": { "name": "main" } } } } }, "400": { "description": "Invalid selection" }, "401": { "description": "Unauthorized" }, "403": { "description": "Target account is outside the organization" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskIds": { "type": "array", "maxItems": 1000, "items": { "type": "string" } }, "batchId": { "type": "string", "description": "Cancel every pending task in this submission batch" }, "allPending": { "type": "boolean", "example": false } } } } } } } }, "/api/v2/createReseller": { "post": { "tags": [ "Accounts" ], "summary": "Create a new reseller", "description": "Create a new reseller under your partner account. Partner account required.", "parameters": [ { "name": "targetPartnerId", "in": "query", "description": "Partner Id to create reseller in", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "201": { "description": "Reseller created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Reseller created" }, "organization": { "type": "string", "example": "New Reseller object" } } } } } }, "400": { "description": "Bad Request" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "resellerName" ], "properties": { "email": { "description": "Admin user email for this account", "type": "string", "example": "admin@acmesolar.com" }, "resellerName": { "description": "Reseller Name", "type": "string", "example": "Acme Solar" }, "offeredProductPlanId": { "description": "Offered Product Plan. Requires the Reseller to accept and checkout.", "type": "string", "example": "custom-plan-1" }, "productPlanId": { "description": "Product Plan to set on the account. Otherwise default sell plan is used", "type": "string", "example": "base-plan-1" }, "hipaaEnabledDefault": { "description": "Default HipaaEnabled settings for organizations under the reseller", "type": "boolean", "example": false }, "resellerStatus": { "description": "Reseller status. Defaults to enabled.", "type": "string", "enum": [ "enabled", "disabled" ], "example": "enabled" } } } } } } } }, "/api/v2/listResellers": { "get": { "tags": [ "Accounts" ], "summary": "List resellers", "description": "List all of your resellers. Partner account required.", "parameters": [ { "name": "targetPartnerId", "in": "query", "description": "Partner Id to list resellers in", "required": true, "schema": { "type": "string" } }, { "name": "pagination", "in": "query", "description": "Whether to provide pagination", "required": false, "example": true, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Page number to fetch", "required": false, "example": 0, "schema": { "type": "number" } }, { "name": "pageSize", "in": "query", "description": "How many resellers per page", "required": false, "example": 20, "schema": { "type": "number" } }, { "name": "active", "in": "query", "description": "Whether to return only resellers with this given active state", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/createOrganization": { "post": { "tags": [ "Accounts" ], "summary": "Create a new organization", "description": "Creates an organization under your reseller account (reseller auth required).", "parameters": [ { "name": "targetResellerId", "in": "query", "description": "Reseller-ID under which the org will be created", "required": true, "example": "2286", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Organization successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Organization created" }, "organization": { "type": "object", "description": "Created organization object" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "orgName" ], "properties": { "email": { "description": "Admin-user e-mail for the new org", "type": "string", "example": "admin@acmesolar.com" }, "orgName": { "description": "Organization name", "type": "string", "example": "Acme Solar" }, "accountName": { "description": "Default agent name for the organization", "type": "string", "example": "Acme Support" }, "orgAccountType": { "description": "Organization account type. Internal orgs are billed through reseller usage; customer orgs are eligible for full subscriptions. Defaults to customer.", "type": "string", "enum": [ "internal", "customer" ], "example": "customer" }, "productPlanId": { "description": "Product-plan ID. If omitted, defaults to your reseller sell-plan.", "type": "string", "example": "pplan-basic-monthly" }, "offeredProductPlanId": { "description": "Give an offered product plan to the organization (same behavior as updateOrganization)", "type": "string", "example": "pplan-basic-monthly" }, "externalAccountId": { "description": "Your own CRM/customer ID for this org", "type": "string", "example": "external-org-12345" }, "externalBillingId": { "description": "External Id to match with your internal billing system", "type": "string", "example": "billing-id-12345" }, "hipaaSetting": { "description": "HIPAA setting for this organization. on|off|inherit (inherit from reseller)", "type": "string", "enum": [ "on", "off", "inherit" ], "default": "inherit" }, "numberingProviders": { "description": "Array of numbering provider configurations", "type": "array", "items": { "type": "object", "required": [ "providerId", "config" ], "properties": { "providerId": { "type": "string", "example": "Twilio" }, "default": { "type": "boolean", "example": true }, "config": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "accountSid": "ACxxxx", "authToken": "tokenxxxx" } } } } }, "vidaPremium": { "description": "Mark this account as an actively paying account", "type": "boolean", "example": true }, "smsEnabled": { "description": "Enable SMS Capabilities on the agent", "type": "boolean", "example": true }, "smsBrandId": { "description": "SMS Brand Id that is registered for the organization", "type": "string", "example": "XXXXXX" }, "smsCampaignId": { "description": "Approved SMS Campaign Id for the organizations traffic", "type": "string", "example": "XXXXXX" }, "integrations": { "description": "Optional list of third-party app integrations to set up at org creation", "type": "array", "items": { "type": "object", "required": [ "appId", "appVersion", "appData" ], "properties": { "appId": { "type": "string", "example": "someappId" }, "appVersion": { "type": "string", "example": "v1" }, "appData": { "type": "object", "description": "Key/value settings specific to the integration", "additionalProperties": { "type": "string" }, "example": { "apiToken": "appsApiToken" } } } }, "example": [ { "appId": "some-app-id", "appVersion": "v1", "appData": { "apiToken": "APIToken" } }, { "appId": "another-example-app", "appVersion": "v2", "appData": { "accountSid": "sidxxxxxxx", "accountToken": "tokenxxxxxxx", "apiUrl": "https://someurl.example" } } ] } } } } } } } }, "/api/v2/deleteOrganization": { "delete": { "tags": [ "Accounts" ], "summary": "Delete an organization", "description": "Delete (immediately) an organization under your reseller. Reseller account required.", "parameters": [ { "name": "targetResellerId", "in": "query", "description": "Reseller Id to delete organization in", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "201": { "description": "Organization deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Organization deleted" } } } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targetOrganizationId" ], "properties": { "targetOrganizationId": { "description": "Organization Id to delete", "type": "integer", "example": "XXXXXXX" } } } } } } } }, "/api/v2/listOrganizations": { "get": { "tags": [ "Accounts" ], "summary": "List organizations", "description": "List all of your organizations. Reseller account required.", "parameters": [ { "name": "targetResellerId", "in": "query", "description": "Reseller Id to list organizations in", "required": true, "schema": { "type": "string" } }, { "name": "pagination", "in": "query", "description": "Whether to provide pagination", "required": false, "example": true, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Page number to fetch (0-based)", "required": false, "example": 0, "schema": { "type": "number" } }, { "name": "pageSize", "in": "query", "description": "How many orgs per page", "required": false, "example": 20, "schema": { "type": "number" } }, { "name": "active", "in": "query", "description": "Whether to return only organizations with this given active state", "required": false, "schema": { "type": "boolean" } } ], "responses": { "default": { "description": "" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/account": { "get": { "tags": [ "Accounts" ], "summary": "Get account details", "description": "Retrieve details for the authenticated account", "parameters": [ { "name": "targetAccountId", "in": "query", "description": "Target account ID when acting on behalf of another account", "required": false, "example": 123, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Account details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "example": 123 }, "username": { "type": "string", "example": "user@example.com" }, "details": { "type": "object" } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Accounts" ], "summary": "Update account details", "description": "Update selected profile details or supported settings for an account.", "parameters": [ { "name": "targetAccountId", "in": "query", "description": "Target account ID when acting on behalf of another account", "required": false, "example": 123, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Updated account details", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name", "example": "Ada Lovelace" }, "partnerName": { "type": "string", "description": "Partner name (for partner accounts only)" }, "resellerName": { "type": "string", "description": "Reseller name (for reseller accounts only)" }, "orgName": { "type": "string", "description": "Organization name" }, "accountName": { "type": "string", "description": "Account name" }, "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "description": { "type": "string", "description": "Profile description" }, "image": { "type": "string", "description": "Profile image URL" }, "businessName": { "type": "string", "description": "Business name" }, "businessAddress": { "type": "string", "description": "Business address" }, "email": { "type": "string", "format": "email", "description": "Email address" }, "agentTypeId": { "type": "string", "format": "uuid", "description": "Agent type to put this account on. Reseller or partner admins only. Must be a type available to the account's reseller." }, "settings": { "type": "object", "description": "Supported account-level reporting and dashboard settings. Existing settings outside the supplied fields are preserved; each supplied array is a complete replacement for that array.", "properties": { "reportingFields": { "type": "array", "description": "Structured fields extracted from conversations for reporting. Sending this array replaces the current reporting-field list at this account level.", "items": { "type": "object", "required": [ "key", "label", "instructions", "values" ], "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "example": "appointment_booked" }, "label": { "type": "string", "example": "Appointment booked" }, "instructions": { "type": "string", "example": "True when the customer agrees to a specific appointment time." }, "values": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "boolean", "choices", "number", "text" ] }, "choices": { "type": "array", "items": { "type": "string" }, "description": "Allowed values when kind is choices." } } } } } }, "metrics": { "type": "array", "description": "The complete replacement list for organization dashboard metrics; this is not an append operation. Before adding or updating a metric, read the current organization account and submit every metric that should remain. Do not send only the new metric. If the stored list is missing or empty, the dashboard may still show visible defaults; confirm the intended complete list before creating an organization override.", "items": { "type": "object", "additionalProperties": true } }, "defaultOrgSettings": { "type": "object", "description": "Defaults inherited by newly created organizations under a reseller.", "properties": { "metrics": { "type": "array", "description": "Default dashboard metric definitions for new organizations. Sending this array replaces the current default list.", "items": { "type": "object", "additionalProperties": true } } } } } } } } } } } } }, "/api/v2/listAccounts": { "get": { "tags": [ "Accounts" ], "summary": "List agent accounts", "description": "List all of your agent accounts", "parameters": [ { "name": "targetOrganizationId", "in": "query", "description": "Organization Id to list accounts in", "required": true, "schema": { "type": "string" } }, { "name": "pagination", "in": "query", "description": "Whether to provide pagination", "required": false, "example": true, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Page number to fetch", "required": false, "example": 0, "schema": { "type": "number" } }, { "name": "pageSize", "in": "query", "description": "How many accounts per page", "required": false, "example": 20, "schema": { "type": "number" } }, { "name": "active", "in": "query", "description": "Whether to return only accounts with this given active state", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/createAccount": { "post": { "tags": [ "Accounts" ], "summary": "Create an agent account", "description": "Creates a child agent account under an organization. Use the returned account ID when configuring and provisioning a Computer Agent.", "parameters": [ { "name": "targetAccountId", "in": "query", "description": "Organization account ID. Required when the API key is not already scoped to the organization.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Account created" }, "account": { "type": "object", "description": "The newly created agent account without its API key." } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "accountName" ], "properties": { "accountName": { "description": "Customer-facing name for the new agent account.", "type": "string", "example": "Acme Solar Bay Area Support Agent" }, "externalAccountId": { "description": "Optional identifier from another business system.", "type": "string", "example": "AC_12345" }, "externalBillingId": { "description": "Optional identifier from another billing system.", "type": "string", "example": "billing-id-6789" }, "integrations": { "description": "Optional list of third-party app integrations to set up for the new agent account.", "type": "array", "items": { "type": "object", "required": [ "appId", "appVersion", "appData" ], "properties": { "appId": { "type": "string", "example": "someappId" }, "appVersion": { "type": "string", "example": "v1" }, "appData": { "type": "object", "description": "Key/value settings specific to the integration", "additionalProperties": { "type": "string" }, "example": { "apiToken": "appsApiToken" } } } }, "example": [ { "appId": "some-app-id", "appVersion": "v1", "appData": { "apiToken": "APIToken" } }, { "appId": "another-example-app", "appVersion": "v2", "appData": { "accountSid": "sidxxxxxxx", "accountToken": "tokenxxxxxxx", "apiUrl": "https://someurl.example" } } ] } } } } } } } }, "/api/v2/deleteAccount": { "delete": { "tags": [ "Accounts" ], "summary": "Delete an account", "description": "Delete an account under your organization", "parameters": [ { "name": "targetOrganizationId", "in": "query", "description": "Organization Id to delete the account in", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "201": { "description": "Account deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Account deleted" } } } } } }, "400": { "description": "Bad Request" }, "403": { "description": "Forbidden" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targetAccountId": { "description": "Account Id", "type": "string", "example": "3" } } } } } } } }, "/api/v2/members": { "get": { "tags": [ "Accounts" ], "summary": "List members", "description": "List all members of your organization", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/member": { "get": { "tags": [ "Accounts" ], "summary": "Fetch member", "description": "Fetch details for a single member of your organization", "parameters": [ { "name": "targetMemberId", "in": "query", "description": "Id of the member to fetch", "required": true, "example": 3, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "member": { "type": "object" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Accounts" ], "summary": "Invite member", "description": "Invite a user to join your account as a member", "responses": { "201": { "description": "Invitation sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Invitation sent" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "description": "Email of the person you are inviting", "type": "string", "example": "admin@acmesolar.com" }, "redirectUrl": { "description": "URL to redirect user to after they accept invite", "type": "string", "example": "https://vida.io/welcome" }, "role": { "description": "Role for the invited member. Defaults to admin when not specified.", "type": "string", "example": "admin" }, "permittedAccountIds": { "description": "Account ids that this member can access", "type": "array", "items": { "type": "number" }, "example": [ 12345, 67890 ] }, "sendWelcomeEmail": { "description": "Whether to send the default welcome email. Defaults to true.", "type": "boolean", "example": true } } } } } } }, "delete": { "tags": [ "Accounts" ], "summary": "Delete member", "description": "Delete a member from your organization", "responses": { "201": { "description": "Member deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Member successfully removed from your organization" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targetMemberId" ], "properties": { "targetMemberId": { "description": "User Id of the member you are removing from your account", "type": "number", "example": 3 } } } } } } }, "put": { "tags": [ "Accounts" ], "summary": "Update member", "description": "Update member details for your organization", "responses": { "201": { "description": "Member updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Member updated" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targetMemberId" ], "properties": { "targetMemberId": { "description": "User Id of the member you are updating", "type": "number", "example": 3 }, "email": { "description": "New email for the member", "type": "string", "example": "member@acmesolar.com" }, "role": { "description": "Role for the member", "type": "string", "example": "admin" }, "permittedAccountIds": { "description": "Account ids that this member can access. Send empty array to remove all account restrictions", "type": "array", "items": { "type": "number" }, "example": [ 12345, 67890 ] } } } } } } } }, "/api/v2/stats/usage": { "get": { "tags": [ "Billing" ], "summary": "View Usage", "description": "View statistics about account usage", "parameters": [ { "name": "giveCosts", "in": "query", "description": "Returns values for keys with cost: prefix.", "example": false, "schema": { "type": "boolean" } }, { "name": "combineCosts", "in": "query", "description": "Returns cost values and usage values in the same response.", "example": false, "schema": { "type": "boolean" } }, { "name": "billingPeriod", "in": "query", "description": "Accepts previous or current for previous and current billing periods.", "example": "current", "schema": { "type": "string" } }, { "name": "timeseries", "in": "query", "description": "Returns data as a timeseries.", "example": false, "schema": { "type": "boolean" } }, { "name": "startDate", "in": "query", "description": "ISO date-time string, defaults to billing period start date.", "example": "2026-04-01T00:00:00.000Z", "schema": { "type": "string" } }, { "name": "endDate", "in": "query", "description": "ISO date-time string, optional, defaults to today.", "example": "2026-04-30T23:59:59.999Z", "schema": { "type": "string" } }, { "name": "frequency", "in": "query", "description": "Frequency value. Allowed: day, month, year. Defaults to day.", "example": "day", "schema": { "type": "string" } }, { "name": "allItems", "in": "query", "description": "Show all product items and not just the current plan.", "example": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Stats fetched successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/product/offeredPlan": { "get": { "tags": [ "Billing" ], "summary": "View Offered Product Plan", "description": "View Your Product Plan Offer", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/product/currentPlan": { "get": { "tags": [ "Billing" ], "summary": "View Current Product Plan", "description": "View Your Current Product Plan", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/product/allAvailablePlans": { "get": { "tags": [ "Billing" ], "summary": "View Available Product Plans", "description": "View All Available Product Plans", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/billing/billingSystemConfig": { "get": { "tags": [ "Billing" ], "summary": "Get billing provider configuration", "description": "Returns the configured Stripe or Chargebee provider for the selected reseller or partner account. Credential values are redacted and are display-only; do not submit them in an update request.", "parameters": [ { "name": "targetAccountId", "in": "query", "description": "Reseller or partner account whose billing provider configuration should be returned.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Billing system configuration fetched successfully" }, "billingConfig": { "type": "object", "properties": { "billingSystemType": { "type": "string", "enum": [ "stripe", "chargebee" ], "example": "stripe" }, "apiKey": { "type": "string", "description": "Redacted provider API key.", "example": "sk_liXXXXXXXXXXXXXX12345" }, "publishableKey": { "type": "string", "description": "Redacted provider publishable key.", "example": "pk_liXXXXXXXXXXXXXX12345" }, "webhookSigningKey": { "type": "string", "description": "Redacted Stripe webhook signing secret when Stripe is configured.", "example": "whsecXXXXXXXXXXXXXX12345" }, "site": { "type": "string", "description": "Chargebee site name when Chargebee is configured.", "example": "acme" }, "webhookUsername": { "type": "string", "description": "Chargebee webhook basic-auth username when Chargebee is configured.", "example": "vida-webhooks" }, "webhookPassword": { "type": "string", "description": "Redacted Chargebee webhook password when Chargebee is configured.", "example": "passXXXXXXXXX12345" } } } } } } } }, "401": { "description": "Authentication is required." }, "403": { "description": "The requester cannot manage billing for the selected account." }, "404": { "description": "No billing provider is configured for the selected account." } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Billing" ], "summary": "Configure a billing provider", "description": "Stores the complete Stripe or Chargebee configuration used to bill downstream customers for the selected reseller or partner account. Each request replaces the current provider configuration. Supply every required field with its original value; redacted values returned by GET cannot be reused.", "parameters": [ { "name": "targetAccountId", "in": "query", "description": "Reseller or partner account whose billing provider configuration should be replaced.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Billing provider configuration stored successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Authentication is required." }, "403": { "description": "The requester cannot manage billing for the selected account." } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Stripe billing provider", "type": "object", "required": [ "billingSystemType", "apiKey", "publishableKey", "webhookSigningKey" ], "properties": { "billingSystemType": { "type": "string", "enum": [ "stripe" ], "example": "stripe" }, "apiKey": { "type": "string", "description": "Stripe secret API key.", "example": "" }, "publishableKey": { "type": "string", "description": "Stripe publishable key used for customer checkout.", "example": "" }, "webhookSigningKey": { "type": "string", "description": "Signing secret for the reseller-specific Vida webhook endpoint.", "example": "" } } }, { "title": "Chargebee billing provider", "type": "object", "required": [ "billingSystemType", "apiKey", "publishableKey", "site", "webhookUsername", "webhookPassword" ], "properties": { "billingSystemType": { "type": "string", "enum": [ "chargebee" ], "example": "chargebee" }, "apiKey": { "type": "string", "description": "Chargebee full-access API key.", "example": "" }, "publishableKey": { "type": "string", "description": "Chargebee publishable key used for customer checkout.", "example": "" }, "site": { "type": "string", "description": "Chargebee site subdomain without chargebee.com.", "example": "acme" }, "webhookUsername": { "type": "string", "description": "Username configured for Chargebee webhook basic authentication.", "example": "" }, "webhookPassword": { "type": "string", "description": "Password configured for Chargebee webhook basic authentication.", "example": "" } } } ] } } } } } }, "/api/v2/product/subscribe": { "post": { "tags": [ "Billing" ], "summary": "Subscribe to product plan", "description": "Subscribe to a product plan", "responses": { "200": { "description": "Successfully subscribed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "productPlanId", "term" ], "properties": { "productPlanId": { "description": "Product Plan Id to enable subscription", "type": "string", "example": "pplan-vida-business-basic" }, "term": { "description": "Subscription length of month or year", "type": "string", "example": "month" }, "cancelUrl": { "description": "If using external payment processor (eg Stripe) what url to redirect if payment canceled", "type": "string", "example": "https://yoursite.io/cancel" }, "successUrl": { "description": "If using external payment processor (eg Stripe) what url to redirect if payment successful", "type": "string", "example": "https://yoursite.io/success" }, "checkoutType": { "description": "Which checkout session you would like to start. Embedded session or external redirect url", "type": "string", "example": "embedded" } } } } } } } }, "/api/v2/product/cancel": { "delete": { "tags": [ "Billing" ], "summary": "Cancel product subscription", "description": "Cancel the current product subscription for the authenticated account", "parameters": [ { "name": "targetAccountId", "in": "query", "description": "Target account ID when acting on behalf of another account", "required": false, "example": 123, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Subscription canceled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Subscription cancelled" } } } } } }, "400": { "description": "Unable to cancel subscription", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A descriptive error message" } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Cancellation reason" }, "details": { "type": "string", "description": "Additional details" } } } } } } } }, "/api/v2/addon/available": { "get": { "tags": [ "Billing" ], "summary": "View Available Add Ons", "description": "View all available Add-Ons for current product plan", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/product/productCatalog": { "get": { "tags": [ "Billing" ], "summary": "View Product Catalog", "description": "View Your Product Catalog Plans. Reseller or Partner Account Required.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/product/productCatalog/{productPlanId}": { "get": { "tags": [ "Billing" ], "summary": "Fetch a product plan details", "description": "Fetch a product plan details from your catalog", "parameters": [ { "name": "productPlanId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Product Plan Id", "example": "pplan-id-xxxx" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/domains": { "get": { "tags": [ "White-label Domains" ], "summary": "List white-label domains", "description": "Lists the domains registered to the authenticated reseller and identifies the current default domain.", "responses": { "200": { "description": "White-label domains", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Domains fetched successfully" }, "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "example": "ai.example.com" }, "createdTimestamp": { "type": "integer", "description": "Creation timestamp returned by Vida." }, "default": { "type": "boolean" } } } } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/domain": { "delete": { "tags": [ "White-label Domains" ], "summary": "Remove a white-label domain", "description": "Removes a domain owned by the authenticated reseller. The current default domain cannot be removed; select another default first.", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Registered domain to remove.", "example": "ai.example.com", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Domain removed" }, "400": { "description": "Invalid domain request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "White-label Domains" ], "summary": "Add a white-label domain", "description": "Registers a domain to the authenticated reseller. Configure the domain according to your Vida onboarding instructions before directing users to it.", "responses": { "200": { "description": "Domain registered" }, "400": { "description": "Domain could not be registered" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "example": "ai.example.com" } } } } } } } }, "/api/v2/domain/default": { "post": { "tags": [ "White-label Domains" ], "summary": "Set the default white-label domain", "description": "Makes one of the authenticated reseller\\'s registered domains the default domain.", "responses": { "200": { "description": "Default domain updated" }, "400": { "description": "Domain is not registered to this reseller or is already the default" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "example": "ai.example.com" } } } } } } } }, "/api/v2/numberingProviders": { "get": { "tags": [ "Phone Numbers" ], "summary": "List supported numbering providers", "description": "Returns every numbering provider supported along with configuration requirements. Requires a valid reseller or partner account.", "responses": { "200": { "description": "Numbering providers fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Numbering providers fetched successfully" }, "numberingProviders": { "type": "array", "items": { "type": "object" } } } } } } }, "404": { "description": "No numbering providers configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No numbering providers configured" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/logs": { "get": { "tags": [ "Conversation Logs" ], "summary": "Query conversation logs", "description": "Returns authorized conversation logs for a time range. Select returned fields, export CSV, or filter any log field with query names such as duration__gte, eventType__in, or metadata.status__icontains. Supported suffixes are eq, ne, gt, gte, lt, lte, in, nin, contains, icontains, startswith, istartswith, endswith, iendswith, regex, iregex, isnull, isset, empty, notempty, and present. Without a suffix, a field uses exact matching.", "parameters": [ { "name": "start", "in": "query", "required": false, "description": "Start time as Unix seconds. Defaults to Unix epoch (Jan 1 1970 00:00:00 UTC).", "example": 1727481600, "schema": { "type": "integer" } }, { "name": "end", "in": "query", "required": false, "description": "End time as Unix seconds. Defaults to current time.", "example": 1728086400, "schema": { "type": "integer" } }, { "name": "fields", "in": "query", "required": false, "description": "Comma separated list of fields to include. Restricted fields are always removed.", "example": "id,timestamp,account_id,org_id,eventType", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "Response format. json returns a JSON envelope. csv streams a CSV file.", "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" } }, { "name": "pageSize", "in": "query", "required": false, "description": "Page size for pagination. Max 10000. Defaults to 20.", "example": 500, "schema": { "type": "integer", "minimum": 1, "maximum": 10000 } }, { "name": "page", "in": "query", "required": false, "description": "Page number starting at 1. Defaults to 1.", "example": 1, "schema": { "type": "integer", "minimum": 1 } }, { "name": "includeFields", "in": "query", "required": false, "description": "When truthy, include an inferred schema array in the JSON response.", "example": true, "schema": { "type": "boolean" } }, { "name": "targetAccountId", "in": "query", "required": false, "description": "Selected account whose conversation logs should be returned. Include this when the API token can access more than one account.", "example": 3026480, "schema": { "type": "integer" } }, { "name": "outcome", "in": "query", "required": false, "description": "Match fields against one task-goal evaluation in the log outcomes array. Supply a URL-encoded JSON object followed by ||json.", "example": "%7B%22type%22%3A%22task_goal%22%2C%22status%22%3A%22evaluated%22%2C%22value%22%3Atrue%7D%7C%7Cjson", "schema": { "type": "string" } }, { "name": "field__suffix", "in": "query", "required": false, "description": "Replace field with a log field name and suffix with a supported comparison. Values may use an explicit ||json, ||bool, ||number, ||null, or ||string type hint. Repeat this pattern for each filter.", "example": "120||number", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful JSON response. When format=csv, a CSV file is streamed with status 200.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "logs": { "type": "array", "description": "Array of log entries with restricted fields removed based on caller scope.", "items": { "type": "object", "additionalProperties": true, "example": { "id": "log_001", "timestamp": "2025-09-30T12:34:56.789Z", "account_id": "acct_123", "org_id": "org_456", "eventType": "message.created", "metadata": { "convoId": "c_abc", "tokens": 1234 }, "outcomes": [ { "type": "task_goal", "status": "evaluated", "value": true, "source": "task_goal_evaluator", "schemaVersion": 1 } ] } } }, "count": { "type": "integer", "example": 20 }, "totalCount": { "type": "integer", "example": 5231 }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "pageSize": { "type": "integer", "example": 20 }, "totalPages": { "type": "integer", "example": 262 }, "totalCount": { "type": "integer", "example": 5231 }, "hasMore": { "type": "boolean", "example": true }, "pageCount": { "type": "integer", "example": 262 } } }, "schema": { "type": "array", "description": "Returned only when includeFields is truthy. The inferred list of available fields.", "items": { "type": "string" }, "example": [ "id", "timestamp", "account_id", "org_id", "eventType", "metadata" ] } } } }, "text/csv": { "schema": { "type": "string", "format": "binary", "description": "CSV export of logs when format=csv" } } } }, "401": { "description": "Unauthorized. req.user missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized Request" } } } } } }, "404": { "description": "No logs available for CSV export when format=csv", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No logs found for CSV export" } } } } } }, "500": { "description": "Unhandled server error while fetching logs or generating CSV", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while fetching conversation logs." }, "error": { "type": "string", "example": "Detailed error message" } } } } } }, "503": { "description": "Conversation logs service not available", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Conversation logs service not available" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/searchAccounts": { "get": { "tags": [ "Accounts" ], "summary": "Search accounts", "description": "Search partner, reseller, organization or account objects using various filters", "parameters": [ { "name": "accountType", "in": "query", "description": "Type of account to search", "required": true, "example": "organization", "schema": { "type": "string" } }, { "name": "queryText", "in": "query", "description": "Optional free text search", "required": false, "example": "vida", "schema": { "type": "string" } }, { "name": "pagination", "in": "query", "description": "Whether to provide pagination", "required": false, "example": true, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Page number to fetch", "required": false, "example": 0, "schema": { "type": "number" } }, { "name": "pageSize", "in": "query", "description": "How many accounts per page", "required": false, "example": 20, "schema": { "type": "number" } }, { "name": "createdStart", "in": "query", "description": "Epoch to search created accounts from", "required": false, "example": 1700000000, "schema": { "type": "number" } }, { "name": "createdEnd", "in": "query", "description": "Epoch to search created accounts until", "required": false, "example": 1710000000, "schema": { "type": "number" } }, { "name": "canceledStart", "in": "query", "description": "Epoch to search cancellations from", "required": false, "example": 1700000000, "schema": { "type": "number" } }, { "name": "canceledEnd", "in": "query", "description": "Epoch to search cancellations until", "required": false, "example": 1710000000, "schema": { "type": "number" } }, { "name": "subscribed", "in": "query", "description": "Filter by subscription state", "required": false, "example": true, "schema": { "type": "boolean" } }, { "name": "canceled", "in": "query", "description": "Filter by canceled subscription state", "required": false, "example": false, "schema": { "type": "boolean" } }, { "name": "active", "in": "query", "description": "Filter by active flag", "required": false, "example": true, "schema": { "type": "boolean" } }, { "name": "onboardingComplete", "in": "query", "description": "Filter by onboarding completed flag", "required": false, "example": true, "schema": { "type": "boolean" } }, { "name": "productPlanId", "in": "query", "description": "Product plan id filter", "required": false, "example": "plan1", "schema": { "type": "string" } }, { "name": "productPlanTerm", "in": "query", "description": "Product plan term filter", "required": false, "example": "monthly", "schema": { "type": "string" } }, { "name": "billingSubscriptionId", "in": "query", "description": "Billing subscription id filter", "required": false, "example": "sub_123", "schema": { "type": "string" } }, { "name": "billingId", "in": "query", "description": "Billing id filter", "required": false, "example": "bill_123", "schema": { "type": "string" } }, { "name": "externalAccountId", "in": "query", "description": "External account id filter", "required": false, "example": "ext_123", "schema": { "type": "string" } }, { "name": "currentBillingPeriodVoiceMinutesMin", "in": "query", "description": "Minimum current period voice minutes", "required": false, "example": 10, "schema": { "type": "number" } }, { "name": "currentBillingPeriodVoiceMinutesMax", "in": "query", "description": "Maximum current period voice minutes", "required": false, "example": 200, "schema": { "type": "number" } }, { "name": "previousBillingPeriodVoiceMinutesMin", "in": "query", "description": "Minimum previous period voice minutes", "required": false, "example": 5, "schema": { "type": "number" } }, { "name": "previousBillingPeriodVoiceMinutesMax", "in": "query", "description": "Maximum previous period voice minutes", "required": false, "example": 100, "schema": { "type": "number" } }, { "name": "currentBillingPeriodMessagesMin", "in": "query", "description": "Minimum current period messages", "required": false, "example": 10, "schema": { "type": "number" } }, { "name": "currentBillingPeriodMessagesMax", "in": "query", "description": "Maximum current period messages", "required": false, "example": 200, "schema": { "type": "number" } }, { "name": "previousBillingPeriodMessagesMin", "in": "query", "description": "Minimum previous period messages", "required": false, "example": 5, "schema": { "type": "number" } }, { "name": "previousBillingPeriodMessagesMax", "in": "query", "description": "Maximum previous period messages", "required": false, "example": 100, "schema": { "type": "number" } }, { "name": "allTimeVoiceMinutesMin", "in": "query", "description": "Minimum all time voice minutes", "required": false, "example": 100, "schema": { "type": "number" } }, { "name": "allTimeVoiceMinutesMax", "in": "query", "description": "Maximum all time voice minutes", "required": false, "example": 1000, "schema": { "type": "number" } }, { "name": "allTimeMessagesMin", "in": "query", "description": "Minimum all time messages", "required": false, "example": 100, "schema": { "type": "number" } }, { "name": "allTimeMessagesMax", "in": "query", "description": "Maximum all time messages", "required": false, "example": 1000, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "totalAccounts": { "type": "number", "example": 1 }, "pageSize": { "type": "number", "example": 20 }, "pageNumber": { "type": "number", "example": 0 }, "accounts": { "type": "array", "items": { "type": "object" } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/conversation/batch": { "post": { "tags": [ "Conversations" ], "summary": "Fetch multiple conversations", "description": "Returns up to 200 authorized conversations in one request. Use the roomId and uuid values returned by GET /api/v2/logs.", "responses": { "200": { "description": "Batch lookup complete. Each item includes per-item success/failure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "stats": { "type": "object", "properties": { "requested": { "type": "number", "example": 2 }, "ok": { "type": "number", "example": 2 }, "failed": { "type": "number", "example": 0 } } }, "results": { "type": "array", "items": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "roomId": { "type": "string", "example": "2236859:2550714" }, "uuid": { "type": "string", "example": "bf0011ed-8175-458a-8fba-1e62ddc77567:1770763782" }, "message": { "type": "string", "example": "Success" }, "conversation": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } } }, "400": { "description": "Invalid request body (e.g., missing items or too many items).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "items array is required" } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "type": "string", "example": "Unauthorized Request" } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "description": "List of conversation lookup items (max 200).", "type": "array", "items": { "type": "object", "required": [ "roomId", "uuid" ], "properties": { "roomId": { "description": "Conversation room ID.", "type": "string", "example": "2236859:2550714" }, "uuid": { "description": "Conversation UUID from logs. Supports call format {uuid}:{timestamp} or message format {uuid}:{openTimestamp}:{closeTimestamp}.", "type": "string", "example": "bf0011ed-8175-458a-8fba-1e62ddc77567:1770763782" } } } } } }, "example": { "items": [ { "roomId": "2236859:2550714", "uuid": "bf0011ed-8175-458a-8fba-1e62ddc77567:1770763782" }, { "roomId": "2236859:2535655", "uuid": "edf65410-9f78-4d5e-82d2-2ee773ad4a49:1770765260" } ] } } } } } }, "/api/v2/conversation/{roomId}/{uuid}": { "get": { "tags": [ "Conversations" ], "summary": "Get a conversation", "description": "Returns one authorized conversation using the roomId and uuid values returned by GET /api/v2/logs.", "parameters": [ { "name": "roomId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversation room ID returned by the log entry.", "example": "2236859:2550714" }, { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversation lookup value returned by the log entry.", "example": "bf0011ed-8175-458a-8fba-1e62ddc77567:1770763782" }, { "name": "targetAccountId", "in": "query", "description": "Selected account that owns the conversation. Include this when the API token can access more than one account.", "required": false, "schema": { "type": "integer" }, "example": 3026480 } ], "responses": { "200": { "description": "Conversation returned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "conversation": { "description": "Chronological conversation events, including messages and recorded Computer Agent tool activity when present.", "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "403": { "description": "The authenticated user cannot access this conversation." } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/auth/account/oneTimeAuthToken": { "get": { "tags": [ "Authorization" ], "summary": "Generate one-time auth token", "description": "Generate a single-use authentication token for the specified account – Reseller/Partner account required. If the email does not exist and an externalAccountId is provided, the system will automatically add that email as a member of the organization.", "parameters": [ { "name": "externalAccountId", "in": "query", "description": "Your system’s customer / account ID (optional)", "required": false, "example": "acct_123abc", "schema": { "type": "string" } }, { "name": "customerId", "in": "query", "description": "Alternative to externalAccountId. Provide either this or your externalAccountId (optional)", "required": false, "example": "acct_123abc", "schema": { "type": "string" } }, { "name": "email", "in": "query", "description": "Email address of the account user", "required": true, "example": "user@example.com", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Auth token created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "authToken": { "type": "string", "example": "token_here" } } } } } }, "400": { "description": "Missing or invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "email is required" } } } } } }, "401": { "description": "Unauthorized : missing / bad API key or token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized Request" } } } } } }, "404": { "description": "No account found OR caller lacks access", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Account not found for key: user@example.com" } } } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while fetching authentication token" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/getAccountByExternalId": { "get": { "tags": [ "Accounts" ], "summary": "Fetch Account by externalAccountId", "description": "Returns the account that matches the externalAccountId – Reseller/Partner only.", "parameters": [ { "name": "externalAccountId", "in": "query", "description": "Your system’s customer / account ID", "required": true, "example": "acct_123abc", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "account": { "type": "object" } } }, "examples": { "example": { "value": { "success": true, "message": "Success", "account": { "id": 3, "username": "accountUsername", "organizationId": 3 } } } } } } }, "400": { "description": "Missing or invalid externalAccountId", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "externalAccountId is required" } } } } } }, "401": { "description": "Unauthorized : missing / bad API key or token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized Request" } } } } } }, "404": { "description": "No account found OR caller lacks access", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Account not found for externalAccountId acct_123abc" } } } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while fetching account" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/billing/billingPeriod": { "post": { "tags": [ "Billing" ], "summary": "Start a new billing period for an organization", "description": "Start a new billing period for an organization. This must be set on the day the current billing period ends – Reseller/Partner only.", "parameters": [ { "name": "targetAccountId", "in": "query", "description": "Account ID to update billing period for", "required": false, "example": "123", "schema": { "type": "string" } }, { "name": "externalAccountId", "in": "query", "description": "External account identifier mapped to the target account", "required": false, "example": "acct_123abc", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Billing period updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Billing period updated" }, "billingPeriod": { "type": "object", "properties": { "startDateTimestamp": { "type": "integer", "example": 1735689600 }, "endDateTimestamp": { "type": "integer", "example": 1738281600 } } } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "startDateTimestamp must not be greater than endDateTimestamp" } } } } } }, "404": { "description": "Account not found or inaccessible", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Account not found for provided identifier" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "startDateTimestamp", "endDateTimestamp" ], "properties": { "startDateTimestamp": { "type": "integer", "example": 1735689600, "description": "Billing period start timestamp (seconds since epoch)" }, "endDateTimestamp": { "type": "integer", "example": 1738281600, "description": "Billing period end timestamp (seconds since epoch)" } } } } } } } }, "/api/v2/billing/adrExportConfig": { "post": { "tags": [ "Billing" ], "summary": "Configure ADR Export Settings", "description": "Configure or update your ADR export settings", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "deliveryProtocol", "rotationMinutes", "host", "port", "username", "password" ], "properties": { "deliveryProtocol": { "description": "SFTP, FTPS, or FTP", "type": "string", "example": "sftp" }, "rotationMinutes": { "description": "How many minutes of records should be contained in each file", "type": "string", "example": "somekey", "default": "60" }, "host": { "description": "hostname or IP address where to ship the ADR files to", "type": "string", "example": "sftp.domain.com" }, "port": { "description": "Port for the SFTP or FTP service", "type": "integer", "example": 2202 }, "username": { "description": "username for the sftp or ftp account", "type": "string", "example": "someuser" }, "password": { "description": "password for the sftp or ftp account", "type": "string", "example": "somepassword" }, "path": { "description": "Folder path to deposit the files to. Defaults to the users home directory", "type": "string", "example": "/path/" } } } } } } } }, "/api/v2/updateOrganization": { "post": { "tags": [ "Accounts" ], "summary": "Update Organization Settings", "description": "Update certain settings for an organization – Reseller/Partner only.", "parameters": [ { "name": "targetOrganizationId", "in": "query", "description": "Target Organization Id to update settings for", "required": true, "example": "XXXXXXX", "schema": { "type": "string" } } ], "responses": { "200": { "description": "At least one setting was successfully updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Organization settings updated" }, "updatedSettings": { "type": "array", "items": { "type": "string" }, "example": [ "orgName", "vidaPremium" ] }, "failedSettings": { "type": "array", "items": { "type": "string" }, "nullable": true, "example": [ "email" ] } } }, "examples": { "AllSuccess": { "summary": "All requested changes succeeded", "value": { "success": true, "message": "Organization settings updated", "updatedSettings": [ "productPlanId", "externalBillingId" ] } }, "PartialSuccess": { "summary": "Some settings failed validation / update", "value": { "success": true, "message": "Organization settings updated", "updatedSettings": [ "vidaPremium" ], "failedSettings": [ "email", "smsEnabled" ] } } } } } }, "400": { "description": "Bad request – nothing updated *or* specific validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No settings updated" }, "failedSettings": { "type": "array", "items": { "type": "string" }, "nullable": true, "example": [ "productPlanId" ] } } }, "examples": { "NothingUpdated": { "summary": "Request parsed but no valid changes supplied", "value": { "success": false, "message": "No settings updated" } }, "ProductPlanCheckoutRequired": { "summary": "Product-plan change blocked until checkout completed", "value": { "success": false, "message": "Unable to change product plan, customer has not yet completed billing checkout. Please offer the plan first.", "failedSettings": [ "productPlanId" ] } }, "InvalidEmail": { "summary": "Email failed format validation", "value": { "success": false, "message": "Invalid email provided. Doesn't look like a valid email address.", "failedSettings": [ "email" ] } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "description": "Account status - if set to false calls and messages for all agents in this org will no longer be answered", "type": "boolean", "example": true }, "productPlanId": { "description": "Change Product Plan Id on the Organization. Note: if the target product plan is tied to a Stripe or Chargebee product and the customer has not yet subscribed - this will not work. Give the customer an offered product plan first. Otherwise - this will update the product plan on Vida and in the configured billing system.", "type": "string", "example": "someProductPlanId" }, "offeredProductPlanId": { "description": "Give an offer of a product plan to a customer. Useful when offering a private plan before the customer has completed checkout. Set null to remove it", "type": "string", "example": "someProductPlanId" }, "email": { "description": "Change main owner Email Of the Organization", "type": "string", "example": "admin@test.com" }, "orgName": { "description": "Change Organization Name", "type": "string", "example": "Test Organization" }, "smsEnabled": { "description": "Enable SMS Capabilities on the agent.", "type": "boolean", "example": true }, "smsBrandId": { "description": "SMS Brand Id that is registered for the organization", "type": "string", "example": "XXXXXX" }, "smsCampaignId": { "description": "Approved SMS Campaign Id for the organizations traffic", "type": "string", "example": "XXXXXX" }, "vidaPremium": { "description": "Indicates whether the account is in an unlocked (paid) state.", "type": "boolean", "example": true }, "externalAccountId": { "description": "External Account Id to match with your internal system account Id. Set to null to remove it.", "type": "string", "example": "AC_XXXXXXX" }, "externalBillingId": { "description": "External Id to match with your internal billing system. Set to null to remove it.", "type": "string", "example": "somebillingId" }, "hipaaSetting": { "description": "HIPAA setting for this organization. on|off|inherit (inherit from reseller)", "type": "string", "enum": [ "on", "off", "inherit" ], "default": "inherit" }, "orgAccountType": { "description": "Organization account type (internal vs customer). Internal orgs are billed through reseller usage; customer orgs are eligible for full subscriptions. Defaults to customer.", "type": "string", "enum": [ "internal", "customer" ], "example": "customer" } } } } } } } }, "/api/v2/updateAccount": { "post": { "tags": [ "Accounts" ], "summary": "Update Account Settings", "description": "Update certain settings for an account – Reseller/Partner only.", "parameters": [ { "name": "targetAccountId", "in": "query", "description": "Target Account Id to update settings for", "required": true, "example": "XXXXXXX", "schema": { "type": "string" } } ], "responses": { "200": { "description": "At least one setting was successfully updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Account settings updated" }, "updatedSettings": { "type": "array", "items": { "type": "string" }, "example": [ "accountName" ] }, "failedSettings": { "type": "array", "items": { "type": "string" }, "nullable": true, "example": [ "externalBillingId" ] } } } } } }, "400": { "description": "Bad request – nothing updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No settings updated" }, "failedSettings": { "type": "array", "items": { "type": "string" }, "nullable": true, "example": [ "externalBillingId" ] } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "description": "Account status - if set to false calls and messages will not be answered", "type": "boolean", "example": true }, "accountName": { "description": "Change Account Name", "type": "string", "example": "Support Team" }, "externalAccountId": { "description": "External Account Id to match with your internal system account Id. Set to null to remove it.", "type": "string", "example": "AC_XXXXXXX" }, "externalBillingId": { "description": "External Id to match with your internal billing system. Set to null to remove it.", "type": "string", "example": "somebillingId" } } } } } } } }, "/api/v2/numberingProvider": { "post": { "tags": [ "Phone Numbers" ], "summary": "Add a numbering provider to an organization", "description": "Create a new numbering provider configuration for an organization – Reseller/Partner only.", "parameters": [ { "name": "targetOrganizationId", "in": "query", "description": "Target Organization Id to update settings for", "required": true, "example": "XXXXXXX", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Numbering provider added", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Numbering provider added" } } } } } }, "400": { "description": "Validation or duplication error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Numbering provider already exists" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "providerId", "config" ], "properties": { "providerId": { "type": "string", "example": "Twilio" }, "default": { "type": "boolean", "example": false }, "enabled": { "type": "boolean", "example": true }, "config": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "twilioAccountSid": "ACxxxx", "twilioAuthToken": "tokenxxxx" } } } } } } } }, "put": { "tags": [ "Phone Numbers" ], "summary": "Update an existing numbering provider", "description": "Modify an existing numbering provider configuration, set default, or disable it – Reseller/Partner only.", "parameters": [ { "name": "targetOrganizationId", "in": "query", "description": "Target Organization Id to update settings for", "required": true, "example": "XXXXXXX", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Numbering provider updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Numbering provider updated" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Only one numbering provider can be set as default" } } } } } }, "404": { "description": "Specified provider not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Numbering provider not found" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "providerId" ], "properties": { "providerId": { "type": "string", "example": "Twilio" }, "default": { "type": "boolean", "example": true }, "enabled": { "type": "boolean", "example": false }, "config": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "accountSid": "ACxxxx", "authToken": "tokenxxxx" } } } } } } } } }, "/api/v2/webhookRelay/types": { "get": { "tags": [ "Webhooks" ], "summary": "List supported Webhook Relay types", "description": "Returns every webhook relay type that can be configured for your account (e.g., Twilio SMS, Chargebee, etc.).", "responses": { "200": { "description": "Relay types fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook Relay types fetched successfully" }, "types": { "type": "array", "items": { "type": "object", "required": [ "name", "description" ], "properties": { "name": { "type": "string", "description": "Unique identifier for this relay type", "example": "twilioSMS" }, "description": { "type": "string", "description": "What the relay does", "example": "Proxy inbound Twilio SMS webhooks to your app first before agent processes them." } } } } } } } } }, "401": { "description": "Unauthorized – missing or invalid API key/token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized Request" } } } } } }, "500": { "description": "Internal server or data-store error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Internal data store error" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/webhookRelay/{type}": { "post": { "tags": [ "Webhooks" ], "summary": "Create or update a webhook relay", "description": "Forward incoming webhooks of the specified type to your URL.", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "string" }, "example": { "type": "string", "example": "twilioSMS" } } }, "description": "Relay type (e.g. twilioSMS, chargebee)" } ], "responses": { "200": { "description": "Relay stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook Relay for type 'twilioSMS' configured successfully." } } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "headers must be an array of single-key objects" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized Request" } } } } } }, "403": { "description": "Premium feature required", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Webhook Relay is a premium feature. Please upgrade your account." } } } } } }, "404": { "description": "Relay type not supported", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Webhook Relay type 'foo' is not supported." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to store configuration." } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Absolute HTTP/HTTPS endpoint that will receive the forwarded webhook.", "example": "https://example.com/webhook/twilio" }, "timeout": { "type": "number", "description": "Timeout (ms) before the forward request is aborted.", "example": 5000 }, "headers": { "type": "array", "description": "Custom HTTP headers (array of single-key objects).", "items": { "type": "object", "example": { "Authorization": "Bearer xyz" } }, "example": [ { "Authorization": "Bearer xyz" }, { "X-Customer-ID": "abc123" } ] }, "successStatusCodes": { "type": "array", "description": "Status codes treated as success by Vida when your endpoint responds.", "items": { "type": "integer", "example": 202 }, "example": [ 200, 201, 202 ] } } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook relay configuration", "description": "Removes the stored webhook relay settings for the specified type from the authenticated user account.", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Relay type to delete (must be one previously configured)", "example": "twilioSMS" } ], "responses": { "200": { "description": "Relay configuration deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook Relay type 'twilioSMS' removed successfully." } } } } } }, "400": { "description": "Missing or invalid type parameter", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "type path parameter is required and must be a string" } } } } } }, "401": { "description": "Unauthorized – missing or invalid API key/token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized Request" } } } } } }, "403": { "description": "Forbidden – feature requires Vida Premium", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Webhook Relay is a premium feature. Please upgrade your account to use it." } } } } } }, "404": { "description": "Relay type was not configured for this user", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Webhook Relay type 'foo' was not configured." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Internal error" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] }, "get": { "tags": [ "Webhooks" ], "summary": "Get a webhook relay configuration", "description": "Fetch the current webhook relay settings for the given type (e.g., Twilio SMS, Chargebee) for your account.", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Relay type to fetch (must match one of GET /webhookRelay/types)", "example": "twilioSMS" } ], "responses": { "200": { "description": "Relay configuration found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook Relay configuration fetched successfully." }, "config": { "type": "object", "properties": { "url": { "type": "string", "example": "https://hooks.myapp.com/inbound/twilio" }, "timeout": { "type": "number", "example": 5000 }, "headers": { "type": "array", "items": { "type": "object", "example": { "Authorization": "Bearer xyz" } } }, "successStatusCodes": { "type": "array", "items": { "type": "integer" }, "example": [ 200, 202 ] } } } } } } } }, "401": { "description": "Unauthorized – missing or invalid API key/token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized Request" } } } } } }, "403": { "description": "Forbidden – feature requires Vida Premium", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Webhook Relay is a premium feature. Please upgrade your account to use it." } } } } } }, "404": { "description": "Relay type not configured for this user", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Webhook Relay type 'twilioSMS' not configured." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Internal error" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/webhookRelay": { "get": { "tags": [ "Webhooks" ], "summary": "List all webhook relay configurations", "description": "Fetch the complete set of webhook relay settings configured on your account.", "responses": { "200": { "description": "At least one relay configuration found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook Relay configurations fetched successfully." }, "configs": { "type": "array", "items": { "type": "object", "required": [ "type", "url" ], "properties": { "type": { "type": "string", "example": "twilioSMS" }, "url": { "type": "string", "example": "https://hooks.myapp.com/inbound/twilio" }, "timeout": { "type": "number", "example": 5000 }, "headers": { "type": "array", "items": { "type": "object", "example": { "Authorization": "Bearer xyz" } } }, "successStatusCodes": { "type": "array", "items": { "type": "integer" }, "example": [ 200, 202 ] } } } } } } } } }, "401": { "description": "Unauthorized – missing or invalid API key/token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized Request" } } } } } }, "403": { "description": "Forbidden – feature requires Vida Premium", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Webhook Relay is a premium feature. Please upgrade your account to use it." } } } } } }, "404": { "description": "The user has no webhook relay configurations", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No webhook relay configurations found." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Internal error" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/models/supported": { "get": { "tags": [ "Models" ], "summary": "List supported AI models", "description": "Returns the model identifiers the selected account may use for agentModel and agentThinkingModel. Use canReason and supportsFastMode to decide which model settings apply.", "parameters": [ { "name": "targetAccountId", "in": "query", "description": "Account whose model availability should be returned.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of supported model descriptors", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": { "provider": { "type": "string", "description": "Model provider.", "example": "openai" }, "canReason": { "type": "boolean", "description": "Whether the model supports advanced reasoning", "example": true }, "supportsFastMode": { "type": "boolean", "description": "Whether the model supports OpenAI Fast processing.", "example": true } } } }, "example": { "claude-haiku-4-5-20251001": { "provider": "anthropic", "canReason": true }, "claude-sonnet-4-5-20250929": { "provider": "anthropic", "canReason": true }, "gemini-3.5-flash": { "provider": "google", "canReason": true }, "gpt-5.6": { "provider": "openai", "canReason": true, "supportsFastMode": true }, "z-ai/glm-5.2": { "provider": "openrouter", "canReason": true }, "gpt-4.1": { "provider": "openai", "canReason": false } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Internal error" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agentEventRules/staging": { "get": { "tags": [ "Agents" ], "summary": "Fetch Staging Agent", "description": "Returns the editable staging configuration for the selected account. Changes made with POST /api/v2/agent remain in staging until published.", "parameters": [ { "name": "targetAccountId", "in": "query", "description": "Account whose staging configuration should be returned.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Agent retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConfigurationResponse" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agentEventRules/default": { "get": { "tags": [ "Agents" ], "summary": "Fetch Live Agent", "description": "Returns the live configuration currently used by the selected account. The live and staging configurations have different agentConfigId values.", "parameters": [ { "name": "targetAccountId", "in": "query", "description": "Account whose live configuration should be returned.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Agent retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConfigurationResponse" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agent/autoReviewAgentConfiguration": { "post": { "operationId": "autoReviewPostAutoReviewAgentConfiguration", "summary": "Review an Agent configuration", "description": "Reviews selected configuration fields or the complete Agent configuration and returns suggested improvements. This operation does not change or publish the Agent configuration.\n", "parameters": [ { "name": "targetAccountId", "in": "query", "required": false, "description": "Account that owns the Agent configuration.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Suggested Agent configuration improvements", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "description": "Reviewed fields when mode is fields.", "items": { "type": "object", "additionalProperties": true } }, { "type": "object", "description": "Agent-wide suggestions when mode is agent.", "additionalProperties": true } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "fields", "agent" ], "default": "fields", "description": "Review selected fields or the complete Agent configuration." }, "templateId": { "type": "string", "description": "Template used for a field review when agentConfigId is not provided." }, "agentConfigId": { "type": "string", "description": "Agent configuration to review. Required when mode is agent." }, "fields": { "type": "array", "description": "Configuration fields to review when mode is fields.", "items": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "Configuration field name." }, "value": { "type": "string", "description": "Current field value when reviewing a template." } } } } } }, "examples": { "fields": { "summary": "Review selected fields", "value": { "mode": "fields", "agentConfigId": "campa123", "fields": [ { "key": "greeting" } ] } }, "agent": { "summary": "Review the complete Agent configuration", "value": { "mode": "agent", "agentConfigId": "campa123" } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Agents" ] } }, "/api/v2/apps": { "get": { "operationId": "appsGetIndex", "summary": "List agent apps", "description": "Lists the Vader apps available to the selected Computer Agent account. Each manifest reports whether the app is installed and active and describes any account-specific setup requirements. Read an individual app before installing it when its dependencies require configuration values.\n", "parameters": [ { "name": "targetAccountId", "in": "query", "required": false, "description": "Computer Agent account whose app state should be used. Defaults to the API token account.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Available app manifests and installation state", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "apps": { "type": "array", "items": { "$ref": "#/components/schemas/AgentAppManifest" } } }, "required": [ "apps" ] } } } }, "401": { "description": "The Vida API token is missing or invalid" }, "403": { "description": "The API token cannot access the selected account" }, "404": { "description": "The selected account was not found" }, "502": { "description": "Vader could not provide the app catalog" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Apps" ] } }, "/api/v2/apps/functions": { "get": { "operationId": "appsGetFunctions", "summary": "List enabled app functions", "description": "Lists the Vader integration functions enabled on the selected Computer Agent's published Agent configuration. Call this operation immediately before choosing a function: use the returned appId, appVersion, and name as the exact invocation path, and construct arguments from that function's parameters JSON Schema. Functions from unassigned, disabled, or unpublished apps are omitted. Functions whose app is not installed are also omitted. An empty functions array means this Agent currently has no callable app functions.\n", "parameters": [ { "name": "targetAccountId", "in": "query", "required": true, "description": "Computer Agent account whose enabled app functions should be used.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Enabled app function catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "functions": { "type": "array", "items": { "type": "object", "required": [ "appId", "appVersion", "name", "description", "parameters", "href" ], "properties": { "appId": { "type": "string", "description": "Exact app identifier to place in the invocation path.", "example": "googleCalendar" }, "appVersion": { "type": "string", "description": "Exact app version to place in the invocation path.", "example": "v1" }, "name": { "type": "string", "description": "Exact function name to place in the invocation path.", "example": "checkGoogleAvailability" }, "description": { "type": "string", "description": "What the function does and any function-specific usage guidance." }, "category": { "type": "string", "nullable": true }, "parameters": { "type": "object", "additionalProperties": true, "description": "JSON Schema for the arguments object accepted by this function." }, "appInstructions": { "type": "string", "nullable": true, "description": "Agent-specific instructions for when and how to use this app." }, "href": { "type": "string", "description": "Relative POST path for this exact function and target account.", "example": "/api/v2/apps/googleCalendar/v1/functions/checkGoogleAvailability?targetAccountId=1881960" } } } } }, "required": [ "functions" ] } } } }, "401": { "description": "The Vida API token is missing or invalid" }, "403": { "description": "The API token cannot access the selected account" }, "404": { "description": "The selected account or its published Agent configuration was not found" }, "502": { "description": "Vader could not provide the enabled function catalog" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Apps" ] } }, "/api/v2/apps/{appId}/{appVersion}/functions/{functionName}": { "post": { "operationId": "appsPostFunction", "summary": "Run an enabled app function", "description": "Runs one function returned by GET /api/v2/apps/functions. Use the exact appId, appVersion, and name from the latest catalog response, and send an arguments object that matches its parameters JSON Schema. Vida re-resolves the published Agent configuration and rejects functions that are no longer assigned and enabled, or whose app is no longer installed. Do not send caller, account, Agent configuration, provider credentials, or app manifest data—Vida supplies the required context server-side. Each POST executes the function directly; after an ambiguous timeout on a function that changes external data, confirm the outcome before retrying it.\n", "parameters": [ { "name": "appId", "in": "path", "required": true, "description": "App identifier returned by GET /api/v2/apps/functions.", "schema": { "type": "string", "minLength": 1 } }, { "name": "appVersion", "in": "path", "required": true, "description": "App version returned by GET /api/v2/apps/functions.", "schema": { "type": "string", "minLength": 1 } }, { "name": "functionName", "in": "path", "required": true, "description": "Function name returned by GET /api/v2/apps/functions.", "schema": { "type": "string", "minLength": 1 } }, { "name": "targetAccountId", "in": "query", "required": true, "description": "Computer Agent account whose enabled app functions should be used.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Function result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "function": { "type": "object", "required": [ "appId", "appVersion", "name" ], "properties": { "appId": { "type": "string" }, "appVersion": { "type": "string" }, "name": { "type": "string" } } }, "result": { "type": "object", "additionalProperties": true, "description": "Vader function response, including its status, message, data, and metadata when provided." } }, "required": [ "function", "result" ] } } } }, "400": { "description": "Arguments do not match the live function schema" }, "401": { "description": "The Vida API token is missing or invalid" }, "403": { "description": "The API token cannot access the selected account" }, "404": { "description": "The app is not installed or its function is not assigned and enabled on the published Agent configuration" }, "502": { "description": "Vader or the underlying integration could not execute the function" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "arguments" ], "additionalProperties": false, "properties": { "arguments": { "type": "object", "additionalProperties": true, "description": "Arguments matching the selected function's parameters JSON Schema." } } }, "examples": { "checkAvailability": { "summary": "Check Google Calendar availability", "value": { "arguments": { "startDateTime": "2026-08-27T15:00:00Z", "endDateTime": "2026-08-27T16:00:00Z", "timeZone": "America/Denver" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Apps" ] } }, "/api/v2/apps/{appId}/{appVersion}": { "get": { "operationId": "appsGetRecord", "summary": "Get agent app", "description": "Returns one Vader app manifest and its installation and activation state for the selected Computer Agent account. Inspect dependencies and their required values before installing or updating the app. Use the exact appId and appVersion returned by the app catalog.\n", "parameters": [ { "name": "appId", "in": "path", "required": true, "description": "App identifier returned by GET /api/v2/apps.", "schema": { "type": "string", "minLength": 1 } }, { "name": "appVersion", "in": "path", "required": true, "description": "Exact app version returned by GET /api/v2/apps.", "schema": { "type": "string", "minLength": 1 } }, { "name": "targetAccountId", "in": "query", "required": false, "description": "Computer Agent account whose app state should be used. Defaults to the API token account.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "App manifest and account-specific state", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "app": { "$ref": "#/components/schemas/AgentAppManifest" } }, "required": [ "app" ] } } } }, "401": { "description": "The Vida API token is missing or invalid" }, "403": { "description": "The API token cannot access the selected account" }, "404": { "description": "The selected account or app was not found" }, "502": { "description": "Vader could not provide the app manifest" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Apps" ] }, "post": { "operationId": "appsPostRecord", "summary": "Install agent app", "description": "Installs the selected Vader app for the Computer Agent account. Read the app manifest first and when its dependencies require configuration or authentication values, send that complete app manifest with the required values filled in. Omit app when the catalog manifest needs no changes. After installation, verify the returned active state before enabling its functions in an Agent configuration. Do not send an empty object as app because Vader treats app as a replacement manifest.\n", "parameters": [ { "name": "appId", "in": "path", "required": true, "description": "App identifier returned by GET /api/v2/apps.", "schema": { "type": "string", "minLength": 1 } }, { "name": "appVersion", "in": "path", "required": true, "description": "Exact app version returned by GET /api/v2/apps.", "schema": { "type": "string", "minLength": 1 } }, { "name": "targetAccountId", "in": "query", "required": false, "description": "Computer Agent account whose app state should be used. Defaults to the API token account.", "schema": { "type": "integer" } } ], "responses": { "201": { "description": "App installed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "app": { "$ref": "#/components/schemas/AgentAppManifest" } }, "required": [ "app" ] } } } }, "400": { "description": "The app payload is invalid" }, "401": { "description": "The Vida API token is missing or invalid" }, "403": { "description": "The API token cannot access the selected account" }, "404": { "description": "The selected account or catalog app was not found" }, "409": { "description": "The app is already installed for the selected account" }, "502": { "description": "Vader could not install the app" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "app": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Complete app manifest returned by GET, with required dependency values filled in." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Apps" ] }, "put": { "operationId": "appsPutRecord", "summary": "Update installed agent app", "description": "Updates an installed Vader app for the selected Computer Agent account. To change configuration, fetch the current app, edit its dependency values, and send that complete manifest as app. Set reload to true to replace its stored manifest with the current catalog manifest. Read the returned manifest and verify active before relying on its functions.\n", "parameters": [ { "name": "appId", "in": "path", "required": true, "description": "App identifier returned by GET /api/v2/apps.", "schema": { "type": "string", "minLength": 1 } }, { "name": "appVersion", "in": "path", "required": true, "description": "Exact app version returned by GET /api/v2/apps.", "schema": { "type": "string", "minLength": 1 } }, { "name": "targetAccountId", "in": "query", "required": false, "description": "Computer Agent account whose app state should be used. Defaults to the API token account.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Updated app manifest and activation state", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "app": { "$ref": "#/components/schemas/AgentAppManifest" } }, "required": [ "app" ] } } } }, "400": { "description": "The app or reload value is invalid" }, "401": { "description": "The Vida API token is missing or invalid" }, "403": { "description": "The API token cannot access the selected account" }, "404": { "description": "The selected account or installed app was not found" }, "502": { "description": "Vader could not update the app" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "app": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Complete current app manifest with updated dependency values." }, "reload": { "type": "boolean", "nullable": true, "default": false, "description": "Reload the current catalog manifest instead of applying app values." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Apps" ] }, "delete": { "operationId": "appsDeleteRecord", "summary": "Uninstall agent app", "description": "Uninstalls the selected Vader app from the Computer Agent account. Remove or disable its app assignment and enabled functions in the Agent staging configuration before publishing, then verify the app no longer reports installed.\n", "parameters": [ { "name": "appId", "in": "path", "required": true, "description": "App identifier returned by GET /api/v2/apps.", "schema": { "type": "string", "minLength": 1 } }, { "name": "appVersion", "in": "path", "required": true, "description": "Exact app version returned by GET /api/v2/apps.", "schema": { "type": "string", "minLength": 1 } }, { "name": "targetAccountId", "in": "query", "required": false, "description": "Computer Agent account whose app state should be used. Defaults to the API token account.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "App uninstalled successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "allOf": [ { "type": "object", "additionalProperties": false } ] } } } }, "401": { "description": "The Vida API token is missing or invalid" }, "403": { "description": "The API token cannot access the selected account" }, "404": { "description": "The selected account or installed app was not found" }, "502": { "description": "Vader could not uninstall the app" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Apps" ] } }, "/api/v2/integration/{integrationSlug}/{integrationVersion}": { "get": { "operationId": "appsGetIntegration", "summary": "Fetch integration data", "description": "Retrieves the saved configuration for a Vader integration. Use the integration slug configured for the account and omit integrationVersion to use the legacy v1 default.\n", "parameters": [ { "name": "integrationSlug", "in": "path", "required": true, "description": "Slug identifier for the Vader integration.", "schema": { "type": "string", "minLength": 1 } }, { "name": "integrationVersion", "in": "path", "required": true, "description": "Integration version. Defaults to v1.", "schema": { "type": "string", "minLength": 1 } }, { "name": "targetAccountId", "in": "query", "required": false, "description": "Computer Agent account whose app state should be used. Defaults to the API token account.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Integration data found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "appId": { "type": "string", "example": "squire" }, "appVersion": { "type": "string", "example": "v1" }, "appData": { "type": "object", "additionalProperties": true } }, "required": [ "message", "appId", "appVersion", "appData" ] } } } }, "400": { "description": "The integration slug is not allowed" }, "401": { "description": "The Vida API token is missing or invalid" }, "404": { "description": "Integration data was not found" }, "500": { "description": "Integration data could not be fetched" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Integrations" ] }, "put": { "operationId": "appsPutIntegration", "summary": "Update integration data", "description": "Shallow-merges appData into an existing Vader integration configuration and returns the stored result. Use POST on this same path when the integration may not have been configured yet.\n", "parameters": [ { "name": "integrationSlug", "in": "path", "required": true, "description": "Slug identifier for the Vader integration.", "schema": { "type": "string", "minLength": 1 } }, { "name": "integrationVersion", "in": "path", "required": true, "description": "Integration version. Defaults to v1.", "schema": { "type": "string", "minLength": 1 } }, { "name": "targetAccountId", "in": "query", "required": false, "description": "Computer Agent account whose app state should be used. Defaults to the API token account.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Integration data updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Integration data updated successfully" }, "appId": { "type": "string", "example": "squire" }, "appVersion": { "type": "string", "example": "v1" }, "appData": { "type": "object", "additionalProperties": true } }, "required": [ "message", "appId", "appVersion", "appData" ] } } } }, "400": { "description": "The integration slug or appData is invalid" }, "401": { "description": "The Vida API token is missing or invalid" }, "404": { "description": "Existing integration data was not found" }, "500": { "description": "Integration data could not be updated" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "appData" ], "properties": { "appData": { "type": "object", "additionalProperties": true, "description": "Integration-specific settings to merge into the existing configuration." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Integrations" ] } }, "/api/v2/email/inboundPolicy": { "get": { "operationId": "inboundPolicyGetIndex", "summary": "Get the inbound email policy", "description": "Returns whether the selected Agent accepts inbound email from any sender or only from its access list. The response also includes the current access list.\n", "parameters": [], "responses": { "200": { "description": "Inbound email policy", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "mode": { "type": "string", "enum": [ "allowlist", "open" ] }, "whitelist": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "label": { "type": "string" } } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Inbound Email" ] }, "put": { "operationId": "inboundPolicyPutIndex", "summary": "Update the inbound email policy", "description": "Changes the selected Agent between access-list-only and open inbound email. Read the current policy first and verify it again after the update.\n", "parameters": [], "responses": { "200": { "description": "Updated inbound email policy", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "mode": { "type": "string", "enum": [ "allowlist", "open" ] }, "whitelist": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "description": "" } }, "required": [ "mode" ] } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Inbound Email" ] } }, "/api/v2/email/inboundWhitelist": { "get": { "operationId": "inboundWhitelistGetIndex", "summary": "List allowed inbound email senders", "description": "Returns the selected Agent's inbound email access list and current policy mode.\n", "parameters": [], "responses": { "200": { "description": "Allowed inbound email senders", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "mode": { "type": "string", "enum": [ "allowlist", "open" ] }, "whitelist": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "label": { "type": "string" } } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Inbound Email" ] }, "post": { "operationId": "inboundWhitelistPostIndex", "summary": "Allow an inbound email sender", "description": "Adds one sender to the selected Agent's inbound email access list. This list controls delivery only while the policy is set to allowlist.\n", "parameters": [], "responses": { "201": { "description": "Sender added", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "allOf": [ { "type": "object", "additionalProperties": true } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "" }, "label": { "type": "string", "description": "" } }, "required": [ "email", "label" ] } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Inbound Email" ] }, "delete": { "operationId": "inboundWhitelistDeleteIndex", "summary": "Remove an allowed inbound email sender", "description": "Removes one sender from the selected Agent's inbound email access list. Confirm the exact address before removing it, then re-read the list.\n", "parameters": [ { "name": "email", "in": "query", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sender removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "allOf": [ { "type": "object", "additionalProperties": true } ] } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Inbound Email" ] } }, "/api/v2/experiments": { "get": { "operationId": "experimentsGetIndex", "summary": "List agent experiments", "description": "Lists experiments for the selected organization. Supply agentConfigId to limit the results to one live agent configuration.\n", "parameters": [ { "name": "agentConfigId", "in": "query", "required": false, "description": "Live agent configuration ID.", "schema": { "type": "string" } }, { "name": "targetAccountId", "in": "query", "required": true, "description": "Account used to authorize this request.", "schema": {} } ], "responses": { "200": { "description": "Agent experiments", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentExperiment" } }, "status": { "type": "string", "example": "ok" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Agents" ] }, "post": { "operationId": "experimentsPostIndex", "summary": "Create agent experiment", "description": "Creates an experiment from at least two saved versions of the same live agent configuration. The weights are relative and do not need to total 100. Only one experiment for an agent configuration may be active at a time.\n", "parameters": [ { "name": "targetAccountId", "in": "query", "required": true, "description": "Account used to authorize this request.", "schema": {} } ], "responses": { "201": { "description": "Experiment created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentExperiment" }, "status": { "type": "string", "example": "created" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentConfigId", "variants" ], "properties": { "agentConfigId": { "type": "string", "description": "Live agent configuration ID whose saved versions will be tested." }, "name": { "type": "string", "default": "Untitled Experiment" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ], "default": "active" }, "variants": { "type": "array", "minItems": 2, "items": { "$ref": "#/components/schemas/AgentExperimentVariant" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Agents" ] } }, "/api/v2/experiments/{experimentId}": { "get": { "operationId": "experimentsGetShow", "summary": "Get agent experiment", "description": "Returns one experiment available to the selected organization.", "parameters": [ { "name": "experimentId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "targetAccountId", "in": "query", "required": true, "description": "", "schema": {} } ], "responses": { "200": { "description": "Agent experiment", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentExperiment" }, "status": { "type": "string", "example": "ok" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Agents" ] }, "put": { "operationId": "experimentsPutRecord", "summary": "Update agent experiment", "description": "Renames an experiment and, while it is still a draft, can replace its saved-version variants. agentConfigId must match the experiment.\n", "parameters": [ { "name": "experimentId", "in": "path", "required": true, "description": "", "schema": {} }, { "name": "targetAccountId", "in": "query", "required": true, "description": "Account used to authorize this request.", "schema": {} } ], "responses": { "200": { "description": "Experiment updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentExperiment" }, "status": { "type": "string", "example": "ok" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentConfigId", "name" ], "properties": { "agentConfigId": { "type": "string" }, "name": { "type": "string" }, "variants": { "type": "array", "minItems": 2, "items": { "$ref": "#/components/schemas/AgentExperimentVariant" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Agents" ] }, "delete": { "operationId": "experimentsDeleteShow", "summary": "Delete agent experiment", "description": "Deletes a draft, paused, or ended experiment. Active experiments must be paused or ended first.", "parameters": [ { "name": "experimentId", "in": "path", "required": true, "description": "", "schema": {} }, { "name": "targetAccountId", "in": "query", "required": true, "description": "", "schema": {} } ], "responses": { "200": { "description": "Experiment deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "deleted", "id" ], "properties": { "deleted": { "type": "boolean", "example": true }, "id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] } } }, "status": { "type": "string", "example": "ok" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Agents" ] } }, "/api/v2/experiments/{experimentId}/status": { "post": { "operationId": "experimentsPostStatus", "summary": "Change agent experiment status", "description": "Starts, pauses, or ends an experiment. Starting an experiment routes new conversations deterministically across its saved-version variants according to their relative weights.\n", "parameters": [ { "name": "experimentId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "targetAccountId", "in": "query", "required": true, "description": "Account used to authorize this request.", "schema": {} } ], "responses": { "200": { "description": "Experiment status updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentExperiment" }, "status": { "type": "string", "example": "ok" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agentConfigId", "status" ], "properties": { "agentConfigId": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Agents" ] } }, "/api/v2/features/assign": { "post": { "operationId": "assignPostIndex", "summary": "Assign account features", "description": "Assigns one or more features to a child account. Partners may manage reseller or organization assignments; resellers may manage organization assignments. Every feature must already be granted to the caller's account.\n", "parameters": [ { "name": "targetAccountId", "in": "query", "required": true, "description": "Reseller or organization account receiving the feature assignments.", "schema": {} } ], "responses": { "200": { "description": "Features assigned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "featureIds": { "type": "array", "items": { "type": "string" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "features" ], "properties": { "features": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "featureId", "price" ], "properties": { "featureId": { "type": "string" }, "price": { "type": "number", "minimum": 0 } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Features" ] }, "delete": { "operationId": "assignDeleteIndex", "summary": "Remove account features", "description": "Removes selected feature assignments from a child account. Read the current assignments first and confirm that dependent Agent capabilities may stop working before removing them.\n", "parameters": [ { "name": "featureIds", "in": "query", "required": true, "description": "Feature IDs to remove.", "schema": {}, "example": [ "feature-id" ] }, { "name": "targetAccountId", "in": "query", "required": true, "description": "Reseller or organization account losing the feature assignments.", "schema": {} } ], "responses": { "200": { "description": "Feature assignments removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "featureIds": { "type": "array", "items": { "type": "string" } }, "notAssignedFeatureIds": { "type": "array", "items": { "type": "string" } } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Features" ] } }, "/api/v2/features": { "get": { "operationId": "featuresGetIndex", "summary": "List available account features", "description": "Lists features the requesting partner or reseller may manage for the selected account. Each result identifies whether the feature is enabled and may include its assigned price. Only features granted to the parent account can be assigned to a child account.\n", "parameters": [], "responses": { "200": { "description": "Available account features", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "features": { "type": "array", "items": { "type": "object", "properties": { "featureId": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "enabled": { "type": "boolean" }, "price": { "type": "number", "nullable": true } }, "additionalProperties": true } } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Features" ] } }, "/api/v2/logs/timeSeries": { "post": { "operationId": "timeSeriesPostIndex", "summary": "Calculate a conversation metric", "description": "Calculates an aggregate metric from conversation logs for the selected account and time range. Results can also include time buckets and, for eligible reseller accounts, organization or agent comparisons. Use the normal conversation logs endpoint to inspect the records behind a metric.\n", "parameters": [], "responses": { "200": { "description": "Metric calculated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "aggregate": { "type": "number", "nullable": true, "description": "Metric value across every matching conversation." }, "metricTotal": { "type": "number", "description": "Sum used to calculate the aggregate." }, "eventCount": { "type": "integer", "minimum": 0, "description": "Number of matching conversation records." }, "minimumSampleSize": { "type": "integer", "minimum": 1, "description": "Requested minimum sample size, when supplied." }, "qualified": { "type": "boolean", "description": "Whether the aggregate meets the requested minimum sample size." }, "timeSeries": { "type": "object", "additionalProperties": { "type": "number", "nullable": true }, "description": "Metric values keyed by Unix-second bucket start." }, "timeSeriesEventCounts": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 }, "description": "Matching record counts by bucket when a minimum sample size is used." }, "groups": { "type": "array", "description": "Organization or agent comparisons when groupBy is enabled.", "items": { "type": "object", "properties": { "organizationId": { "type": "integer" }, "organizationName": { "type": "string" }, "agentId": { "type": "integer" }, "agentName": { "type": "string" }, "metricValue": { "type": "number", "nullable": true }, "metricTotal": { "type": "number" }, "eventCount": { "type": "integer", "minimum": 0 } } } }, "pagination": { "type": "object", "description": "Present when grouped results are requested.", "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalCount": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } } }, "400": { "description": "The metric definition, scope, or time range is invalid" }, "504": { "description": "The metric could not be calculated within the allowed time" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "definition", "startAt", "endAt", "targetAccountId" ], "properties": { "targetAccountId": { "type": "integer", "description": "Account whose authorized conversation data should be analyzed." }, "startAt": { "type": "integer", "description": "Inclusive start of the range as Unix seconds." }, "endAt": { "type": "integer", "description": "Inclusive end of the range as Unix seconds. Must be after startAt." }, "definition": { "type": "object", "required": [ "formula", "aggregation" ], "description": "Metric calculation applied to each matching conversation log.", "properties": { "formula": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Numeric expression to aggregate. It may reference log fields and use arithmetic, comparisons, boolean operators, IF, NOW, TIMESTAMP_DIFF, ABS, MIN, MAX, SUM, AVG, COUNT, D_COUNT, MED, VARIANCE, or STD_DEV.\n", "example": "transfer == true" }, "aggregation": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "sum", "avg", "count", "d_count", "med", "variance", "std_dev" ], "description": "How matching formula values are combined." }, "term": { "type": "string", "enum": [ "minutes", "hours", "days", "weeks", "months" ], "description": "Time bucket used when time-series data is requested." } } }, "filters": { "type": "object", "additionalProperties": true, "description": "Conversation-log fields that limit the source records. Append operators such as __gte, __lte, __in, __contains, or __isnull to a field name when needed.\n" }, "fieldTypes": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "number", "boolean", "truthy", "string" ] }, "description": "Value types for custom fields referenced by the formula." }, "minimumSampleSize": { "type": "integer", "minimum": 1, "description": "Hide metric values for groups or buckets with fewer matching records." } } }, "includeTimeSeries": { "type": "boolean", "default": true, "description": "Include metric values grouped into time buckets." }, "groupBy": { "type": "string", "enum": [ "none", "organization", "agent" ], "description": "Add ranked group results. Organization and agent grouping are available when the selected account has access to those account levels.\n" }, "scope": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "allOrganizations", "selectedOrganizations" ] }, "organizationIds": { "type": "array", "maxItems": 500, "items": { "type": "integer", "minimum": 1 } } }, "description": "Organization subset used for reseller-level grouped metrics." }, "search": { "type": "string", "maxLength": 100, "description": "Match organization or agent names in grouped results." }, "sort": { "type": "string", "enum": [ "metricValue", "eventCount" ], "default": "metricValue", "description": "Field used to order grouped results." }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction for grouped results." }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Group-result page number." }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Number of grouped results per page." }, "refresh": { "type": "boolean", "default": false, "description": "Recalculate instead of using a recent identical result." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Conversation Logs" ] } }, "/api/v2/computer/accounts/{targetAccountId}/prompts/sync": { "post": { "operationId": "agentsPostPromptSync", "summary": "Refresh Computer Agent instructions", "description": "Reapplies Vida-managed instructions to one or all Computer Agents on the selected account and returns the result for each agent.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/backup": { "post": { "operationId": "backupsPostBackup", "summary": "Create a Computer Agent backup", "description": "Starts an asynchronous backup of the selected Computer Agent and returns a job for tracking its progress.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Backup was accepted" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/backups": { "get": { "operationId": "backupsGetBackups", "summary": "List Computer Agent backups", "description": "Lists available backups and their freshness for the selected Computer Agent.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/backup-job": { "get": { "operationId": "backupsGetLatestBackupJob", "summary": "Get the latest backup job", "description": "Returns the most recent backup request for the selected Computer Agent, or no result when one has not been started.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/backup-jobs/{jobId}": { "get": { "operationId": "backupsGetBackupJob", "summary": "Get a backup job", "description": "Returns the current status and result of one backup request for the selected Computer Agent.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "jobId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/restore": { "post": { "operationId": "backupsPostRestore", "summary": "Restore a Computer Agent backup", "description": "Starts an asynchronous restore from a selected backup and returns a job for tracking its progress. Restoring replaces the Computer Agent's current data. The Computer Agent is stopped and restarted automatically. Read the available backups first and poll the returned restore job until it finishes.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Restore was accepted" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "snapshotId": { "type": "string", "description": "Backup snapshot to restore. Omit to restore the latest available snapshot." }, "delete": { "type": "boolean", "description": "When true, also removes local files that are not present in the selected backup. Send false unless the user explicitly wants an exact replacement.\n" } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/restore-job": { "get": { "operationId": "backupsGetLatestRestoreJob", "summary": "Get the latest restore job", "description": "Returns the most recent restore request for the selected Computer Agent, or no result when one has not been started.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/restore-jobs/{jobId}": { "get": { "operationId": "backupsGetRestoreJob", "summary": "Get a restore job", "description": "Returns the current status and result of one restore request for the selected Computer Agent.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "jobId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/browser/ticket": { "post": { "operationId": "browserPostBrowserTicket", "summary": "Create a browser access ticket", "description": "Creates short-lived interactive browser access for the selected Computer Agent. Open the returned launchRef.href before it expires instead of constructing a browser URL.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Browser access ticket created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "ticket": { "type": "string" }, "expiresAtMs": { "type": "integer", "format": "int64" }, "targetAgentId": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "browserPath": { "type": "string" }, "browserProfile": { "type": "object", "nullable": true, "additionalProperties": true }, "launchRef": { "type": "object", "required": [ "method", "href", "expiresAtMs" ], "properties": { "method": { "type": "string", "enum": [ "GET" ] }, "href": { "type": "string", "format": "uri", "description": "Complete, short-lived URL that opens the interactive browser." }, "expiresAtMs": { "type": "integer", "format": "int64" } } } }, "required": [ "ticket", "expiresAtMs", "targetAgentId", "browserPath", "launchRef" ] } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/browser/automation-sessions": { "post": { "operationId": "browserPostBrowserAutomationSession", "summary": "Create a Computer Agent browser automation session", "description": "Creates a short-lived connection to the selected Computer Agent's browser. Use the returned CDP URL and request header to inspect and automate the browser, including while recording a reusable browser workflow.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Browser automation session created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "targetAgentId": { "type": "string" }, "profile": { "type": "string", "nullable": true }, "slot": { "type": "integer" }, "cdpUrl": { "type": "string", "format": "uri" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "targetAgentId", "profile", "slot", "cdpUrl", "headers", "expiresAt" ] } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ttlSeconds": { "type": "integer", "minimum": 60, "maximum": 1800, "description": "Number of seconds before the connection expires." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/canvas": { "get": { "operationId": "canvasGetCanvas", "summary": "Get Computer Agent Canvas access", "description": "Returns the selected Computer Agent's current Canvas availability, visibility, workspace paths, and a ready-to-open URL when access is available. A public Canvas includes a stable publicUrl. A private Canvas includes only a short-lived launchRef. Visibility is read-only through this API.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Canvas access details", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "available": { "type": "boolean" }, "visibility": { "type": "string", "enum": [ "public", "private", "off" ] }, "sourcePath": { "type": "string", "enum": [ "app" ], "description": "Workspace directory containing editable Canvas source." }, "publishedPath": { "type": "string", "enum": [ "public" ], "description": "Protected workspace directory containing generated Canvas files." }, "publicUrl": { "type": "string", "format": "uri", "nullable": true, "description": "Stable share URL when visibility is public; otherwise null." }, "launchRef": { "type": "object", "nullable": true, "required": [ "method", "href", "expiresAtMs" ], "properties": { "method": { "type": "string", "enum": [ "GET" ] }, "href": { "type": "string", "format": "uri", "description": "Complete URL for opening the Canvas." }, "expiresAtMs": { "type": "integer", "format": "int64", "nullable": true, "description": "Expiration time for private access, or null for a public URL." } } } }, "required": [ "available", "visibility", "sourcePath", "publishedPath", "publicUrl", "launchRef" ] } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/canvas/publish": { "post": { "operationId": "canvasPostPublish", "summary": "Publish a Computer Agent Canvas", "description": "Prepares dependencies declared by the selected Computer Agent's Canvas project when they changed or are unavailable, builds the editable source from the app workspace directory, and replaces the generated files served from public. Read the source first, make the intended workspace changes, publish, and then open the Canvas URL to verify the result.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Canvas published", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "agentId": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "published": { "type": "boolean", "enum": [ true ] }, "publishedAt": { "type": "string", "format": "date-time" }, "phase": { "type": "string", "enum": [ "complete" ] }, "dependencies": { "type": "object", "required": [ "status", "changed" ], "properties": { "status": { "type": "string", "enum": [ "ready", "updated" ] }, "changed": { "type": "boolean" } } } }, "required": [ "agentId", "published", "publishedAt", "phase", "dependencies" ] } } } }, "502": { "description": "Canvas dependency preparation or source build failed. The error payload identifies the failed phase and includes bounded, project-relative output for diagnosing the project.\n" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/channels/web-login/start": { "post": { "operationId": "webLoginPostStart", "summary": "Start a channel web-login flow", "description": "Starts browser or QR-code sign-in for a supported channel and returns the next required step.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "description": "Optional channel account identifier when the channel has multiple accounts." }, "force": { "type": "boolean", "default": false, "description": "Clear the existing sign-in and start a new one." }, "verbose": { "type": "boolean", "default": false, "description": "Include additional sign-in progress details." }, "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 120000, "description": "Maximum time to wait for the sign-in flow to start." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/channels/web-login/wait": { "post": { "operationId": "webLoginPostWait", "summary": "Wait for a channel web login", "description": "Waits for a channel sign-in attempt to complete and returns its result.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "description": "Optional channel account identifier used when sign-in was started." }, "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 180000, "description": "Maximum time to wait for this status request." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/channels/catalog": { "get": { "operationId": "channelsGetCatalog", "summary": "List supported Computer Agent channels", "description": "Lists channels that can be connected to the selected Computer Agent. Each catalog entry describes its connection fields, access controls, and current values for this Computer Agent.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/channels/status": { "get": { "operationId": "channelsGetStatus", "summary": "Get Computer Agent channel status", "description": "Shows the selected Computer Agent's configured channels and their connection status. An optional live check returns current connectivity.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/channels/logout": { "post": { "operationId": "channelsPostLogout", "summary": "Log a channel account out", "description": "Disconnects the selected channel account from the Computer Agent.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "description": "" } }, "required": [ "channel" ] } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/channels/configure": { "post": { "operationId": "channelsPostConfigure", "summary": "Configure a Computer Agent channel", "description": "Connects, updates, enables, or disables one supported channel for the selected Computer Agent. Send the channel identifier with the connection and access fields defined by the channel catalog. Vida assigns the connection and incoming messages to the selected Computer Agent automatically.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string", "description": "Channel identifier from the channel catalog." }, "connection": { "type": "object", "properties": {}, "description": "Connection fields defined by the selected channel catalog entry." }, "access": { "type": "object", "properties": {}, "description": "Direct-message and group access settings for this Computer Agent." }, "enabled": { "type": "boolean", "description": "Whether this Computer Agent can use the channel." } }, "required": [ "channel" ] } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/config": { "get": { "operationId": "configGetConfig", "summary": "Get Computer Agent configuration", "description": "Returns the complete redacted configuration for the selected Computer Agent, including the authored settings, effective settings, revision, validation findings, and the agents sharing the same computer. Use the revision when applying a change.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/config/patch": { "post": { "operationId": "configPostConfigPatch", "summary": "Update Computer Agent configuration", "description": "Merges selected settings into the current Computer Agent configuration. The revision prevents an older read from overwriting a newer change. Read the configuration again after the Computer Agent finishes restarting to verify the result.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "revision", "patch" ], "properties": { "revision": { "type": "string", "description": "Revision returned by the latest configuration read." }, "patch": { "type": "object", "additionalProperties": true, "description": "Settings to merge into the current configuration." }, "replacePaths": { "type": "array", "maxItems": 256, "items": { "type": "string" }, "description": "Array paths that this update is intentionally replacing." }, "note": { "type": "string", "description": "Optional reason for the change." }, "restartDelayMs": { "type": "integer", "minimum": 0, "description": "Optional delay before a required restart begins." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/helpers": { "get": { "operationId": "helpersGetIndex", "summary": "List Computer Agent helpers", "description": "Lists reusable helpers available to the selected Computer Agent, including whether each helper requires Browser access, its exact arguments, its owning skill, and which managed secrets must be configured. Create a helper as part of a Computer Agent skill, then use this operation to verify its callable contract before adding it to conversational Agent instructions.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/helpers/execute": { "post": { "operationId": "helpersPostExecute", "summary": "Execute a registered Computer Agent helper", "description": "Runs a registered helper for the selected Computer Agent with optional arguments. Vida supplies any managed secrets declared by the helper; secret values are never accepted in this request. Use this operation to test the exact helper and arguments before making it available to a conversational Agent through the Computer function.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "" }, "arguments": { "description": "" } }, "required": [ "name", "arguments" ] } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/helpers/refresh": { "post": { "operationId": "helpersPostRefresh", "summary": "Refresh and validate Computer Agent helpers", "description": "Rebuilds the selected Computer Agent's helper registration from the helper source files in its installed skills, then validates the registered contracts and source files. Run this after creating or changing a helper. A successful refresh means the helper is registered and its source passed validation; list the helpers and execute a representative request before making the helper available to conversations.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Helper registration and validation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "ok": { "type": "boolean" }, "status": { "type": "string", "enum": [ "done", "failed" ] }, "agentId": { "type": "string" }, "functions": { "type": "array", "items": { "type": "object", "required": [ "name", "description", "args", "result", "requiresBrowser", "requiredSecrets" ], "properties": { "name": { "type": "string" }, "domain": { "type": "string" }, "description": { "type": "string" }, "args": { "type": "object", "additionalProperties": true }, "result": { "type": "object", "additionalProperties": true }, "source": { "type": "string" }, "skillSlug": { "type": "string", "nullable": true }, "requiresBrowser": { "type": "boolean" }, "requiredSecrets": { "type": "array", "items": { "type": "string" } } } } }, "validation": { "type": "object", "required": [ "compile", "missingExports", "staleRegistryEntries", "missingRegistryEntries", "errors" ], "properties": { "compile": { "type": "array", "items": { "type": "object", "required": [ "path", "ok" ], "properties": { "path": { "type": "string" }, "ok": { "type": "boolean" }, "error": { "type": "string", "nullable": true } } } }, "missingExports": { "type": "array", "items": { "type": "string" } }, "staleRegistryEntries": { "type": "array", "items": { "type": "string" } }, "missingRegistryEntries": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "string" } } } } }, "required": [ "ok", "status", "agentId", "functions", "validation" ] } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/provision": { "post": { "operationId": "lifecyclePostProvision", "summary": "Provision or reconcile a Computer Agent", "description": "Sets up the selected Computer Agent using Vida's current published version, or reconciles its existing shared Computer. Reconciliation can briefly interrupt other Agents on that Computer. Check status until the operation is terminal, then verify Computer health.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Computer Agent setup was accepted" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/deprovision": { "post": { "operationId": "lifecyclePostDeprovision", "summary": "Deprovision a Computer Agent", "description": "Removes the shared Computer used by the selected Agent and stops Computer access for every Agent assigned to it. By default saved state is preserved so it can be provisioned again later. Permanent removal first requires a successful recent safety backup.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The shared Computer was deprovisioned" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "wipeState": { "type": "boolean", "default": false, "description": "Permanently delete the Computer Agent's saved state after its safety backup. Use only when the user explicitly requests a fresh start.\n" } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/restart": { "post": { "operationId": "lifecyclePostRestart", "summary": "Restart a Computer Agent", "description": "Restarts the shared Computer used by the selected Agent. Other Agents assigned to that Computer are briefly unavailable. Check status until the operation is terminal, then verify Computer health.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Restart was accepted" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/upgrade": { "post": { "operationId": "lifecyclePostUpgrade", "summary": "Upgrade a Computer Agent", "description": "Upgrades the shared Computer to Vida's current published version, refreshes managed workspace templates without replacing customer Canvas or project files, and affects every Agent assigned to that Computer. Check status until the operation is terminal, then verify Computer health.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Upgrade was accepted" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/status": { "get": { "operationId": "lifecycleGetStatus", "summary": "Get Computer Agent status", "description": "Returns the selected Computer Agent's deployment version, readiness, and latest lifecycle operation. An unprovisioned Agent returns 404. A terminal operation remains available in the lifecycle field so callers can reconcile the accepted job before checking Computer health.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Computer Agent deployment status" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/secrets": { "get": { "operationId": "managedSecretsGetIndex", "summary": "List Computer Agent secrets", "description": "Lists saved secrets for the selected Computer Agent without returning their secret values.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": {} } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] }, "post": { "operationId": "managedSecretsPostCreateOrUpdate", "summary": "Save a Computer Agent secret", "description": "Creates or updates a secret for the selected Computer Agent.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": {} } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "secretId": { "description": "" }, "value": { "description": "" } }, "required": [ "secretId", "value" ] } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/secrets/delete": { "post": { "operationId": "managedSecretsPostDelete", "summary": "Delete a Computer Agent secret", "description": "Deletes one secret from the selected Computer Agent. Skills or integrations that use the secret may stop working.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": {} } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "secretId": { "description": "" } }, "required": [ "secretId" ] } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/secrets/check": { "post": { "operationId": "managedSecretsPostCheck", "summary": "Check Computer Agent secrets", "description": "Checks whether selected secrets are available to the Computer Agent without exposing their values.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": {} } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/secrets/reapply": { "post": { "operationId": "managedSecretsPostReapply", "summary": "Reapply a Computer Agent secret", "description": "Makes a saved secret available to the selected Computer Agent again.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": {} } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "secretId": { "description": "" } }, "required": [ "secretId" ] } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/memory/explorer": { "get": { "operationId": "memoryGetExplorer", "summary": "Explore Computer Agent memories", "description": "Returns memory statistics, recent items, search results, and a timeline for the selected Computer Agent. Private memories are shown by default, with options for broader accessible scopes.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/memory": { "post": { "operationId": "memoryPostIndex", "summary": "Store a Computer Agent memory", "description": "Stores a memory for the selected Computer Agent with optional category, importance, and access settings.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": {} } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "description": "" } }, "required": [ "text" ] } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/memory/{memoryId}": { "post": { "operationId": "memoryPostRecord", "summary": "Update a Computer Agent memory", "description": "Updates the text, category, or importance of one memory available to the selected Computer Agent. Include at least one field to change.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": {} }, { "name": "memoryId", "in": "path", "required": true, "description": "", "schema": {} } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "text": { "type": "string", "description": "Replacement memory text." }, "category": { "type": "string", "enum": [ "preference", "fact", "decision", "entity", "other" ], "description": "Replacement memory category." }, "importance": { "type": "number", "minimum": 0, "maximum": 1, "description": "Replacement importance from 0 to 1." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/memory/{memoryId}/delete": { "post": { "operationId": "memoryPostRecordDelete", "summary": "Delete a Computer Agent memory", "description": "Permanently deletes one memory available to the selected Computer Agent.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": {} }, { "name": "memoryId", "in": "path", "required": true, "description": "", "schema": {} } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/config/schema": { "get": { "operationId": "runtimeGetSchema", "summary": "Get available Computer Agent settings", "description": "Lists the supported configuration settings and accepted values for the selected Computer Agent.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/runtime/health": { "get": { "operationId": "runtimeGetHealth", "summary": "Check Computer Agent health", "description": "Returns whether the selected Computer Agent is healthy and ready. Use it after setup, configuration, restart, or upgrade changes.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/runtime/logs": { "get": { "operationId": "runtimeGetLogs", "summary": "Get recent Computer Agent logs", "description": "Returns a limited page of recent logs for the selected Computer Agent with cursor pagination.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/runtime/service-logs": { "get": { "operationId": "runtimeGetServiceLogs", "summary": "Get recent Computer Agent service logs", "description": "Returns recent service logs for the selected Computer Agent with optional line-count and time-window limits.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recent Computer Agent service logs", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "customerId": { "type": "string" }, "tail": { "type": "integer" }, "sinceSeconds": { "type": "integer", "nullable": true }, "logs": { "type": "string" }, "truncated": { "type": "boolean" }, "maxBytes": { "type": "integer" } } } } } }, "404": { "description": "Computer Agent service was not found" }, "502": { "description": "Computer Agent service logs could not be read" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/runtime/diagnostics": { "get": { "operationId": "runtimeGetDiagnostics", "summary": "Diagnose a Computer Agent", "description": "Runs read-only checks and returns structured findings for the computer hosting the selected agent. Findings include stable codes, severity, and affected configuration paths.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/runtime/repair": { "post": { "operationId": "runtimePostRepair", "summary": "Repair a Computer Agent", "description": "Starts the supported repair operation for the computer hosting the selected agent. The operation verifies the result with read-only diagnostics. Poll the Computer Agent lifecycle status until the returned repair job finishes.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "confirm" ], "properties": { "confirm": { "type": "boolean", "enum": [ true ], "description": "Confirms that the repair should start." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/skills/{skillSlug}/auth/{actionId}/start": { "post": { "operationId": "authPostStart", "summary": "Start a skill authentication action", "description": "Starts one sign-in action returned by the latest skill verification. The response uses the same session fields as the sign-in status endpoint. Poll status until it returns a user handoff or a terminal result.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "skillSlug", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "actionId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Skill sign-in started", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "result": { "type": "object", "required": [ "skillSlug", "actionId", "session" ], "properties": { "skillSlug": { "type": "string" }, "actionId": { "type": "string" }, "session": { "type": "object", "required": [ "actionId", "status" ], "properties": { "actionId": { "type": "string" }, "jobId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "queued", "launching", "running", "browser_ready", "waiting_for_user", "succeeded", "failed", "cancelling", "cancelled", "unknown" ] }, "phase": { "type": "string", "nullable": true }, "browserNavigateUrl": { "type": "string", "format": "uri", "nullable": true }, "capturedDeviceCode": { "type": "string", "nullable": true }, "error": { "type": "object", "nullable": true, "additionalProperties": true } } } } } }, "required": [ "result" ] } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/skills/{skillSlug}/auth/{actionId}": { "get": { "operationId": "authGetStatus", "summary": "Get skill authentication action status", "description": "Returns the current status of one skill sign-in attempt. Present browserNavigateUrl or capturedDeviceCode to the user when provided. Continue polling until status is succeeded, failed, or cancelled, then verify the skill again.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "skillSlug", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "actionId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Skill sign-in status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "result": { "type": "object", "required": [ "skillSlug", "actionId", "session" ], "properties": { "skillSlug": { "type": "string" }, "actionId": { "type": "string" }, "session": { "type": "object", "required": [ "actionId", "status" ], "properties": { "actionId": { "type": "string" }, "requiredActionId": { "type": "string", "nullable": true }, "jobId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "queued", "launching", "running", "browser_ready", "waiting_for_user", "succeeded", "failed", "cancelling", "cancelled", "unknown" ] }, "phase": { "type": "string", "nullable": true }, "accepted": { "type": "boolean" }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "browserNavigateUrl": { "type": "string", "format": "uri", "nullable": true }, "capturedDeviceCode": { "type": "string", "nullable": true }, "error": { "type": "object", "nullable": true, "additionalProperties": true } } } } } }, "required": [ "result" ] } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/skills/{skillSlug}/auth/{actionId}/cancel": { "post": { "operationId": "authPostCancel", "summary": "Cancel a skill authentication action", "description": "Cancels one active skill sign-in attempt. Use this only when the user abandons the sign-in or the current attempt must be restarted.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "skillSlug", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "actionId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/skills/catalog": { "get": { "operationId": "skillsGetCatalog", "summary": "List available Computer Agent skills", "description": "Lists skills available to the selected Computer Agent and shows whether each one is currently installed and ready. Use a skill's skillSlug to read its detail before installation.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Available Computer Agent skills", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "results": { "type": "array", "items": { "type": "object", "required": [ "skillSlug", "name", "status", "installOptions", "installed", "runtimeReady", "ready" ], "properties": { "skillSlug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string", "nullable": true }, "status": { "type": "string" }, "installOptions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "installed": { "type": "boolean" }, "runtimeReady": { "type": "boolean" }, "setupComplete": { "type": "boolean", "nullable": true }, "verifiedReady": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true } } }, "required": [ "results" ] } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/skills/catalog/{skillSlug}": { "get": { "operationId": "skillsGetCatalogDetail", "summary": "Get Computer Agent skill details", "description": "Returns the description, installation options, current readiness, and latest verification for one available skill. After installation, use verification.requiredActions as the current setup plan.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "skillSlug", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Computer Agent skill detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "result": { "type": "object", "required": [ "skillSlug", "name", "installOptions", "installed", "runtimeReady", "ready" ], "properties": { "skillSlug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string", "nullable": true }, "installOptions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "accountState": { "type": "object", "nullable": true, "additionalProperties": true }, "verification": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Latest verification, including result.requiredActions when setup remains." }, "installed": { "type": "boolean" }, "runtimeReady": { "type": "boolean" }, "setupComplete": { "type": "boolean", "nullable": true }, "verifiedReady": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true } }, "required": [ "result" ] } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/skills/state": { "get": { "operationId": "skillsGetState", "summary": "Get installed Computer Agent skills", "description": "Returns the installed skills and their current state for the selected Computer Agent.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/skills/{skillSlug}/setup-values": { "get": { "operationId": "skillsGetSetupValue", "summary": "Get a Computer Agent skill setup value", "description": "Reads a setup storage key declared by the selected skill. The response returns non-sensitive values and reports whether sensitive values are already configured without returning their contents.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "skillSlug", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "storageKey", "in": "query", "required": true, "description": "Storage key declared by the selected skill catalog entry.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Skill setup value status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "storageKey": { "type": "string" }, "source": { "type": "string", "enum": [ "setup_state", "skill_configuration" ] }, "hasValue": { "type": "boolean" }, "valueVisibility": { "type": "string", "enum": [ "plaintext", "redacted" ] }, "shared": { "type": "boolean" }, "editable": { "type": "boolean" }, "currentValue": { "description": "Present only when a non-sensitive value exists and may be returned." } }, "required": [ "storageKey", "source", "hasValue", "valueVisibility", "shared", "editable" ] } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/skills/install": { "post": { "operationId": "skillsPostInstall", "summary": "Install a Computer Agent skill", "description": "Installs one skill returned by the Computer Agent skill catalog. Read the skill detail first and select an installation option when more than one is available. Verify the skill immediately after installation to obtain its current setup requirements.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Skill installation finished", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "curated": { "type": "boolean" }, "catalog": { "type": "object", "additionalProperties": true, "description": "Refreshed skill detail and readiness state." }, "install": { "type": "object", "additionalProperties": true } }, "required": [ "curated", "catalog" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "skillSlug" ], "properties": { "skillSlug": { "type": "string", "description": "Skill identifier returned by the skill catalog." }, "installId": { "type": "string", "description": "Installation option identifier returned by the skill detail." }, "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 300000, "default": 300000, "description": "Maximum time allowed for installation." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/skills/{skillSlug}/verify": { "post": { "operationId": "skillsPostVerify", "summary": "Verify an installed skill", "description": "Checks whether the selected skill is installed and configured. Treat the returned requiredActions as the current setup plan, complete them in order while respecting dependsOn, and verify again until setupComplete is true.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "skillSlug", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Skill verification finished", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "result": { "type": "object", "required": [ "skillSlug", "verification" ], "properties": { "skillSlug": { "type": "string" }, "sessionKey": { "type": "string", "nullable": true }, "verification": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "string", "description": "Current verification outcome." }, "summary": { "type": "string" }, "result": { "type": "object", "required": [ "skillSlug", "runtimeReady", "setupComplete", "requiredActions" ], "properties": { "skillSlug": { "type": "string" }, "runtimeReady": { "type": "boolean" }, "setupComplete": { "type": "boolean" }, "requiredActions": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "label", "description", "status" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "enter_value", "upload_file", "select_option", "oauth", "device_code", "manual_confirmation" ] }, "label": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed" ] }, "order": { "type": "integer" }, "dependsOn": { "type": "array", "items": { "type": "string" } }, "group": { "type": "string" }, "storageKey": { "type": "string" }, "inputKind": { "type": "string", "enum": [ "text", "email", "password", "file", "select", "multiselect" ] }, "sensitive": { "type": "boolean" }, "deliveryMode": { "type": "string", "enum": [ "browser_handoff" ] }, "payload": { "type": "object", "additionalProperties": true } } } } } } } } } } }, "required": [ "result" ] } } } }, "202": { "description": "Skill verification started", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "pending": { "type": "boolean", "enum": [ true ] }, "result": { "type": "object", "required": [ "skillSlug", "verificationJob" ], "properties": { "skillSlug": { "type": "string" }, "verificationJob": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "running", "completed", "failed" ] }, "jobId": { "type": "string", "nullable": true }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "required": [ "pending", "result" ] } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "async": { "type": "boolean", "default": false, "description": "Return an accepted verification job instead of waiting for completion." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/skills/{skillSlug}/disable": { "post": { "operationId": "skillsPostDisable", "summary": "Disable an installed skill", "description": "Disables one installed skill without deleting its saved setup.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "skillSlug", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/skills/{skillSlug}/uninstall": { "post": { "operationId": "skillsPostUninstall", "summary": "Uninstall an installed skill", "description": "Removes one skill from the selected Computer Agent and disables the capability it provides.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "skillSlug", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/skills/{skillSlug}/setup-state": { "post": { "operationId": "skillsPostSetupState", "summary": "Save a Computer Agent skill setting", "description": "Saves one non-sensitive setup value declared by the skill's current required actions. Use the managed skill-configuration endpoint for sensitive values.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "skillSlug", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Skill setting saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "skillSlug": { "type": "string" }, "storageKey": { "type": "string" }, "value": {} }, "required": [ "skillSlug", "storageKey", "value" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "storageKey", "value" ], "properties": { "storageKey": { "type": "string", "description": "Setup key returned by a required action for this skill." }, "value": { "description": "Value requested by the required action.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": true } ] } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/tasks/execute": { "post": { "operationId": "tasksPostExecute", "summary": "Execute a Computer Task and wait for its result", "description": "Creates one ordinary, immediate Computer Task for the account in the path. The selected account must be a provisioned Computer Agent accessible to the authenticated requester, including any member account restrictions. Do not send type or accountId in the body. Communication Tasks, schedules, and registered helper execution are not supported by this operation.\nAfter creation, waits up to waitSeconds (0-60, default 60) for completion and replication of the assistant reply into Vida room messages. A five-second grace period after the stored Task update allows replication to settle. Returns the latest assistant text in the Task execution window; tool, reasoning, system, and user entries are not returned as answers. Replicated messages do not contain a definitive final-answer marker, so readiness uses Task completion and that grace period. No direct computer-session lookup, result cache, or additional persistent execution state is used.\nHTTP 200 means a reply is ready or the Task errored/was canceled; inspect state, resultStatus, and error. HTTP 202 means execution or reply replication is still pending. Save taskId and check resultRef.href rather than creating another Task. A finished Task can still have pending output. waitSeconds=0 performs one inspection with a maximum 10-second read budget, without polling. Normal request setup and Task creation time are additional to the result-wait budget. A timeout or client disconnect never cancels the Task. Use the existing Task API to inspect or cancel it.\nThis POST is not idempotent. Retrying it can create another Task, even with the same externalTaskId. Reconcile existing Tasks before retrying an uncertain create. Missing or expired replicated messages remain pending; this endpoint does not fabricate an answer or recover deleted history.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "Selected Computer Agent account.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Reply ready, or Task errored or canceled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "allOf": [ { "$ref": "#/components/schemas/ComputerTaskResult" } ] } } } }, "202": { "description": "Task accepted; execution or reply replication remains pending", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "allOf": [ { "$ref": "#/components/schemas/ComputerTaskResult" } ] } } } }, "400": { "description": "Invalid Computer Task input, unsupported body field, or waitSeconds outside 0-60" }, "401": { "description": "Authentication required or target account inaccessible" }, "403": { "description": "Selected account is outside the requester permissions" }, "404": { "description": "Selected account not found" }, "409": { "description": "Selected Computer Agent is not provisioned or unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerTaskExecute" }, "example": { "taskContext": "Open example.com and report the page title.", "waitSeconds": 60 } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/tasks/{taskId}/result": { "get": { "operationId": "tasksGetRecordResult", "summary": "Read or wait for a Computer Task result", "description": "Reads an existing Computer Task belonging to the account in the path. Never creates, reruns, or cancels work. Uses the same requester and account permissions as Computer Task execution; Tasks belonging to another account and non-computer Tasks return 404.\nwaitSeconds is an integer from 0 to 60, default 0. Zero performs one inspection, bounded to 10 seconds for result reads, without polling. Positive values wait up to that many seconds after the initial Task lookup. Execution completion plus a five-second replication grace period gates selection of the latest replicated assistant text in the execution window. Messages do not have a definitive final-answer marker. Tool, reasoning, system, and user entries are not answers. No direct computer-session reads or new persisted state are used.\nHTTP 200 means output is ready or the Task errored/was canceled; inspect state, resultStatus, and error. HTTP 202 means execution or replicated output is pending, even if state is finished. Missing/expired replicated output remains pending. Read the linked chat with the existing Tasks API chatRef when investigating. A client disconnect only ends this wait, not the Task.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "Selected Computer Agent account.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "taskId", "in": "path", "required": true, "description": "Existing Computer Task ID.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "waitSeconds", "in": "query", "required": false, "description": "Maximum additional wait after the initial Task lookup.", "schema": { "type": "integer", "minimum": 0, "maximum": 60, "default": 0 } } ], "responses": { "200": { "description": "Reply ready, or Task errored or canceled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "allOf": [ { "$ref": "#/components/schemas/ComputerTaskResult" } ] } } } }, "202": { "description": "Execution or reply replication remains pending", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "allOf": [ { "$ref": "#/components/schemas/ComputerTaskResult" } ] } } } }, "400": { "description": "Invalid waitSeconds or route parameters" }, "401": { "description": "Authentication required or target account inaccessible" }, "403": { "description": "Selected account is outside the requester permissions" }, "404": { "description": "Computer Task not found in the selected account" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/tools/catalog": { "get": { "operationId": "toolsGetToolsCatalog", "summary": "List Computer Agent tools and policy", "description": "Lists tools available to the selected Computer Agent and whether each tool is currently allowed.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/tools/policy": { "post": { "operationId": "toolsPostToolsPolicy", "summary": "Change one Computer Agent tool policy", "description": "Allows or blocks one supported tool for the selected Computer Agent.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "description": "" }, "blocked": { "description": "" } }, "required": [ "tool", "blocked" ] } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/tools/invoke": { "post": { "operationId": "toolsPostToolsInvoke", "summary": "Run an allowed Computer Agent tool", "description": "Runs one tool returned by the Computer Agent tool catalog and returns its result. Prefer a purpose-built endpoint when one is available.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tool" ], "properties": { "tool": { "type": "string", "description": "Tool name returned by the tool catalog." }, "args": { "type": "object", "additionalProperties": true, "description": "Arguments accepted by the selected tool." }, "action": { "type": "string", "description": "Optional action supported by the selected tool." }, "dryRun": { "type": "boolean", "description": "Ask the tool to validate or preview the operation without applying it." }, "sessionKey": { "type": "string", "description": "Optional known session to continue for this Computer Agent." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/workflow-recordings/status": { "get": { "operationId": "workflowRecordingsGetStatus", "summary": "Get browser workflow status", "description": "Shows recording and browser-helper generation status. Active generation includes a conversation reference that explains how to open its live Vida chat.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current recording and generation status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "recording": { "type": "object", "nullable": true, "additionalProperties": true, "properties": { "state": { "type": "string", "description": "Current recorder lifecycle state." }, "active": { "type": "boolean" }, "recordingId": { "type": "string", "nullable": true, "description": "Stable identifier allocated when recording starts." }, "slotId": { "type": "integer", "nullable": true }, "finalized": { "type": "boolean", "description": "True only after recording analysis and artifact finalization succeed." }, "analysisStatus": { "type": "string", "nullable": true }, "fileSizeBytes": { "type": "integer", "nullable": true }, "artifacts": { "type": "array", "items": { "type": "string" } }, "updatedAt": { "type": "string", "format": "date-time" }, "evidenceRoot": { "type": "string", "description": "Workspace-relative directory containing the selected recording evidence." } } }, "generation": { "type": "object", "nullable": true, "additionalProperties": true, "properties": { "state": { "type": "string" }, "phase": { "type": "string", "description": "Current generation phase, such as starting, running, reviewing, recovering, completed, or failed." }, "generationId": { "type": "string" }, "recordingIds": { "type": "array", "description": "Immutable recording snapshot selected when this generation started.", "items": { "type": "string" } }, "updatedAt": { "type": "string", "format": "date-time" }, "lastActivityAt": { "type": "string", "format": "date-time", "description": "Last worker heartbeat, output, or phase transition." }, "evidenceRoot": { "type": "string", "description": "Workspace-relative directory containing the selected recording evidence." }, "sessionKey": { "type": "string" }, "conversationRef": { "type": "object", "properties": { "sessionKey": { "type": "string" }, "resolve": { "type": "object", "additionalProperties": true } } } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/workflow-recordings/start": { "post": { "operationId": "workflowRecordingsPostStart", "summary": "Start recording a browser workflow", "description": "Starts a browser workflow recording for the selected Computer Agent. When using a browser automation session, pass the exact slot returned by that session.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recording started", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "state": { "type": "string" }, "recordingId": { "type": "string", "description": "Stable identifier for this recording." }, "slotId": { "type": "integer" }, "finalized": { "type": "boolean", "enum": [ false ] }, "updatedAt": { "type": "string", "format": "date-time" }, "evidenceRoot": { "type": "string", "description": "Workspace-relative directory where recording evidence will be stored." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "slotId" ], "properties": { "slotId": { "type": "integer", "minimum": 0, "description": "Browser slot returned by the browser automation session." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/workflow-recordings/stop": { "post": { "operationId": "workflowRecordingsPostStop", "summary": "Stop recording a browser workflow", "description": "Stops and finalizes the active browser workflow recording for the selected Computer Agent.", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recording stopped and finalized", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "state": { "type": "string" }, "domainKey": { "type": "string" }, "recordingId": { "type": "string" }, "finalized": { "type": "boolean", "description": "True only when final analysis and artifacts are ready for generation." }, "analysisStatus": { "type": "string" }, "fileSizeBytes": { "type": "integer" }, "artifacts": { "type": "array", "items": { "type": "string" } }, "updatedAt": { "type": "string", "format": "date-time" }, "evidenceRoot": { "type": "string", "description": "Workspace-relative directory containing the finalized recording evidence." } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/workflow-recordings/{domainKey}/{recordingId}/commentary": { "post": { "operationId": "workflowRecordingsPostRecordCommentary", "summary": "Add guidance to a browser workflow recording", "description": "Adds written guidance and structured notes to a finalized browser workflow recording.", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "domainKey", "in": "path", "required": true, "description": "", "schema": {} }, { "name": "recordingId", "in": "path", "required": true, "description": "", "schema": {} } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text", "notes" ], "properties": { "text": { "type": "string", "description": "Overall workflow intent, constraints, and expected outcome." }, "notes": { "type": "array", "description": "Guidance tied to exact moments in the recording timeline.", "items": { "type": "object", "required": [ "t", "text" ], "properties": { "id": { "type": "string", "description": "Existing note identifier when updating a note." }, "t": { "type": "integer", "minimum": 0, "description": "Milliseconds from the beginning of the recording." }, "text": { "type": "string", "description": "Guidance for what happens at this moment." } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/workflow-recordings/{domainKey}/{recordingId}/delete": { "post": { "operationId": "workflowRecordingsPostRecordDelete", "summary": "Delete a browser workflow recording", "description": "Deletes the selected finalized browser workflow recording.", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "domainKey", "in": "path", "required": true, "description": "", "schema": {} }, { "name": "recordingId", "in": "path", "required": true, "description": "", "schema": {} } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/workflow-recordings/{domainKey}/generate": { "post": { "operationId": "workflowRecordingsPostDomainGenerate", "summary": "Generate a reusable browser helper", "description": "Starts browser-helper generation from the finalized recordings for the selected domain. The response includes the resulting skill identifier and a conversation reference for following the Computer Agent's work and tool calls. Supply a neutral skill name when the domain contains customer-specific information or would make a poor reusable name.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "domainKey", "in": "path", "required": true, "description": "", "schema": {} } ], "responses": { "200": { "description": "Browser-helper generation started", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "state": { "type": "string" }, "phase": { "type": "string" }, "generationId": { "type": "string" }, "recordingIds": { "type": "array", "description": "Immutable recording snapshot used by this generation.", "items": { "type": "string" } }, "updatedAt": { "type": "string", "format": "date-time" }, "lastActivityAt": { "type": "string", "format": "date-time" }, "sessionKey": { "type": "string" }, "skillSlug": { "type": "string" }, "evidenceRoot": { "type": "string", "description": "Workspace-relative directory containing the selected recording evidence." }, "conversationRef": { "type": "object", "required": [ "sessionKey", "resolve" ], "properties": { "sessionKey": { "type": "string" }, "resolve": { "type": "object", "required": [ "method", "href", "body" ], "properties": { "method": { "type": "string", "enum": [ "POST" ] }, "href": { "type": "string" }, "body": { "type": "object", "required": [ "sessionKey" ], "properties": { "sessionKey": { "type": "string" } } } } } } } } } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "skillName": { "type": "string", "maxLength": 128, "description": "Optional reusable name. Vida converts it to the returned safe skillSlug." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/workflow-recordings/{domainKey}/reset": { "post": { "operationId": "workflowRecordingsPostDomainReset", "summary": "Reset a generated browser helper", "description": "Removes the generated browser helper for the selected domain while preserving its recordings.", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "domainKey", "in": "path", "required": true, "description": "", "schema": {} } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/workspace/read": { "post": { "operationId": "workspacePostWorkspaceRead", "summary": "Read a Computer Agent workspace file", "description": "Returns the text content of one customer-created, workspace-relative file. Canvas source is available under app even though that directory is omitted from root listings. Use the agent configuration workflow for agent instructions and settings.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string", "description": "Workspace-relative text file to read." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/workspace/write": { "post": { "operationId": "workspacePostWorkspaceWrite", "summary": "Write a Computer Agent workspace file", "description": "Writes complete text content to one customer-created, workspace-relative file. This replaces an existing file or creates a new file and any missing parent folders. Canvas source is editable under app and must be published separately. Use the agent configuration workflow for agent instructions and settings.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "path", "content" ], "properties": { "path": { "type": "string", "description": "Workspace-relative text file to create or replace." }, "content": { "type": "string", "description": "Complete new file content." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/workspace/upload": { "post": { "operationId": "workspacePostWorkspaceUpload", "summary": "Upload a Computer Agent workspace file", "description": "Uploads one customer-created file to the selected Computer Agent workspace. Set overwrite to true to replace an existing file. Agent instructions, settings, and protected system files cannot be uploaded through this endpoint.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "path", "file" ], "properties": { "path": { "type": "string", "description": "Workspace-relative destination path." }, "file": { "type": "string", "format": "binary", "description": "File to upload. Zero-byte files are supported." }, "overwrite": { "type": "boolean", "default": false, "description": "Replace an existing file at the destination path." }, "mode": { "type": "string", "pattern": "^[0-7]{3,4}$", "example": "0600", "description": "Optional Unix file permissions." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/workspace/list": { "post": { "operationId": "workspacePostWorkspaceList", "summary": "List a Computer Agent workspace directory", "description": "Lists customer-created files and folders at an optional workspace-relative directory. Omit path to list the ordinary workspace root. Canvas source is intentionally omitted there but can be listed directly with path app. Agent instructions and settings do not appear in customer results; update them through the agent configuration workflow.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspace directory listing", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "result": { "type": "object", "required": [ "entries" ], "properties": { "path": { "type": "string" }, "entries": { "type": "array", "items": { "type": "object", "required": [ "path", "name" ], "properties": { "path": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "isDir": { "type": "boolean" }, "size": { "type": "integer", "nullable": true } } } }, "truncated": { "type": "boolean" }, "limit": { "type": "integer" } } } }, "required": [ "result" ] } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string", "description": "Workspace-relative directory. Omit to list the root." }, "limit": { "type": "integer", "minimum": 1, "maximum": 2000, "description": "Maximum number of entries to return." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/workspace/delete": { "delete": { "operationId": "workspaceDeleteWorkspacePath", "summary": "Delete a Computer Agent workspace path", "description": "Deletes one customer-created file or empty directory from the selected Computer Agent workspace. Agent instructions, settings, and protected system files cannot be deleted here.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "path", "in": "query", "required": true, "description": "Workspace-relative file or empty directory to delete.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/workspace/download": { "get": { "operationId": "workspaceGetWorkspaceDownload", "summary": "Download a Computer Agent workspace file", "description": "Downloads one customer-created file from the selected Computer Agent workspace.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "path", "in": "query", "required": true, "description": "", "schema": {} } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/workspace/preview": { "get": { "operationId": "workspaceGetWorkspacePreview", "summary": "Preview a Computer Agent workspace file", "description": "Previews one supported customer-created file from the selected Computer Agent workspace.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "path", "in": "query", "required": true, "description": "", "schema": {} } ], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/workspace/edit": { "post": { "operationId": "workspacePostWorkspaceEdit", "summary": "Replace text in a Computer Agent workspace file", "description": "Replaces the first exact occurrence of text in a customer-created, workspace-relative file. Read the file first and verify it again after editing. Use the agent configuration workflow for agent instructions and settings.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "path", "oldText", "newText" ], "properties": { "path": { "type": "string", "description": "Workspace-relative file path." }, "oldText": { "type": "string", "minLength": 1, "description": "Exact text that must currently exist in the file." }, "newText": { "type": "string", "description": "Replacement text. Use an empty string to remove the matched text." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/workspace/find": { "post": { "operationId": "workspacePostWorkspaceFind", "summary": "Find workspace paths", "description": "Finds customer-created, workspace-relative file and folder names containing a pattern. Search the whole visible workspace by omitting path, or limit the search to one directory. Agent instructions and settings are not included.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pattern" ], "properties": { "path": { "type": "string", "description": "Optional workspace-relative file or directory to search." }, "pattern": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Text to match in file and folder names." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum number of matches to return." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts/{targetAccountId}/workspace/search": { "post": { "operationId": "workspacePostWorkspaceSearch", "summary": "Search text in a Computer Agent workspace", "description": "Finds plain text within a customer-created, workspace-relative file or directory. Results can be limited by file pattern, capitalization, surrounding lines, and maximum count. Agent instructions and settings are not searchable here.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string", "maxLength": 4096, "description": "Workspace-relative file or directory to search." }, "pattern": { "type": "string", "maxLength": 500, "description": "Plain text to find." }, "glob": { "type": "string", "maxLength": 500, "description": "Optional file pattern, such as *.js." }, "ignoreCase": { "type": "boolean", "description": "Set to true to ignore capitalization differences." }, "context": { "type": "integer", "minimum": 0, "maximum": 5, "description": "Number of surrounding lines to include." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum number of matches to return." } }, "required": [ "path", "pattern" ] } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/accounts": { "get": { "operationId": "computerAccountsGetAccounts", "summary": "List Computer Agent accounts", "description": "Lists the Computer Agent accounts available to the requester, including whether their shared Computer is configured and which account is the default.\n", "parameters": [], "responses": { "200": { "description": "Available Computer Agent accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "configured": { "type": "boolean" }, "count": { "type": "integer" }, "accounts": { "type": "array", "items": { "type": "object" } }, "defaultAccountId": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true } }, "required": [ "configured", "count", "accounts" ] } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agents" ] } }, "/api/v2/computer/sessions": { "get": { "operationId": "sessionsGetIndex", "summary": "List Computer Agent sessions", "description": "Lists Computer Agent sessions visible to the authenticated user with pagination and optional filters.\n", "parameters": [], "responses": { "200": { "description": "Successful response" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agent Sessions" ] } }, "/api/v2/computer/sessions/reset": { "post": { "operationId": "sessionsPostReset", "summary": "Reset a Computer Agent session", "description": "Resets one authorized Computer Agent session. This discards its active conversational context.\n", "parameters": [], "responses": { "200": { "description": "Successful response" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sessionKey" ], "properties": { "sessionKey": { "type": "string", "description": "Session key returned by the Computer Agent sessions list." }, "reason": { "type": "string", "description": "Optional reason for resetting the session." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agent Sessions" ] } }, "/api/v2/computer/accounts/{targetAccountId}/session/resolve": { "post": { "operationId": "sessionsPostResolveManagedSessionRoom", "summary": "Find a Computer Agent session chat", "description": "Returns the Vida chat associated with an authorized session for the selected Computer Agent, including a direct messages reference when the chat is available. Omit sessionKey to resolve the default direct session for the requester and selected agent.\n", "parameters": [ { "name": "targetAccountId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session chat resolution", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "configured": { "type": "boolean" }, "sessionKey": { "type": "string" }, "roomId": { "type": "string", "nullable": true }, "chatRef": { "type": "object", "nullable": true, "required": [ "roomId", "targetAccountId", "href" ], "properties": { "roomId": { "type": "string" }, "targetAccountId": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Selected Agent account used to authorize the messages request." }, "href": { "type": "string", "description": "Relative API URL for reading the chat messages." } } }, "targetAgentId": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "requesterAccountId": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "sessionType": { "type": "string" }, "sessionContextLabel": { "type": "string" } }, "required": [ "configured", "sessionKey", "roomId" ] } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionKey": { "type": "string", "description": "Optional session key belonging to the selected Computer Agent." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Computer Agent Sessions" ] } }, "/api/v2/reseller/settings": { "get": { "operationId": "settingsGetIndex", "summary": "Get reseller settings", "description": "Returns the selected reseller's identity, status, product-plan, and external-system identifiers. This operation requires an authorized partner account.\n", "parameters": [], "responses": { "200": { "description": "Reseller settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "resellerStatus": { "type": "string", "nullable": true }, "resellerEnabledAt": { "type": "integer", "nullable": true }, "offeredProductPlanId": { "type": "string", "nullable": true }, "active": { "type": "boolean", "nullable": true }, "productPlanId": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "resellerName": { "type": "string", "nullable": true }, "vidaPremium": { "type": "boolean" }, "externalAccountId": { "type": "string", "nullable": true }, "externalBillingId": { "type": "string", "nullable": true } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Accounts" ] }, "post": { "operationId": "settingsPostIndex", "summary": "Update reseller settings", "description": "Updates selected reseller settings from an authorized partner account. Read the current settings first, send only intended changes, and verify updatedSettings and failedSettings in the response.\n", "parameters": [], "responses": { "200": { "description": "Reseller settings update result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "updatedSettings": { "type": "array", "items": { "type": "string" } }, "failedSettings": { "type": "array", "items": { "type": "string" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "resellerStatus": { "type": "string", "enum": [ "enabled", "disabled" ] }, "productPlanId": { "type": "string" }, "offeredProductPlanId": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "email": { "type": "string", "format": "email" }, "resellerName": { "type": "string" }, "vidaPremium": { "type": "boolean" }, "externalAccountId": { "type": "string", "nullable": true }, "externalBillingId": { "type": "string", "nullable": true } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Accounts" ] } }, "/api/v2/prefillTemplateFromWeb": { "post": { "operationId": "legacyPostPrefillFromWeb", "summary": "Suggest template fields from a website", "description": "Reads a public website and suggests values for an existing Agent template draft. Review every suggestion before saving or applying the template.\n", "parameters": [], "responses": { "200": { "description": "Suggested template values", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "allOf": [ { "type": "object", "additionalProperties": true } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "templateId": { "description": "" }, "targetUrl": { "description": "" } }, "required": [ "templateId", "targetUrl" ] } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Agent Templates" ] } }, "/api/v2/createAgentFromTemplate": { "post": { "operationId": "legacyPostAgents", "summary": "Create an Agent from a template", "description": "Applies a reseller template to the selected Agent account, creates staging and live Agent configurations, and publishes the result. Supply values for the template's declared fields and verify the returned live configuration before using it.\n", "parameters": [], "responses": { "201": { "description": "Agent created and published from the template", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "stagingAgent": { "type": "object", "additionalProperties": true }, "defaultAgent": { "type": "object", "additionalProperties": true } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "templateId" ], "properties": { "templateId": { "type": "string", "description": "Template to apply." }, "templateFields": { "type": "array", "description": "Values for the template's declared onboarding fields.", "items": { "type": "object", "additionalProperties": true } }, "timezone": { "type": "string", "description": "IANA timezone for the new Agent." }, "agentVoice": { "type": "string", "description": "Voice identifier selected from the Agent voice catalog." } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Agent Templates" ] } }, "/api/v2/detachAgentFromTemplate": { "post": { "operationId": "legacyPostDetachAgents", "summary": "Detach an Agent from its template", "description": "Removes template ownership and editable-field restrictions from the selected Agent, then publishes the detached configuration. The Agent keeps its current authored configuration.\n", "parameters": [], "responses": { "200": { "description": "Agent detached from its template", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "campaign": { "type": "object", "additionalProperties": true } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Agent Templates" ] } }, "/api/v2/templates/{templateId}/migrate": { "post": { "operationId": "migrationsPostMigrate", "summary": "Migrate Agents to a template revision", "description": "Starts a migration for Agents created from this template. A dry run is used by default. Review its result before setting dryRun to false. Use sectionsToMigrate to limit the change and avoid forcing over customer overrides unless that replacement is explicitly intended.\n", "parameters": [ { "name": "templateId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inline migration result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "allOf": [ { "type": "object", "additionalProperties": true } ] } } } }, "202": { "description": "Migration queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "taskId": { "type": "string" }, "status": { "type": "string" }, "statusEndpoint": { "type": "string" }, "message": { "type": "string" } } } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "dryRun": { "type": "boolean", "default": true }, "sectionsToMigrate": { "type": "array", "items": { "type": "string" } }, "forceMigrateOverriddenFields": { "type": "boolean", "default": false } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Agent Templates" ] } }, "/api/v2/templates/{templateId}/migrations": { "get": { "operationId": "migrationsGetMigrations", "summary": "List template migrations", "description": "Lists recent migrations for an Agent template owned by the selected reseller. The optional limit query value controls how many recent migrations are returned.\n", "parameters": [ { "name": "templateId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Template migrations", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "templateId": { "type": "string" }, "migrations": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Agent Templates" ] } }, "/api/v2/templates/{templateId}/migrations/{taskId}": { "get": { "operationId": "migrationsGetMigration", "summary": "Get a template migration", "description": "Returns the current status and result for one template migration. Poll this operation until the migration reaches a terminal state before reporting completion.\n", "parameters": [ { "name": "templateId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "taskId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Template migration", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "migration": { "type": "object", "additionalProperties": true } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Agent Templates" ] } }, "/api/v2/templates": { "get": { "operationId": "templatesGetIndex", "summary": "List Agent templates", "description": "Lists reusable Agent templates available to the selected account. By default, disabled templates are excluded. Use includeHidden only when the caller is allowed to manage hidden templates.\n", "parameters": [], "responses": { "200": { "description": "Available Agent templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "templates": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Agent Templates" ] } }, "/api/v2/templates/createTemplate": { "post": { "operationId": "templatesPostCreateTemplate", "summary": "Create an Agent template draft", "description": "Creates a disabled template draft for the selected reseller. Read the returned template, update its Agent configuration and onboarding fields, then enable it only after testing it.\n", "parameters": [], "responses": { "201": { "description": "Agent template draft created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "template": { "type": "object", "additionalProperties": true } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Agent Templates" ] } }, "/api/v2/templates/{templateId}": { "get": { "operationId": "templatesGetShow", "summary": "Get an Agent template", "description": "Returns one Agent template owned by the selected reseller. Use this response as the starting point for updates so fields outside the intended change are preserved.\n", "parameters": [ { "name": "templateId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent template", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "template": { "type": "object", "additionalProperties": true } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Agent Templates" ] }, "post": { "operationId": "templatesPostUpdate", "summary": "Update an Agent template", "description": "Updates the supplied fields on an Agent template owned by the selected reseller. Read the current template first and preserve fields that are not part of the requested change.\n", "parameters": [ { "name": "templateId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated Agent template", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "template": { "type": "object", "additionalProperties": true } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "additionalProperties": true } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Agent Templates" ] }, "delete": { "operationId": "templatesDeleteDestroy", "summary": "Delete an Agent template", "description": "Deletes a disabled Agent template owned by the selected reseller. Disable the template and confirm it is no longer needed before deleting it.\n", "parameters": [ { "name": "templateId", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent template deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ "Agent Templates" ] } } }, "components": { "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "query", "name": "token", "description": "Vida API Token" } }, "schemas": { "AgentActionWrite": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Function identifier returned by GET /api/v2/agent/functions." }, "instructions": { "type": "string", "description": "When and how the agent should use this function." } } }, "AgentActionRead": { "allOf": [ { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Function identifier returned by GET /api/v2/agent/functions." }, "instructions": { "type": "string", "description": "When and how the agent should use this function." } } }, { "type": "object", "properties": { "placeholder": { "type": "string", "readOnly": true, "description": "Configuration guidance for this function." }, "allowed": { "type": "boolean", "readOnly": true, "description": "Whether the selected account can currently use the function." }, "reason": { "type": "string", "nullable": true, "readOnly": true, "description": "Why the function is unavailable." }, "missingRequirement": { "type": "string", "nullable": true, "readOnly": true, "description": "Account setup required before the function can be used." } } } ] }, "AgentAppAssignment": { "type": "object", "required": [ "appId", "version", "instructions" ], "properties": { "appId": { "type": "string", "description": "App identifier returned by GET /api/v2/apps." }, "version": { "type": "string", "description": "Installed app version." }, "instructions": { "type": "string", "description": "When and how the agent should use the app." }, "enabled": { "type": "boolean", "default": true, "description": "Whether this app assignment is enabled for the agent." } } }, "AgentSkillAssignment": { "type": "object", "required": [ "slug", "instructions" ], "properties": { "slug": { "type": "string", "description": "Computer Agent skill identifier." }, "instructions": { "type": "string", "description": "Agent-specific instructions for using the skill." } } }, "AgentAppManifest": { "type": "object", "description": "Agent app metadata and account-specific setup state.", "properties": { "appId": { "type": "string", "description": "Stable app identifier." }, "version": { "type": "string", "description": "App version." }, "title": { "type": "string", "description": "Display name." }, "description": { "type": "string", "description": "What the app enables." }, "installed": { "type": "boolean", "readOnly": true, "description": "Whether this app is installed for the selected account." }, "active": { "type": "boolean", "readOnly": true, "description": "Whether required setup is complete and the app can be used." }, "dependencies": { "type": "object", "additionalProperties": true, "description": "Authentication and configuration requirements. Required properties include their current account-specific values when available." } }, "additionalProperties": true }, "AgentVoice": { "type": "object", "properties": { "id": { "type": "string", "description": "Exact identifier to store in agentVoice." }, "name": { "type": "string", "description": "Display name." }, "description": { "type": "string", "nullable": true }, "sampleUrl": { "type": "string", "format": "uri", "nullable": true }, "imageUrl": { "type": "string", "format": "uri", "nullable": true }, "provider": { "type": "string" }, "languages": { "type": "array", "items": { "type": "string" }, "description": "Vida language modes supported by this voice." }, "compatibleS2SEngines": { "type": "array", "items": { "type": "string", "enum": [ "openai", "openai-live", "gemini" ] } }, "supportsStandardTts": { "type": "boolean" }, "accountAvailability": { "type": "object", "properties": { "available": { "type": "boolean" }, "reason": { "type": "string", "nullable": true, "enum": [ "advanced_voice_required", null ] } } } } }, "AgentExperimentVariant": { "type": "object", "required": [ "versionId", "weight" ], "properties": { "label": { "type": "string", "description": "Display label for the variant." }, "versionId": { "type": "integer", "description": "Saved version used by this variant." }, "weight": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Relative traffic weight." } } }, "AgentExperiment": { "type": "object", "properties": { "id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "readOnly": true }, "agentConfigId": { "type": "string", "description": "Live agent configuration ID whose versions are tested." }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "variants": { "type": "array", "minItems": 2, "items": { "type": "object", "required": [ "versionId", "weight" ], "properties": { "label": { "type": "string", "description": "Display label for the variant." }, "versionId": { "type": "integer", "description": "Saved version used by this variant." }, "weight": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Relative traffic weight." } } } }, "createdAt": { "type": "integer", "format": "int64", "nullable": true, "readOnly": true }, "createdBy": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "readOnly": true } } }, "AgentReportingField": { "type": "object", "required": [ "key", "label", "instructions", "values" ], "properties": { "key": { "type": "string", "description": "Stable field key used in conversation results." }, "label": { "type": "string", "description": "Human-readable field name." }, "instructions": { "type": "string", "description": "How the agent should determine the field value." }, "values": { "type": "object", "required": [ "kind" ], "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "boolean", "choices", "number", "text" ], "description": "Value type the agent must return for this field." }, "choices": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "description": "Allowed values when kind is choices; omit for other kinds." } } } } }, "AgentConfigurationWrite": { "type": "object", "description": "Writable staging configuration. Omitted fields retain their current values.", "properties": { "title": { "type": "string", "description": "Display name for the agent." }, "description": { "type": "string", "description": "Short description of the agent." }, "brandName": { "type": "string", "description": "Brand name the agent represents." }, "agentInstructions": { "type": "string", "description": "Primary instructions for voice, messaging, and Computer Agent work." }, "welcomeMessage": { "type": "string", "description": "Greeting used at the beginning of a conversation. Prefix with prompt: to generate the greeting from instructions." }, "links": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Web pages supplied as agent knowledge." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Searchable labels for the agent." }, "agentModel": { "type": "string", "description": "Model identifier returned by GET /api/v2/models/supported." }, "agentFastMode": { "type": "boolean", "description": "Use OpenAI Fast processing when the selected model supports it. Billing follows the service tier actually returned by OpenAI." }, "agentThinking": { "type": "string", "enum": [ "low" ], "nullable": true, "description": "Reasoning budget for supported models; null disables it." }, "agentThinkingModel": { "type": "string", "nullable": true, "description": "Model used by Pause & Think and optional post-conversation reasoning." }, "postConvoForceThinking": { "type": "boolean", "description": "Use the thinking model for post-conversation work when the primary model is not reasoning-enabled." }, "timezone": { "type": "string", "description": "IANA timezone used for scheduling and time-sensitive instructions.", "example": "America/Chicago" }, "agentVoice": { "type": "string", "description": "Exact voice ID returned by GET /api/v2/agent/voices." }, "agentTtsEngine": { "type": "string", "nullable": true, "description": "Text-to-speech engine used when speech-to-speech mode is disabled." }, "agentLang": { "type": "string", "enum": [ "en-US", "multi", "es-MX", "es-ES", "es-US" ], "description": "Primary spoken language. Use multi only with a compatible voice and speech mode." }, "agentS2SEngine": { "type": "string", "enum": [ "openai", "openai-live", "gemini" ], "nullable": true, "description": "Speech-to-speech engine; openai-live uses GPT-Live, and null uses separate speech recognition and synthesis." }, "agentSttEngine": { "type": "string", "enum": [ "google", "deepgram", "deepgramflux", "openai" ], "description": "Speech recognition engine used when speech-to-speech mode is disabled." }, "agentSttSmartFormatting": { "type": "boolean", "description": "Apply smart formatting when supported by the selected speech recognition engine." }, "actions": { "type": "array", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Function identifier returned by GET /api/v2/agent/functions." }, "instructions": { "type": "string", "description": "When and how the agent should use this function." } } }, "description": "Functions enabled for this agent." }, "reportingFields": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "instructions", "values" ], "properties": { "key": { "type": "string", "description": "Stable field key used in conversation results." }, "label": { "type": "string", "description": "Human-readable field name." }, "instructions": { "type": "string", "description": "How the agent should determine the field value." }, "values": { "type": "object", "required": [ "kind" ], "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "boolean", "choices", "number", "text" ], "description": "Value type the agent must return for this field." }, "choices": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "description": "Allowed values when kind is choices; omit for other kinds." } } } } }, "description": "Agent-level structured fields collected after a conversation." }, "apps": { "type": "array", "items": { "type": "object", "required": [ "appId", "version", "instructions" ], "properties": { "appId": { "type": "string", "description": "App identifier returned by GET /api/v2/apps." }, "version": { "type": "string", "description": "Installed app version." }, "instructions": { "type": "string", "description": "When and how the agent should use the app." }, "enabled": { "type": "boolean", "default": true, "description": "Whether this app assignment is enabled for the agent." } } }, "description": "Installed apps assigned to this agent." }, "skills": { "type": "array", "items": { "type": "object", "required": [ "slug", "instructions" ], "properties": { "slug": { "type": "string", "description": "Computer Agent skill identifier." }, "instructions": { "type": "string", "description": "Agent-specific instructions for using the skill." } } }, "description": "Computer Agent skills assigned at publish time." }, "computerDelegateAccountId": { "type": "integer", "nullable": true, "description": "Account ID of the Computer Agent that performs delegated Computer work." }, "heartbeatInstructions": { "type": "string", "description": "Work the Computer Agent should perform during scheduled check-ins." }, "heartbeatEvery": { "type": "string", "description": "Heartbeat interval such as 15m, 1h, or 1h30m." }, "heartbeatConfig": { "type": "object", "description": "Advanced Computer Agent heartbeat settings. This object replaces the previous advanced settings when supplied, so preserve fields you do not intend to remove.", "additionalProperties": false, "properties": { "activeHours": { "type": "object", "required": [ "start", "end" ], "additionalProperties": false, "description": "Daily window in which scheduled heartbeat work may start.", "properties": { "start": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "Window start in 24-hour HH:MM format.", "example": "08:00" }, "end": { "type": "string", "pattern": "^(?:([01]\\d|2[0-3]):[0-5]\\d|24:00)$", "description": "Window end in 24-hour HH:MM format; 24:00 is allowed.", "example": "18:00" }, "timezone": { "type": "string", "description": "IANA timezone, user, or local. Omit to use the Computer Agent default.", "example": "America/Chicago" } } }, "model": { "type": "string", "minLength": 1, "description": "Model label attached to heartbeat work. This does not replace the Agent configuration's agentModel." }, "session": { "type": "string", "minLength": 1, "description": "Session identifier used for heartbeat work." }, "target": { "type": "string", "minLength": 1, "description": "Delivery target type or channel selected for heartbeat results." }, "to": { "type": "string", "minLength": 1, "description": "Destination within the selected heartbeat target." }, "accountId": { "type": "string", "minLength": 1, "description": "Channel account identifier used for heartbeat delivery when a channel has multiple accounts." }, "directPolicy": { "type": "string", "enum": [ "allow", "block" ], "description": "Whether heartbeat results may be delivered to direct-message destinations." }, "includeReasoning": { "type": "boolean", "description": "Include model reasoning in heartbeat output when supported." }, "includeSystemPromptSection": { "type": "boolean", "description": "Include the Computer Agent system-prompt section in heartbeat context." }, "ackMaxChars": { "type": "integer", "description": "Maximum length treated as a simple heartbeat acknowledgement rather than a result that should be delivered.", "minimum": 0 }, "suppressToolErrorWarnings": { "type": "boolean", "description": "Suppress automatic raw tool-error notices while still allowing the agent to report an unrecovered problem intentionally." }, "timeoutSeconds": { "type": "integer", "description": "Maximum heartbeat execution time in seconds.", "minimum": 1 }, "lightContext": { "type": "boolean", "description": "Use a smaller context for heartbeat work." }, "isolatedSession": { "type": "boolean", "description": "Run heartbeat work in a separate session from the agent's main conversation." }, "skipWhenBusy": { "type": "boolean", "description": "Skip a scheduled heartbeat while the agent is already busy." } } }, "backgroundAudio": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "loop": { "type": "boolean", "default": true }, "gain": { "type": "integer", "default": 0 }, "startAfterGreeting": { "type": "boolean", "default": true }, "track": { "type": "string", "enum": [ "bg", "fx" ] } } } ], "description": "Optional HTTP(S) audio played during calls." }, "waitOnAnswer": { "type": "integer", "description": "Milliseconds to wait before speaking the greeting.", "minimum": 0 }, "waitToGreet": { "type": "boolean", "description": "Wait for the caller to speak before delivering the greeting." }, "postAnswerDtmf": { "type": "string", "description": "DTMF digits sent immediately after an outbound call is answered." }, "interruptionWordCount": { "type": "integer", "description": "Words required before caller speech interrupts the agent.", "minimum": 0 }, "interruptionMinimumSpeakingTime": { "type": "number", "description": "Seconds the agent must speak before interruption is allowed.", "minimum": 0 }, "speakingTimeout": { "type": "integer", "description": "Milliseconds of silence used to detect the end of caller speech.", "minimum": 0 }, "speechProcessingDelay": { "type": "integer", "description": "Milliseconds to wait before sending recognized speech to the model.", "minimum": 0 }, "speechProcessingDelayInterruptionStep": { "type": "integer", "description": "Milliseconds added to speech processing delay after an interruption.", "minimum": 0 }, "speechProcessingDelayMaxMultiplier": { "type": "integer", "description": "Maximum interruption multiplier applied to speech processing delay.", "minimum": 0 }, "callerResponseTimeout": { "type": "number", "description": "Seconds of caller silence before the agent checks in.", "minimum": 0 }, "callerResponseTimeoutHangupCounter": { "type": "integer", "description": "Unanswered check-ins before the agent ends the call.", "minimum": 0 }, "ignoreSpeech": { "type": "array", "items": { "type": "string" }, "description": "Caller phrases that should not be treated as a response." }, "noContactInjection": { "type": "boolean", "description": "Exclude the caller contact record from agent context." }, "noConvoHistory": { "type": "boolean", "description": "Exclude prior conversation summaries from agent context." }, "autoRecordingNotification": { "type": "string", "enum": [ "true", "false", "always" ], "description": "Recording notice policy: jurisdiction-based, never, or every call." }, "recordingNotificationPhrase": { "type": "string", "description": "Phrase spoken when a recording notice is required." }, "preAnswerRingTime": { "type": "integer", "description": "Seconds to ring before answering an inbound call.", "minimum": 0, "maximum": 60, "nullable": true }, "preAnswerSkipProcessingResults": { "type": "boolean", "description": "Place raw Pre Answer results directly into context without an additional model pass." }, "useAgentNumberForTransfers": { "type": "boolean", "description": "Use the agent phone number as caller ID for transfers." }, "confirmTransfers": { "type": "boolean", "description": "Require the recipient to confirm before completing a transfer." }, "monitorTransfers": { "type": "boolean", "description": "Continue monitoring the call after a transfer." }, "attendedTransfers": { "type": "boolean", "description": "Keep the agent with the caller while the recipient is reached." }, "attendedTransferBridgeTrigger": { "type": "string", "nullable": true, "description": "Recipient response required to bridge an attended transfer." }, "attendedTransferCheckInTimeout": { "type": "integer", "description": "Seconds before the agent checks in during an attended transfer.", "minimum": 0 }, "transferConfirmTimeout": { "type": "integer", "description": "Seconds to wait for transfer confirmation.", "minimum": 0 }, "announceTransferConnecting": { "type": "boolean", "description": "Announce that a transfer is being connected." }, "announceTransferConnected": { "type": "boolean", "description": "Announce when a transfer has connected." }, "preTransferNotificationStart": { "type": "string", "description": "Message spoken when Pre Transfer work begins." }, "preTransferNotificationEnd": { "type": "string", "description": "Message spoken when Pre Transfer work completes." }, "enableRingback": { "type": "boolean", "description": "Play ringback while the agent is connecting an outbound call." }, "enableTransferRingback": { "type": "boolean", "description": "Play ringback while a transfer is connecting." }, "cnamAutoRejectRegex": { "type": "string", "nullable": true, "description": "Pattern used to reject matching inbound caller names before answer." }, "cnamAutoRejectCode": { "type": "integer", "description": "SIP response code used when the reject pattern matches." }, "cnamAutoTransferRegex": { "type": "string", "nullable": true, "description": "Pattern used to transfer matching inbound caller names before answer." }, "cnamAutoTransferDestination": { "type": "string", "nullable": true, "description": "Phone number, extension, or PBX destination used by automatic transfer." } } }, "AgentConfigurationRead": { "allOf": [ { "type": "object", "description": "Writable staging configuration. Omitted fields retain their current values.", "properties": { "title": { "type": "string", "description": "Display name for the agent." }, "description": { "type": "string", "description": "Short description of the agent." }, "brandName": { "type": "string", "description": "Brand name the agent represents." }, "agentInstructions": { "type": "string", "description": "Primary instructions for voice, messaging, and Computer Agent work." }, "welcomeMessage": { "type": "string", "description": "Greeting used at the beginning of a conversation. Prefix with prompt: to generate the greeting from instructions." }, "links": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Web pages supplied as agent knowledge." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Searchable labels for the agent." }, "agentModel": { "type": "string", "description": "Model identifier returned by GET /api/v2/models/supported." }, "agentFastMode": { "type": "boolean", "description": "Use OpenAI Fast processing when the selected model supports it. Billing follows the service tier actually returned by OpenAI." }, "agentThinking": { "type": "string", "enum": [ "low" ], "nullable": true, "description": "Reasoning budget for supported models; null disables it." }, "agentThinkingModel": { "type": "string", "nullable": true, "description": "Model used by Pause & Think and optional post-conversation reasoning." }, "postConvoForceThinking": { "type": "boolean", "description": "Use the thinking model for post-conversation work when the primary model is not reasoning-enabled." }, "timezone": { "type": "string", "description": "IANA timezone used for scheduling and time-sensitive instructions.", "example": "America/Chicago" }, "agentVoice": { "type": "string", "description": "Exact voice ID returned by GET /api/v2/agent/voices." }, "agentTtsEngine": { "type": "string", "nullable": true, "description": "Text-to-speech engine used when speech-to-speech mode is disabled." }, "agentLang": { "type": "string", "enum": [ "en-US", "multi", "es-MX", "es-ES", "es-US" ], "description": "Primary spoken language. Use multi only with a compatible voice and speech mode." }, "agentS2SEngine": { "type": "string", "enum": [ "openai", "openai-live", "gemini" ], "nullable": true, "description": "Speech-to-speech engine; openai-live uses GPT-Live, and null uses separate speech recognition and synthesis." }, "agentSttEngine": { "type": "string", "enum": [ "google", "deepgram", "deepgramflux", "openai" ], "description": "Speech recognition engine used when speech-to-speech mode is disabled." }, "agentSttSmartFormatting": { "type": "boolean", "description": "Apply smart formatting when supported by the selected speech recognition engine." }, "actions": { "type": "array", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Function identifier returned by GET /api/v2/agent/functions." }, "instructions": { "type": "string", "description": "When and how the agent should use this function." } } }, "description": "Functions enabled for this agent." }, "reportingFields": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "instructions", "values" ], "properties": { "key": { "type": "string", "description": "Stable field key used in conversation results." }, "label": { "type": "string", "description": "Human-readable field name." }, "instructions": { "type": "string", "description": "How the agent should determine the field value." }, "values": { "type": "object", "required": [ "kind" ], "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "boolean", "choices", "number", "text" ], "description": "Value type the agent must return for this field." }, "choices": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "description": "Allowed values when kind is choices; omit for other kinds." } } } } }, "description": "Agent-level structured fields collected after a conversation." }, "apps": { "type": "array", "items": { "type": "object", "required": [ "appId", "version", "instructions" ], "properties": { "appId": { "type": "string", "description": "App identifier returned by GET /api/v2/apps." }, "version": { "type": "string", "description": "Installed app version." }, "instructions": { "type": "string", "description": "When and how the agent should use the app." }, "enabled": { "type": "boolean", "default": true, "description": "Whether this app assignment is enabled for the agent." } } }, "description": "Installed apps assigned to this agent." }, "skills": { "type": "array", "items": { "type": "object", "required": [ "slug", "instructions" ], "properties": { "slug": { "type": "string", "description": "Computer Agent skill identifier." }, "instructions": { "type": "string", "description": "Agent-specific instructions for using the skill." } } }, "description": "Computer Agent skills assigned at publish time." }, "computerDelegateAccountId": { "type": "integer", "nullable": true, "description": "Account ID of the Computer Agent that performs delegated Computer work." }, "heartbeatInstructions": { "type": "string", "description": "Work the Computer Agent should perform during scheduled check-ins." }, "heartbeatEvery": { "type": "string", "description": "Heartbeat interval such as 15m, 1h, or 1h30m." }, "heartbeatConfig": { "type": "object", "description": "Advanced Computer Agent heartbeat settings. This object replaces the previous advanced settings when supplied, so preserve fields you do not intend to remove.", "additionalProperties": false, "properties": { "activeHours": { "type": "object", "required": [ "start", "end" ], "additionalProperties": false, "description": "Daily window in which scheduled heartbeat work may start.", "properties": { "start": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "Window start in 24-hour HH:MM format.", "example": "08:00" }, "end": { "type": "string", "pattern": "^(?:([01]\\d|2[0-3]):[0-5]\\d|24:00)$", "description": "Window end in 24-hour HH:MM format; 24:00 is allowed.", "example": "18:00" }, "timezone": { "type": "string", "description": "IANA timezone, user, or local. Omit to use the Computer Agent default.", "example": "America/Chicago" } } }, "model": { "type": "string", "minLength": 1, "description": "Model label attached to heartbeat work. This does not replace the Agent configuration's agentModel." }, "session": { "type": "string", "minLength": 1, "description": "Session identifier used for heartbeat work." }, "target": { "type": "string", "minLength": 1, "description": "Delivery target type or channel selected for heartbeat results." }, "to": { "type": "string", "minLength": 1, "description": "Destination within the selected heartbeat target." }, "accountId": { "type": "string", "minLength": 1, "description": "Channel account identifier used for heartbeat delivery when a channel has multiple accounts." }, "directPolicy": { "type": "string", "enum": [ "allow", "block" ], "description": "Whether heartbeat results may be delivered to direct-message destinations." }, "includeReasoning": { "type": "boolean", "description": "Include model reasoning in heartbeat output when supported." }, "includeSystemPromptSection": { "type": "boolean", "description": "Include the Computer Agent system-prompt section in heartbeat context." }, "ackMaxChars": { "type": "integer", "description": "Maximum length treated as a simple heartbeat acknowledgement rather than a result that should be delivered.", "minimum": 0 }, "suppressToolErrorWarnings": { "type": "boolean", "description": "Suppress automatic raw tool-error notices while still allowing the agent to report an unrecovered problem intentionally." }, "timeoutSeconds": { "type": "integer", "description": "Maximum heartbeat execution time in seconds.", "minimum": 1 }, "lightContext": { "type": "boolean", "description": "Use a smaller context for heartbeat work." }, "isolatedSession": { "type": "boolean", "description": "Run heartbeat work in a separate session from the agent's main conversation." }, "skipWhenBusy": { "type": "boolean", "description": "Skip a scheduled heartbeat while the agent is already busy." } } }, "backgroundAudio": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "loop": { "type": "boolean", "default": true }, "gain": { "type": "integer", "default": 0 }, "startAfterGreeting": { "type": "boolean", "default": true }, "track": { "type": "string", "enum": [ "bg", "fx" ] } } } ], "description": "Optional HTTP(S) audio played during calls." }, "waitOnAnswer": { "type": "integer", "description": "Milliseconds to wait before speaking the greeting.", "minimum": 0 }, "waitToGreet": { "type": "boolean", "description": "Wait for the caller to speak before delivering the greeting." }, "postAnswerDtmf": { "type": "string", "description": "DTMF digits sent immediately after an outbound call is answered." }, "interruptionWordCount": { "type": "integer", "description": "Words required before caller speech interrupts the agent.", "minimum": 0 }, "interruptionMinimumSpeakingTime": { "type": "number", "description": "Seconds the agent must speak before interruption is allowed.", "minimum": 0 }, "speakingTimeout": { "type": "integer", "description": "Milliseconds of silence used to detect the end of caller speech.", "minimum": 0 }, "speechProcessingDelay": { "type": "integer", "description": "Milliseconds to wait before sending recognized speech to the model.", "minimum": 0 }, "speechProcessingDelayInterruptionStep": { "type": "integer", "description": "Milliseconds added to speech processing delay after an interruption.", "minimum": 0 }, "speechProcessingDelayMaxMultiplier": { "type": "integer", "description": "Maximum interruption multiplier applied to speech processing delay.", "minimum": 0 }, "callerResponseTimeout": { "type": "number", "description": "Seconds of caller silence before the agent checks in.", "minimum": 0 }, "callerResponseTimeoutHangupCounter": { "type": "integer", "description": "Unanswered check-ins before the agent ends the call.", "minimum": 0 }, "ignoreSpeech": { "type": "array", "items": { "type": "string" }, "description": "Caller phrases that should not be treated as a response." }, "noContactInjection": { "type": "boolean", "description": "Exclude the caller contact record from agent context." }, "noConvoHistory": { "type": "boolean", "description": "Exclude prior conversation summaries from agent context." }, "autoRecordingNotification": { "type": "string", "enum": [ "true", "false", "always" ], "description": "Recording notice policy: jurisdiction-based, never, or every call." }, "recordingNotificationPhrase": { "type": "string", "description": "Phrase spoken when a recording notice is required." }, "preAnswerRingTime": { "type": "integer", "description": "Seconds to ring before answering an inbound call.", "minimum": 0, "maximum": 60, "nullable": true }, "preAnswerSkipProcessingResults": { "type": "boolean", "description": "Place raw Pre Answer results directly into context without an additional model pass." }, "useAgentNumberForTransfers": { "type": "boolean", "description": "Use the agent phone number as caller ID for transfers." }, "confirmTransfers": { "type": "boolean", "description": "Require the recipient to confirm before completing a transfer." }, "monitorTransfers": { "type": "boolean", "description": "Continue monitoring the call after a transfer." }, "attendedTransfers": { "type": "boolean", "description": "Keep the agent with the caller while the recipient is reached." }, "attendedTransferBridgeTrigger": { "type": "string", "nullable": true, "description": "Recipient response required to bridge an attended transfer." }, "attendedTransferCheckInTimeout": { "type": "integer", "description": "Seconds before the agent checks in during an attended transfer.", "minimum": 0 }, "transferConfirmTimeout": { "type": "integer", "description": "Seconds to wait for transfer confirmation.", "minimum": 0 }, "announceTransferConnecting": { "type": "boolean", "description": "Announce that a transfer is being connected." }, "announceTransferConnected": { "type": "boolean", "description": "Announce when a transfer has connected." }, "preTransferNotificationStart": { "type": "string", "description": "Message spoken when Pre Transfer work begins." }, "preTransferNotificationEnd": { "type": "string", "description": "Message spoken when Pre Transfer work completes." }, "enableRingback": { "type": "boolean", "description": "Play ringback while the agent is connecting an outbound call." }, "enableTransferRingback": { "type": "boolean", "description": "Play ringback while a transfer is connecting." }, "cnamAutoRejectRegex": { "type": "string", "nullable": true, "description": "Pattern used to reject matching inbound caller names before answer." }, "cnamAutoRejectCode": { "type": "integer", "description": "SIP response code used when the reject pattern matches." }, "cnamAutoTransferRegex": { "type": "string", "nullable": true, "description": "Pattern used to transfer matching inbound caller names before answer." }, "cnamAutoTransferDestination": { "type": "string", "nullable": true, "description": "Phone number, extension, or PBX destination used by automatic transfer." } } }, { "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "description": "This configuration record's agentConfigId." }, "actions": { "type": "array", "items": { "allOf": [ { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Function identifier returned by GET /api/v2/agent/functions." }, "instructions": { "type": "string", "description": "When and how the agent should use this function." } } }, { "type": "object", "properties": { "placeholder": { "type": "string", "readOnly": true, "description": "Configuration guidance for this function." }, "allowed": { "type": "boolean", "readOnly": true, "description": "Whether the selected account can currently use the function." }, "reason": { "type": "string", "nullable": true, "readOnly": true, "description": "Why the function is unavailable." }, "missingRequirement": { "type": "string", "nullable": true, "readOnly": true, "description": "Account setup required before the function can be used." } } } ] } }, "activeEventRules": { "type": "array", "items": { "type": "string" }, "readOnly": true, "description": "Slots that currently reference this configuration." }, "effectiveReportingFields": { "type": "array", "items": { "allOf": [ { "type": "object", "required": [ "key", "label", "instructions", "values" ], "properties": { "key": { "type": "string", "description": "Stable field key used in conversation results." }, "label": { "type": "string", "description": "Human-readable field name." }, "instructions": { "type": "string", "description": "How the agent should determine the field value." }, "values": { "type": "object", "required": [ "kind" ], "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "boolean", "choices", "number", "text" ], "description": "Value type the agent must return for this field." }, "choices": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "description": "Allowed values when kind is choices; omit for other kinds." } } } } }, { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string", "enum": [ "reseller", "organization", "campaign" ], "readOnly": true } } } ] }, "readOnly": true, "description": "Final reporting fields after reseller, organization, and agent-level overrides." } } } ] }, "AgentConfigurationResponse": { "type": "object", "required": [ "success", "campaign" ], "properties": { "success": { "type": "boolean", "example": true }, "campaign": { "$ref": "#/components/schemas/AgentConfigurationRead" } } }, "ComputerTaskExecute": { "type": "object", "additionalProperties": false, "required": [ "taskContext" ], "properties": { "taskContext": { "type": "string", "description": "Instructions for the Agent performing this Task.", "example": "Confirm whether the customer wants a renewal quote.", "minLength": 1 }, "waitSeconds": { "type": "integer", "minimum": 0, "maximum": 60, "default": 60 }, "title": { "type": "string", "description": "Optional Task title." }, "externalTaskId": { "type": "string", "description": "Caller correlation ID, not an idempotency key." }, "meta": { "type": "object", "additionalProperties": true, "description": "Ordinary Task reporting metadata, not added to the Agent prompt." } } }, "ComputerTaskResult": { "type": "object", "required": [ "success", "taskId", "state", "resultStatus", "output", "error", "resultRef" ], "properties": { "success": { "type": "boolean", "description": "Whether the API request succeeded, not whether the Task succeeded." }, "taskId": { "type": "string", "description": "Existing Task ID." }, "state": { "type": "string", "enum": [ "pending", "processing", "running", "finished", "errored", "canceled" ] }, "resultStatus": { "type": "string", "enum": [ "pending", "ready", "unavailable" ], "description": "Response-only readiness. Finished Tasks remain pending while their reply has not replicated. Unavailable indicates an errored or canceled Task." }, "output": { "type": "object", "nullable": true, "required": [ "text", "truncated" ], "properties": { "text": { "type": "string", "maxLength": 20000, "description": "Latest replicated assistant reply in the completed Task execution window, after a five-second replication grace period." }, "truncated": { "type": "boolean", "description": "True when the returned text exceeded 20,000 characters." } } }, "error": { "type": "object", "nullable": true, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "task_failed", "task_canceled" ] }, "message": { "type": "string" } } }, "resultRef": { "type": "object", "required": [ "href" ], "properties": { "href": { "type": "string", "description": "Relative GET result URL. Authenticate with the normal token query parameter." } } } } }, "ContactFields": { "type": "object", "additionalProperties": false, "description": "Writable organization Contact fields. See [Contact fields](https://vida.io/docs/api-reference/platform-guides/contacts-and-objectives#contact-fields) for every field and nested property. PATCH recursively merges objects, replaces arrays/scalars and removes fields set to null. POST creates or shallowly updates top-level fields; use PATCH to preserve nested siblings.", "properties": { "name": { "type": "string", "nullable": true, "example": "Example Person" }, "title": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true, "example": "lead@example.com" }, "phone": { "type": "string", "nullable": true, "example": "+15551234567" }, "cnam": { "type": "string", "nullable": true, "description": "Organization Contact display data only; does not change outbound caller ID." }, "mobile": { "type": "string", "nullable": true }, "birthday": { "type": "string", "nullable": true }, "gender": { "type": "string", "nullable": true }, "image": { "type": "string", "nullable": true }, "address": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "street": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "zip": { "type": "string", "nullable": true, "example": "07101" }, "country": { "type": "string", "nullable": true } } }, "company": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "name": { "type": "string", "nullable": true }, "industry": { "type": "string", "nullable": true }, "position": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true } } }, "preferredContactMethod": { "type": "string", "nullable": true }, "marketingOptIn": { "type": "boolean", "nullable": true }, "contactSource": { "type": "string", "nullable": true }, "socialMedia": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "linkedin": { "type": "string", "nullable": true }, "twitter": { "type": "string", "nullable": true }, "facebook": { "type": "string", "nullable": true }, "instagram": { "type": "string", "nullable": true } } }, "leadSource": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "tags": { "type": "array", "nullable": true, "items": { "type": "string" } }, "notes": { "type": "string", "nullable": true }, "agentContext": { "type": "string", "nullable": true }, "customFields": { "type": "object", "nullable": true, "additionalProperties": true, "maxProperties": 20, "description": "Custom JSON data, at most 20 top-level keys and 8192 UTF-8 JSON bytes, including existing values after merge.", "example": { "vendorLeadCode": "lead-123", "source": "website" } }, "lastTask": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "taskId": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "listId": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "timestamp": { "type": "number", "nullable": true }, "success": { "type": "boolean", "nullable": true } } }, "lists": { "type": "array", "nullable": true, "items": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string" }, "timestamp": { "type": "number" } } } }, "appointments": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true } } } }, "ContactCreate": { "type": "object", "additionalProperties": false, "description": "Create or update an organization Contact. Supply id or target to resolve an existing person, or phone/email to create one. Fields are sent directly in the body, not inside meta.contact. Provided top-level values replace existing values; prefer PATCH for nested merges or deleting a field.", "properties": { "id": { "oneOf": [ { "type": "string" }, { "type": "integer" } ], "description": "Existing Contact identifier. Takes precedence over target." }, "target": { "type": "string", "description": "Existing person identifier, phone number or Vida username. If unresolved, provide phone or email to create a Contact." }, "name": { "type": "string", "nullable": true, "example": "Example Person" }, "title": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true, "example": "lead@example.com" }, "phone": { "type": "string", "nullable": true, "example": "+15551234567" }, "cnam": { "type": "string", "nullable": true, "description": "Organization Contact display data only; does not change outbound caller ID." }, "mobile": { "type": "string", "nullable": true }, "birthday": { "type": "string", "nullable": true }, "gender": { "type": "string", "nullable": true }, "image": { "type": "string", "nullable": true }, "address": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "street": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "zip": { "type": "string", "nullable": true, "example": "07101" }, "country": { "type": "string", "nullable": true } } }, "company": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "name": { "type": "string", "nullable": true }, "industry": { "type": "string", "nullable": true }, "position": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true } } }, "preferredContactMethod": { "type": "string", "nullable": true }, "marketingOptIn": { "type": "boolean", "nullable": true }, "contactSource": { "type": "string", "nullable": true }, "socialMedia": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "linkedin": { "type": "string", "nullable": true }, "twitter": { "type": "string", "nullable": true }, "facebook": { "type": "string", "nullable": true }, "instagram": { "type": "string", "nullable": true } } }, "leadSource": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "tags": { "type": "array", "nullable": true, "items": { "type": "string" } }, "notes": { "type": "string", "nullable": true }, "agentContext": { "type": "string", "nullable": true }, "customFields": { "type": "object", "nullable": true, "additionalProperties": true, "maxProperties": 20, "description": "Custom JSON data, at most 20 top-level keys and 8192 UTF-8 JSON bytes, including existing values after merge.", "example": { "vendorLeadCode": "lead-123", "source": "website" } }, "lastTask": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "taskId": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "listId": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "timestamp": { "type": "number", "nullable": true }, "success": { "type": "boolean", "nullable": true } } }, "lists": { "type": "array", "nullable": true, "items": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string" }, "timestamp": { "type": "number" } } } }, "appointments": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true } } }, "anyOf": [ { "required": [ "id" ] }, { "required": [ "target" ] }, { "required": [ "phone" ] }, { "required": [ "email" ] } ] }, "TaskContactFields": { "type": "object", "additionalProperties": false, "description": "Optional Contact fields for call, text and email Task creation, including outboundCall, outboundSms and outboundEmail. Fills missing fields on the target Contact in the Task organization before scheduling. Nested objects fill missing leaves; existing nonblank values, false, zero and nonempty arrays are preserved. Strings are trimmed; null, blank strings and empty objects/arrays are ignored. New Contacts use the supplied name instead of a global-profile default. Existing target phone/email defaults remain canonical. Does not change the Task target, global user profile or outbound caller ID. Task updates do not apply Contact changes; use the Contact API to replace or clear existing values. Identity and ownership fields are not accepted. See [Contact fields](https://vida.io/docs/api-reference/platform-guides/contacts-and-objectives#contact-fields) for the full field reference.", "properties": { "name": { "type": "string", "nullable": true, "example": "Example Person" }, "title": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true, "example": "lead@example.com" }, "phone": { "type": "string", "nullable": true, "example": "+15551234567" }, "cnam": { "type": "string", "nullable": true, "description": "Organization Contact display data only; does not change outbound caller ID." }, "mobile": { "type": "string", "nullable": true }, "birthday": { "type": "string", "nullable": true }, "gender": { "type": "string", "nullable": true }, "image": { "type": "string", "nullable": true }, "address": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "street": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "zip": { "type": "string", "nullable": true, "example": "07101" }, "country": { "type": "string", "nullable": true } } }, "company": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "name": { "type": "string", "nullable": true }, "industry": { "type": "string", "nullable": true }, "position": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true } } }, "preferredContactMethod": { "type": "string", "nullable": true }, "marketingOptIn": { "type": "boolean", "nullable": true }, "contactSource": { "type": "string", "nullable": true }, "socialMedia": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "linkedin": { "type": "string", "nullable": true }, "twitter": { "type": "string", "nullable": true }, "facebook": { "type": "string", "nullable": true }, "instagram": { "type": "string", "nullable": true } } }, "leadSource": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "tags": { "type": "array", "nullable": true, "items": { "type": "string" } }, "notes": { "type": "string", "nullable": true }, "agentContext": { "type": "string", "nullable": true }, "customFields": { "type": "object", "nullable": true, "additionalProperties": true, "maxProperties": 20, "description": "Custom JSON data, at most 20 top-level keys and 8192 UTF-8 JSON bytes, including existing values after merge.", "example": { "vendorLeadCode": "lead-123", "source": "website" } }, "lastTask": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "taskId": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "listId": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "timestamp": { "type": "number", "nullable": true }, "success": { "type": "boolean", "nullable": true } } }, "lists": { "type": "array", "nullable": true, "items": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string" }, "timestamp": { "type": "number" } } } }, "appointments": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true } } } }, "TaskGoal": { "type": "object", "nullable": true, "description": "Task-specific outcome definition. Omit or pass null to inherit the organization default.", "required": [ "completionCriteria" ], "properties": { "completionCriteria": { "type": "string", "description": "Criteria evaluated after a connected conversation." }, "description": { "type": "string", "description": "Optional goal label." } } }, "TaskRetryPolicy": { "type": "object", "nullable": true, "description": "Task-specific cadence. Omit or pass null to inherit the organization default. Use delaysSeconds or steps, never both.", "required": [ "retryOn" ], "properties": { "delaysSeconds": { "type": "array", "minItems": 1, "maxItems": 10, "description": "Delays after each attempt, each from 60 seconds through 30 days.", "items": { "type": "integer", "minimum": 60, "maximum": 2592000 } }, "steps": { "type": "array", "minItems": 1, "maxItems": 10, "description": "Strictly increasing offsets from the first attempt for channel-specific retries.", "items": { "type": "object", "required": [ "offsetSeconds", "channel" ], "properties": { "offsetSeconds": { "type": "integer", "minimum": 60, "maximum": 7776000 }, "channel": { "type": "string", "enum": [ "call", "text", "email" ] }, "target": { "type": "string", "description": "Required when changing between phone and email channels." }, "responseTimeoutSeconds": { "type": "integer", "minimum": 60, "maximum": 604800 }, "content": { "type": "object", "description": "Channel-specific content override, up to 32 KB." } } } }, "retryOn": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "busy", "delivery_failed", "goal_incomplete", "no_answer", "no_response", "no_speech", "rejected", "transient_failure", "voicemail" ] } }, "responseTimeoutSeconds": { "type": "integer", "minimum": 60, "maximum": 604800 } } }, "TaskCronSchedule": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "kind", "at" ], "properties": { "kind": { "type": "string", "enum": [ "at" ] }, "at": { "type": "string", "format": "date-time" } } }, { "type": "object", "additionalProperties": false, "required": [ "kind", "everyMs" ], "properties": { "kind": { "type": "string", "enum": [ "every" ] }, "everyMs": { "type": "integer", "minimum": 60000 } } }, { "type": "object", "additionalProperties": false, "required": [ "kind", "expr" ], "properties": { "kind": { "type": "string", "enum": [ "cron" ] }, "expr": { "type": "string", "example": "0 * * * *" }, "tz": { "type": "string", "example": "America/Chicago" } } } ] }, "TaskCallCreate": { "type": "object", "required": [ "type", "target" ], "properties": { "type": { "type": "string", "enum": [ "call" ] }, "target": { "type": "string", "description": "Phone number, email address, or supported Vida username for this Task type.", "example": "+15551234567" }, "accountId": { "type": "integer", "description": "Agent account that performs the Task.", "example": 1234 }, "title": { "type": "string" }, "context": { "type": "string", "description": "Contact context supplied to the Agent." }, "taskContext": { "type": "string", "description": "Instructions for the Agent performing this Task.", "example": "Confirm whether the customer wants a renewal quote." }, "scheduledFor": { "type": "integer", "description": "Unix timestamp for the first attempt or Computer Agent run.", "example": 1712350000 }, "externalTaskId": { "type": "string", "description": "Reusable caller-defined correlation ID; not an idempotency key." }, "contactListName": { "type": "string" }, "goal": { "$ref": "#/components/schemas/TaskGoal" }, "retryPolicy": { "$ref": "#/components/schemas/TaskRetryPolicy" }, "meta": { "type": "object", "description": "Metadata retained for filtering and reporting; it is not added to the Agent prompt.", "additionalProperties": true, "properties": { "contact": { "$ref": "#/components/schemas/TaskContactFields" } } }, "greeting": { "type": "string", "description": "Call greeting. Prefix with prompt: to generate it from an instruction." }, "waitToGreet": { "type": "boolean" } } }, "TaskTextCreate": { "type": "object", "required": [ "type", "target" ], "properties": { "type": { "type": "string", "enum": [ "text" ] }, "target": { "type": "string", "description": "Phone number, email address, or supported Vida username for this Task type.", "example": "+15551234567" }, "accountId": { "type": "integer", "description": "Agent account that performs the Task.", "example": 1234 }, "title": { "type": "string" }, "context": { "type": "string", "description": "Contact context supplied to the Agent." }, "taskContext": { "type": "string", "description": "Instructions for the Agent performing this Task.", "example": "Confirm whether the customer wants a renewal quote." }, "scheduledFor": { "type": "integer", "description": "Unix timestamp for the first attempt or Computer Agent run.", "example": 1712350000 }, "externalTaskId": { "type": "string", "description": "Reusable caller-defined correlation ID; not an idempotency key." }, "contactListName": { "type": "string" }, "goal": { "$ref": "#/components/schemas/TaskGoal" }, "retryPolicy": { "$ref": "#/components/schemas/TaskRetryPolicy" }, "meta": { "type": "object", "description": "Metadata retained for filtering and reporting; it is not added to the Agent prompt.", "additionalProperties": true, "properties": { "contact": { "$ref": "#/components/schemas/TaskContactFields" } } }, "message": { "type": "string", "description": "Initial text message." } } }, "TaskEmailCreate": { "type": "object", "required": [ "type", "target" ], "properties": { "type": { "type": "string", "enum": [ "email" ] }, "target": { "type": "string", "description": "Phone number, email address, or supported Vida username for this Task type.", "example": "+15551234567" }, "accountId": { "type": "integer", "description": "Agent account that performs the Task.", "example": 1234 }, "title": { "type": "string" }, "context": { "type": "string", "description": "Contact context supplied to the Agent." }, "taskContext": { "type": "string", "description": "Instructions for the Agent performing this Task.", "example": "Confirm whether the customer wants a renewal quote." }, "scheduledFor": { "type": "integer", "description": "Unix timestamp for the first attempt or Computer Agent run.", "example": 1712350000 }, "externalTaskId": { "type": "string", "description": "Reusable caller-defined correlation ID; not an idempotency key." }, "contactListName": { "type": "string" }, "goal": { "$ref": "#/components/schemas/TaskGoal" }, "retryPolicy": { "$ref": "#/components/schemas/TaskRetryPolicy" }, "meta": { "type": "object", "description": "Metadata retained for filtering and reporting; it is not added to the Agent prompt.", "additionalProperties": true, "properties": { "contact": { "$ref": "#/components/schemas/TaskContactFields" } } }, "message": { "type": "string", "description": "Initial email body." } } }, "TaskPingCreate": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "ping" ] }, "target": { "type": "string", "description": "Phone number, email address, or supported Vida username for this Task type.", "example": "+15551234567" }, "accountId": { "type": "integer", "description": "Agent account that performs the Task.", "example": 1234 }, "title": { "type": "string" }, "context": { "type": "string", "description": "Contact context supplied to the Agent." }, "taskContext": { "type": "string", "description": "Instructions for the Agent performing this Task.", "example": "Confirm whether the customer wants a renewal quote." }, "scheduledFor": { "type": "integer", "description": "Unix timestamp for the first attempt or Computer Agent run.", "example": 1712350000 }, "externalTaskId": { "type": "string", "description": "Reusable caller-defined correlation ID; not an idempotency key." }, "contactListName": { "type": "string" }, "goal": { "$ref": "#/components/schemas/TaskGoal" }, "retryPolicy": { "$ref": "#/components/schemas/TaskRetryPolicy" }, "meta": { "type": "object", "description": "Metadata retained for filtering and reporting; it is not added to the Agent prompt." } } }, "TaskComputerCreate": { "type": "object", "additionalProperties": false, "required": [ "type", "accountId", "taskContext" ], "properties": { "type": { "type": "string", "enum": [ "computer" ] }, "accountId": { "type": "integer", "description": "Agent account that performs the Task.", "example": 1234 }, "title": { "type": "string" }, "taskContext": { "type": "string", "description": "Instructions for the Agent performing this Task.", "example": "Confirm whether the customer wants a renewal quote." }, "scheduledFor": { "type": "integer", "description": "Unix timestamp for the first attempt or Computer Agent run.", "example": 1712350000 }, "externalTaskId": { "type": "string", "description": "Reusable caller-defined correlation ID; not an idempotency key." }, "meta": { "type": "object", "description": "Caller metadata. System-managed provider fields are reserved." } } }, "TaskRepeatingCreate": { "type": "object", "additionalProperties": false, "required": [ "type", "accountId", "title", "taskContext", "cronSchedule" ], "properties": { "type": { "type": "string", "enum": [ "repeating" ] }, "accountId": { "type": "integer", "description": "Agent account that performs the Task.", "example": 1234 }, "title": { "type": "string" }, "taskContext": { "type": "string", "description": "Instructions for the Agent performing this Task.", "example": "Confirm whether the customer wants a renewal quote." }, "state": { "type": "string", "enum": [ "active", "paused" ], "default": "active" }, "cronSchedule": { "$ref": "#/components/schemas/TaskCronSchedule" } } }, "TaskCronOneOffCreate": { "type": "object", "additionalProperties": false, "required": [ "type", "accountId", "title", "taskContext", "cronSchedule" ], "properties": { "type": { "type": "string", "enum": [ "cronOneOff" ] }, "accountId": { "type": "integer", "description": "Agent account that performs the Task.", "example": 1234 }, "title": { "type": "string" }, "taskContext": { "type": "string", "description": "Instructions for the Agent performing this Task.", "example": "Confirm whether the customer wants a renewal quote." }, "state": { "type": "string", "enum": [ "active", "paused" ], "default": "active" }, "cronSchedule": { "$ref": "#/components/schemas/TaskCronSchedule" } } }, "TaskCreate": { "oneOf": [ { "$ref": "#/components/schemas/TaskCallCreate" }, { "$ref": "#/components/schemas/TaskTextCreate" }, { "$ref": "#/components/schemas/TaskEmailCreate" }, { "$ref": "#/components/schemas/TaskPingCreate" }, { "$ref": "#/components/schemas/TaskComputerCreate" }, { "$ref": "#/components/schemas/TaskRepeatingCreate" }, { "$ref": "#/components/schemas/TaskCronOneOffCreate" } ], "discriminator": { "propertyName": "type", "mapping": { "call": "#/components/schemas/TaskCallCreate", "text": "#/components/schemas/TaskTextCreate", "email": "#/components/schemas/TaskEmailCreate", "ping": "#/components/schemas/TaskPingCreate", "computer": "#/components/schemas/TaskComputerCreate", "repeating": "#/components/schemas/TaskRepeatingCreate", "cronOneOff": "#/components/schemas/TaskCronOneOffCreate" } } } } }, "tags": [ { "name": "Agents" }, { "name": "Apps", "description": "Install Vida apps and use their enabled integration functions." }, { "name": "Integrations", "description": "Configure Vader integrations." }, { "name": "Inbound Email", "description": "Control which senders may create inbound email work for an Agent." }, { "name": "Features", "description": "Inspect capabilities available within an account hierarchy." }, { "name": "Conversation Logs", "description": "Query conversation activity and calculate account-level metrics." }, { "name": "Computer Agents", "description": "Set up, configure, inspect, and manage Vida Computer Agents." }, { "name": "Computer Agent Sessions", "description": "View and reset Computer Agent sessions." }, { "name": "Accounts" }, { "name": "Agent Templates", "description": "Create, manage, and apply reusable Agent configurations." } ] }