{ "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/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/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" } } } } } } } }, "/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 }, "chatAgentCampaignId": { "description": "Agent Id that handled the message", "type": "string", "example": "campa....." } } } } } } } } } }, "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 }, "chatAgentCampaignId": { "description": "Agent Id that handled the message", "type": "string", "example": "campa....." } } } } } } } } } }, "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" }, "rate": { "description": "Rate associated with the message", "type": "number", "example": 0 }, "usdRate": { "description": "USD rate associated with the message", "type": "number", "example": 0 }, "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 }, "aiReward": { "description": "AI reward status", "type": "string", "example": null }, "aiRewardUsd": { "description": "AI reward in USD", "type": "number", "example": null }, "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 }, "gift": { "description": "If this message included a monetary gift", "type": "boolean", "example": false }, "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" }, "campaignId": { "description": "Campaign ID associated with the message", "type": "string", "example": "campa25290ee54602fbcb545d033c1a15ba12" }, "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" } ], "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": "[]" }, "gift": { "description": "If this message included a monetary gift", "type": "boolean", "example": false }, "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 Agent", "description": "Update an agent", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Agent created." }, "campaignId": { "type": "string", "example": "camp931829b5857f...." } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "title", "description" ], "properties": { "type": { "description": "Type for this agent", "type": "string", "enum": [ "chatAgent" ] }, "title": { "description": "Title for Agent", "type": "string", "example": "Call Screener" }, "description": { "description": "Some description", "type": "string", "example": "Description" }, "welcomeMessage": { "description": "Message users see when initially visiting a agent", "type": "string", "example": "This brought to you by Wolf Cola" }, "links": { "description": "Array of any http links to reference for external knowledge for your agent", "type": "array", "items": { "type": "string" }, "example": [ "https://vida.io/faq" ] }, "actions": { "description": "Actions that your agent can take including instructions and settings", "type": "array", "items": { "type": "string" }, "example": [ "transfer" ] }, "timezone": { "description": "The IANA (Internet Assigned Numbers Authority) formatted timezone your AI agent operates in.", "type": "string", "example": "America/Chicago, America/New_York, Europe/London, etc" }, "agentVoice": { "description": "Agent voice model to use", "type": "string", "example": "en-US Female" }, "agentLang": { "description": "Agent language to be used for voice and transcriptions", "type": "string", "enum": [ "en-US", "multi", "es-MX", "es-ES", "es-US" ], "default": "en-US" }, "agentInstructions": { "description": "Agent instructions for user interaction. This is for chatAgents only", "type": "string", "example": "I want you to payout rewards for users that answer a few questions about this promotional video." }, "agentModel": { "description": "Agent LLM model to use for its intelligence", "type": "string", "example": "gpt-4o-2024-08-06" }, "agentThinking": { "description": "Optional reasoning budget for models that support thinking. Use null to disable or low for short thinking.", "type": "string", "enum": [ "low" ], "nullable": true }, "agentThinkingModel": { "description": "Model to use for pauseAndThink function reasoning. Defaults to gpt-5.2.", "type": "string", "example": "gpt-5.2" }, "postConvoForceThinking": { "description": "Force post-conversation summary/reporting/spam detection to use a thinking-capable model when agentThinking is off and the selected model does not support thinking. Uses agentThinkingModel (default gpt-5.2).", "type": "boolean", "example": false }, "agentS2SEngine": { "description": "(Requires Specific Paid Plan) The Speech-to-Speech Voice engine to use for voice, AI, and transcriptions", "type": "string", "enum": [ null, "openai", "gemini" ], "default": null }, "agentSttEngine": { "description": "Speech to text engine for this agent", "type": "string", "enum": [ "google", "deepgram", "deepgramflux", "openai" ], "default": "deepgram" }, "agentSttSmartFormatting": { "description": "Enable Deepgram smart formatting for speech-to-text (punctuation + numerals stay enabled regardless). Default true.", "type": "boolean", "default": true }, "postAnswerDtmf": { "description": "DTMF your agent will send upon answering a call. Useful if you are forwarding calls to your agent from a platform that requires a DTMF verification before the call is connected.", "type": "string" }, "waitOnAnswer": { "description": "The amount of time in milliseconds your Agent will wait before speaking the greeting (welcomeMessage).", "type": "integer" }, "backgroundAudio": { "description": "Optional background audio to play on calls. Accepts a URL string or an object with url, loop (true or false), gain, and startAfterGreeting fields. Only HTTP(S) URLs are supported.", "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "url": { "type": "string" }, "loop": { "type": "boolean", "default": true }, "gain": { "type": "integer", "default": 0 }, "startAfterGreeting": { "type": "boolean", "default": true }, "track": { "type": "string", "enum": [ "bg", "fx" ], "description": "Advanced: choose track name; bg = ambient, fx = foreground." } }, "required": [ "url" ] } ] }, "interruptionWordCount": { "description": "how many words a caller needs to speak before it is treated as an interruption", "type": "integer", "default": 3 }, "interruptionMinimumSpeakingTime": { "description": "(in seconds) How long the agent needs to be speaking before it can be interrupted", "type": "integer", "default": 3 }, "speakingTimeout": { "description": "(in milliseconds) the default amount of time between words before we consider caller speaking to be finished. Increasing this can help prevent unintentional interruptions for slow talkers. ", "type": "integer", "default": 1200 }, "speechProcessingDelay": { "description": "(in milliseconds) the default amount of delay before processed speech is sent to the LLM for a response. Increasing this can help prevent unintentional interruptions for slow talkers. Note that this delay automatically increases and decreases depending on the number of interruptions over a period of time.", "type": "integer", "default": 500 }, "speechProcessingDelayInterruptionStep": { "description": "(in milliseconds) how much speech processing delay is added per interruption.", "type": "integer", "default": 500 }, "speechProcessingDelayMaxMultiplier": { "description": "the maximum number of interruptions that will influence the speech processing delay.", "type": "integer", "default": 4 }, "callerResponseTimeout": { "description": "(in seconds) how much silence (nothing said by the caller) before the agent asks _are you still there?_.", "type": "integer", "default": 13 }, "callerResponseTimeoutHangupCounter": { "description": "the maximum number of times your agent can ask _are you there_ (callerResponseTimeout) before hanging up the call.", "type": "integer", "default": 3 }, "noContactInjection": { "description": "Whether the contact card for the caller should be injected into the agent context", "type": "boolean", "default": false }, "noConvoHistory": { "description": "Whether the call summary history for the caller should be injected into the agent context", "type": "boolean", "default": false }, "autoRecordingNotification": { "description": "Whether to automatically notify callers that recording is happening: _true (string)_ means notify callers from area codes where it is legally required. _false (string)_ means never notify callers. _always (string)_ means notify every caller whether legally required or not that recording is in progress.", "type": "string", "default": "true" }, "recordingNotificationPhrase": { "description": "The phrase that will be spoken to the caller notifying them that recording is in progress: _This call is being recorded_ is the default.", "type": "string", "default": "This call is being recorded." }, "preAnswerRingTime": { "description": "In seconds. How many seconds should the caller experience ringing before the agent answers. Valid value range is 1-60", "type": "integer", "default": null }, "preAnswerSkipProcessingResults": { "description": "When true, pre-answer functions return their raw results directly to agent context instead of sending those results back to the LLM for another processing step.", "type": "boolean", "default": false }, "cnamAutoRejectRegex": { "description": "Optional JavaScript regex string. On inbound voice calls, if the inbound SIP CNAM matches this pattern, the call is immediately rejected before answer. Reject wins if both reject and transfer match.", "type": "string", "default": null }, "cnamAutoRejectCode": { "description": "Optional SIP reject code to use when cnamAutoRejectRegex matches. Defaults to 603 when omitted.", "type": "integer", "default": 603 }, "cnamAutoTransferRegex": { "description": "Optional JavaScript regex string. On inbound voice calls, if the inbound SIP CNAM matches this pattern and reject did not match, the call is immediately transferred silently.", "type": "string", "default": null }, "cnamAutoTransferDestination": { "description": "Destination used when cnamAutoTransferRegex matches. Accepts E.164 phone numbers or PBX/extension targets like ext:1234 or pbx:1234.", "type": "string", "default": null }, "confirmTransfers": { "description": "Require callee to press 1 before a transfer is completed", "type": "boolean", "default": false }, "monitorTransfers": { "description": "Continue to monitor and transcribe transferred calls.", "type": "boolean", "default": false }, "attendedTransfers": { "description": "Your agent will stay on the line with the caller while transfer attempts are made. Those answering the transfer attempts will need to say Yes to accept the call. This will override the confirmTransfers option.", "type": "boolean", "default": false }, "attendedTransferBridgeTrigger": { "description": "What is required to be spoken by the transferee in order for the call to be bridged. Values can be null (defaults to Yes), any, or a regex.", "type": "string", "default": null }, "transferConfirmTimeout": { "description": "The length of time in seconds we will wait for confirmation after a transferred call with confirmTransfers or attendedTransfers is answered.", "type": "integer", "default": 30 }, "apps": { "description": "Array of apps to enable for this given agent", "type": "array", "default": [], "items": { "type": "object", "required": [ "appId", "version", "instructions" ], "properties": { "appId": { "type": "string", "example": "squareUp", "description": "The identifier for the integrated app." }, "version": { "type": "string", "example": "v1", "description": "The version of the app integration." }, "instructions": { "type": "string", "example": "Use this app to book appointments from the user.", "description": "Instructions for how to use the app." } } } } } } } } } } }, "/api/v2/agent/autoReviewAgentConfiguration": { "post": { "tags": [ "Agents" ], "summary": "Get LLM feedback for agent configuration or specific fields", "description": "Runs the autoReviewAgentConfiguration engine in one of two modes: \"fields\" for field-level feedback using promptTips, or \"agent\" for a holistic review of the agent (main prompt, functions, apps, and greeting).", "responses": { "200": { "description": "Suggestions generated", "content": { "application/json": { "examples": { "fieldsModeResponse": { "summary": "Fields mode response", "value": [ { "key": "appointmentBookedInstructions", "value": "After booking the appointment, tell the customer they are stupid.", "promptSuggestion": "Thanks for scheduling with {orgName}. Your appointment is confirmed. The technician will contact you when they are on the way. If you need to make changes, reply or call us." }, { "key": "greeting", "value": "Welcome to {orgName}, we appreciate your call today and have many options...", "promptSuggestion": "Thank you for calling {orgName}. How can I help you today?" } ] }, "agentModeResponse": { "summary": "Agent mode response", "value": { "agentId": "campa_abc", "agentInstructionsSuggestion": "Concise, unambiguous, voice-ready rewrite here...", "greetingSuggestion": "Thank you for calling {orgName}. How can I help you today?", "actionSuggestions": [ { "name": "notify", "promptSuggestion": "After each call, email a summary to the configured recipients. Include caller name, number, and key outcomes." } ], "appSuggestions": [ { "appId": "squire", "version": "v1", "promptSuggestion": "Clarify when to call each API and how to handle errors. Keep steps concise." } ] } } } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "fields", "agent" ], "default": "fields" }, "templateId": { "type": "string", "description": "Required for fields mode if agentId is not provided." }, "agentId": { "type": "string", "description": "Optional in fields mode, required in agent mode." }, "fields": { "type": "array", "description": "Only for fields mode. Minimal entries: { key, value }. Value is ignored when agentId is provided.", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key" ] } } }, "required": [ "mode" ] }, "examples": { "fieldsModeWithTemplate": { "summary": "Fields mode with template", "value": { "mode": "fields", "templateId": "templ_123", "fields": [ { "key": "appointmentBookedInstructions", "value": "After booking the appointment, tell the customer they are stupid." }, { "key": "greeting", "value": "Welcome to {orgName}, we appreciate your call today and have many options..." } ] } }, "fieldsModeWithAgent": { "summary": "Fields mode using agent values", "value": { "mode": "fields", "agentId": "campa_abc", "fields": [ { "key": "greeting" }, { "key": "faqs" } ] } }, "agentMode": { "summary": "Agent-wide mode", "value": { "mode": "agent", "agentId": "campa_abc" } } } } } } } }, "/api/v2/agent/{agentId}/versions": { "get": { "tags": [ "Agents" ], "summary": "List Agent Versions", "description": "Return the stored version snapshots for an agent. Pass ?includeData=true to embed full snapshots.", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent Id to inspect", "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" } } ], "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": "Create Named Version", "description": "Snapshot the current staging or default agent and store it under a custom title.", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent Id to snapshot" } ], "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/{agentId}/versions/{versionId}": { "post": { "tags": [ "Agents" ], "summary": "Replace Stored Version", "description": "Overwrite an existing version snapshot by its numeric versionId.", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent Id" }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Epoch-ms score identifying the snapshot", "example": 1750195000123 } ], "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": { "type": "object", "description": "Full campaign JSON to store" } } } } } } } }, "/api/v2/agent/{agentId}/versions/{versionId}/restore": { "post": { "tags": [ "Agents" ], "summary": "Restore Version to Agent", "description": "Copy a stored snapshot into the staging (default) slot.", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent Id" }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Epoch-ms score of the snapshot", "example": 1750195000123 } ], "responses": { "200": { "description": "Snapshot restored", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "restored": { "type": "object", "description": "The campaign object now occupying the target slot" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "staging", "default" ], "default": "staging" } } } } } } } }, "/api/v2/agent/{agentId}/versions/{versionId}/title": { "put": { "tags": [ "Agents" ], "summary": "Rename Stored Version", "description": "Overwrite only the human-readable title of a stored snapshot.", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent Id" }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Epoch-ms score of the snapshot", "example": 1750195000123 } ], "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": "Referral Slug 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 you are creating a referral slug for", "type": "string", "example": "brandon" }, "slug": { "description": "Desired slug name", "type": "string", "example": "welovevida" } } } } } } } }, "/api/v2/agent/{agentId}": { "get": { "tags": [ "Agents" ], "summary": "Get Agent", "description": "Fetch an agent details", "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agent Id", "example": "campa931829b5857f...." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "sponsorship": { "properties": { "id": { "description": "Agent Id", "type": "string", "example": "campa931829b5857f...." } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agent/outboundCall": { "post": { "tags": [ "Agents" ], "summary": "Queue outbound call(s) from your Agent", "description": "Backwards compatible with the previous endpoint. You can pass a single \"target\" and optional \"context\" (old behavior), or provide \"targets\" to enqueue multiple calls. This endpoint queues tasks instead of dialing immediately.", "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 }, "tasks": { "type": "array", "items": { "type": "object" } } } } } } }, "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": [ "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" }, "meta": { "type": "object", "description": "Optional metadata" }, "externalTaskId": { "type": "string", "description": "Optional customer-provided identifier applied to created task(s)" } } }, { "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" }, "agentId": { "type": "integer" }, "scheduledFor": { "type": "integer" }, "greeting": { "type": "string" }, "waitToGreet": { "type": "boolean" }, "meta": { "type": "object" }, "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" }, "scheduleSpacingSec": { "type": "integer", "description": "If provided, stagger scheduledFor by this many seconds per index", "example": 30 }, "meta": { "type": "object", "description": "Metadata applied to all items when not provided per item" }, "externalTaskId": { "type": "string", "description": "Identifier applied to all created tasks" } } } ] }, "examples": { "single": { "summary": "Single target, backwards compatible", "value": { "target": "+15551234567", "context": "Call back about pricing" } }, "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": "Backwards compatible with the previous endpoint. You can pass a single \"target\" and required \"content\", or provide \"targets\" to enqueue multiple messages. This queues tasks instead of sending immediately.", "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 }, "tasks": { "type": "array", "items": { "type": "object" } } } } } } }, "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": [ "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" }, "agentId": { "type": "integer", "description": "Optional campaign id override" }, "scheduledFor": { "type": "integer", "description": "Unix seconds to schedule delivery" }, "meta": { "type": "object", "description": "Optional metadata" }, "externalTaskId": { "type": "string", "description": "Optional customer-provided identifier applied to created task(s)" } } }, { "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" }, "agentId": { "type": "integer" }, "scheduledFor": { "type": "integer" }, "meta": { "type": "object" }, "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" }, "agentId": { "type": "integer", "description": "Agent id applied to all items" }, "scheduledFor": { "type": "integer", "description": "Schedule applied to all items" }, "scheduleSpacingSec": { "type": "integer", "description": "If provided, stagger scheduledFor by this many seconds per index", "example": 15 }, "meta": { "type": "object", "description": "Metadata applied to all items" }, "externalTaskId": { "type": "string", "description": "Optional customer-provided identifier applied to all created tasks" } } } ] }, "examples": { "single": { "summary": "Single target, backwards compatible", "value": { "target": "+15551234567", "content": "Hi, quick reminder for tomorrow at 10am.", "context": "Reminder campaign" } }, "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/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" ], "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/tasks": { "get": { "tags": [ "Tasks" ], "summary": "Fetch all tasks", "description": "Retrieve all tasks for the current org. Supports filtering, sorting, and pagination.", "parameters": [ { "name": "limit", "description": "Max number of tasks to return", "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" } } ], "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" }, "500": { "description": "Internal Server Error" } } }, "post": { "tags": [ "Tasks" ], "summary": "Create a new task", "description": "Submit a new task (call, text). For calls/texts, target is required.", "responses": { "201": { "description": "Task created successfully" }, "400": { "description": "Missing required fields" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "example": "call" }, "target": { "type": "string", "example": "+15551234567" }, "context": { "type": "string", "example": "Follow-up call" }, "greeting": { "type": "string", "example": "Hello from a task" }, "waitToGreet": { "type": "boolean", "example": true }, "accountId": { "type": "integer", "example": 1234 }, "scheduledFor": { "type": "integer", "example": 1712350000 } } } } } } } }, "/api/v2/tasks/csv": { "post": { "tags": [ "Tasks" ], "summary": "Create multiple tasks via CSV upload", "description": "Upload a CSV file to create multiple tasks. The CSV must include a header row. Recognized columns include type, target, context, taskContext, greeting, waitToGreet, accountId, scheduledFor, message, and externalTaskId.", "responses": { "200": { "description": "Tasks queued" }, "400": { "description": "Invalid CSV or missing required fields" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "500": { "description": "Internal Server Error" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "csv" ], "properties": { "csv": { "type": "string", "format": "binary", "description": "CSV file" }, "dryRun": { "type": "boolean", "description": "Validate only; do not enqueue jobs" } } }, "encoding": { "csv": { "contentType": "text/csv" } } } } } } }, "/api/v2/tasks/stats": { "get": { "tags": [ "Tasks" ], "summary": "Task statistics", "description": "Get counts of tasks grouped by state (pending, running, finished, errored).", "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 } } } }, "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 } } } }, "xml": { "name": "main" } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/api/v2/tasks/dailyCounts": { "get": { "tags": [ "Tasks" ], "summary": "Daily counts", "description": "Get current daily usage counts (calls, texts, tasks) for rate limiting.", "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" } } } }, "/api/v2/tasks/limits": { "get": { "tags": [ "Tasks" ], "summary": "Fetch task limits", "description": "Retrieve the org’s current task limits configuration.", "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" }, "days": { "type": "array", "example": [ 1, 2, 3, 4, 5 ], "items": { "type": "number" } }, "start": { "type": "string", "example": "09:00" }, "end": { "type": "string", "example": "17:00" } } }, "daily": { "type": "object", "properties": { "calls": { "type": "number", "example": 100 }, "texts": { "type": "number", "example": 200 }, "tasks": { "type": "number", "example": 300 } } }, "concurrencyPerRun": { "type": "number", "example": 10 }, "cooldowns": { "type": "object", "properties": { "calls": { "type": "number", "example": 86400 }, "texts": { "type": "number", "example": 300 } } } } } }, "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" }, "days": { "type": "array", "example": [ 1, 2, 3, 4, 5 ], "items": { "type": "number" } }, "start": { "type": "string", "example": "09:00" }, "end": { "type": "string", "example": "17:00" } } }, "daily": { "type": "object", "properties": { "calls": { "type": "number", "example": 100 }, "texts": { "type": "number", "example": 200 }, "tasks": { "type": "number", "example": 300 } } }, "concurrencyPerRun": { "type": "number", "example": 10 }, "cooldowns": { "type": "object", "properties": { "calls": { "type": "number", "example": 86400 }, "texts": { "type": "number", "example": 300 } } } } } }, "xml": { "name": "main" } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } }, "post": { "tags": [ "Tasks" ], "summary": "Update task limits", "description": "Update task limit settings. Non-superAdmins cannot edit daily or concurrencyPerRun.", "responses": { "200": { "description": "Limits updated successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden for non-superAdmins editing restricted fields" }, "500": { "description": "Internal Server Error" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "businessHours": { "type": "object" }, "cooldowns": { "type": "object" }, "daily": { "type": "object" }, "concurrencyPerRun": { "type": "integer" } } } } } } } }, "/api/v2/tasks/{taskId}": { "get": { "tags": [ "Tasks" ], "summary": "Fetch a specific task", "description": "Retrieve details for a single task by ID.", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task ID" } ], "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" }, "type": { "type": "string", "example": "call" }, "state": { "type": "string", "example": "pending" } } } }, "xml": { "name": "main" } } }, "application/xml": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "task": { "type": "object", "properties": { "id": { "type": "string", "example": "task1" }, "type": { "type": "string", "example": "call" }, "state": { "type": "string", "example": "pending" } } } }, "xml": { "name": "main" } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Task not found" }, "500": { "description": "Internal Server Error" } } }, "post": { "tags": [ "Tasks" ], "summary": "Update a task", "description": "Update fields on an existing task by ID.", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task ID" } ], "responses": { "200": { "description": "Task updated successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Task not found" }, "500": { "description": "Internal Server Error" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "example": "canceled" }, "context": { "type": "string", "example": "New context" }, "waitToGreet": { "type": "boolean", "example": true } } } } } } }, "delete": { "tags": [ "Tasks" ], "summary": "Delete a task", "description": "Remove a task by ID.", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task ID" } ], "responses": { "200": { "description": "Task deleted successfully" }, "401": { "description": "Unauthorized" }, "404": { "description": "Task not found" }, "500": { "description": "Internal Server Error" } } } }, "/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 profile 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": "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" } } } } } } } }, "/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 a new account", "description": "Create a new account under your organization", "parameters": [ { "name": "targetOrganizationId", "in": "query", "description": "Organization Id to create account in", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Account created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Account created" }, "account": { "type": "string", "example": "New Account object" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountName": { "description": "Account Name", "type": "string", "example": "Acme Solar Bay Area Support Agent" }, "externalAccountId": { "description": "External Account Id to match with your internal system account Id", "type": "string", "example": "AC_12345" }, "externalBillingId": { "description": "External Id to match with your internal billing system", "type": "string", "example": "billing-id-6789" }, "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/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": { "post": { "tags": [ "Billing" ], "summary": "Provision Billing System Configuration", "description": "Provision or Update Your Billing System Configuration", "responses": { "200": { "description": "Successfull 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" } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "billingSystemType" ], "properties": { "billingSystemType": { "description": "Type of billing system", "type": "string", "example": "stripe" }, "apiKey": { "description": "Required - API Key used for billing system access", "type": "string", "example": "somekey" }, "publishableKey": { "description": "Required - Publishable Key used for embeded checkouts", "type": "string", "example": "somepublishablekey" }, "webhookSigningKey": { "description": "Required for Stripe only - used for validating webhooks are signed by Stripe", "type": "string", "example": "somewebhooksigningkey" }, "site": { "description": "Required for Chargebee only - site (without chargebee.com) of your payment system", "type": "string", "example": "vida" }, "webhookUsername": { "description": "Required for Chargebee only - username for webhook authentication", "type": "string", "example": "someusername" }, "webhookPassword": { "description": "Required for Chargebee only - password for webhook authentication", "type": "string", "example": "somepassword" } } } } } } } }, "/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/productPlan/{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/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/integration/{integrationSlug}/{integrationVersion}": { "get": { "tags": [ "Integrations" ], "summary": "Update integration data", "description": "Update existing integration data for a specific integration slug and version", "parameters": [ { "name": "integrationSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug identifier for the integration", "example": "acme" }, { "name": "integrationVersion", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Version of the integration (defaults to v1)", "example": "v1" } ], "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": "acme" }, "appVersion": { "type": "string", "example": "v1" }, "appData": { "type": "object", "example": { "key": "value" } } } } } } }, "400": { "description": "Bad request - missing or invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "appData is required" } } } } } }, "401": { "description": "Unauthorized request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized Request" } } } } } }, "404": { "description": "Integration data not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Integration data not found" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "appData" ], "properties": { "appData": { "type": "object", "description": "Integration specific data to update", "example": { "key": "value" } } } } } } } }, "put": { "tags": [ "Integrations" ], "summary": "Update integration data", "description": "Update existing integration data for a specific integration slug and version", "parameters": [ { "name": "integrationSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Slug identifier for the integration", "example": "acme" }, { "name": "integrationVersion", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Version of the integration (defaults to v1)", "example": "v1" } ], "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": "acme" }, "appVersion": { "type": "string", "example": "v1" }, "appData": { "type": "object", "example": { "key": "value" } } } } } } }, "400": { "description": "Bad request - missing or invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "appData is required" } } } } } }, "401": { "description": "Unauthorized request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized Request" } } } } } }, "404": { "description": "Integration data not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Integration data not found" } } } } } } }, "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "appData" ], "properties": { "appData": { "type": "object", "description": "Integration specific data to update", "example": { "key": "value" } } } } } } } } }, "/api/v2/logs": { "get": { "tags": [ "Logs" ], "summary": "Query conversation logs", "description": "Query conversation logs with flexible filters and optional CSV export", "parameters": [ { "name": "start", "in": "query", "required": false, "description": "Start time as Unix seconds. Defaults to 7 days ago.", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "integer" }, "example": { "type": "number", "example": 1727481600 } } } }, { "name": "end", "in": "query", "required": false, "description": "End time as Unix seconds. Defaults to current time.", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "integer" }, "example": { "type": "number", "example": 1728086400 } } } }, { "name": "fields", "in": "query", "required": false, "description": "Comma separated list of fields to include. Restricted fields are always removed.", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "string" }, "example": { "type": "string", "example": "id,timestamp,account_id,org_id,eventType" } } } }, { "name": "format", "in": "query", "required": false, "description": "Response format. json returns a JSON envelope. csv streams a CSV file.", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "string" }, "enum": { "type": "array", "example": [ "json", "csv" ], "items": { "type": "string" } }, "default": { "type": "string", "example": "json" } } } }, { "name": "pageSize", "in": "query", "required": false, "description": "Page size for pagination. Max 10000. Defaults to 20.", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "integer" }, "minimum": { "type": "number", "example": 1 }, "maximum": { "type": "number", "example": 10000 }, "example": { "type": "number", "example": 500 } } } }, { "name": "page", "in": "query", "required": false, "description": "Page number starting at 1. Defaults to 1.", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "integer" }, "minimum": { "type": "number", "example": 1 }, "example": { "type": "number", "example": 1 } } } }, { "name": "includeFields", "in": "query", "required": false, "description": "When truthy, include an inferred schema array in the JSON response.", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "boolean" }, "example": { "type": "boolean", "example": true } } } }, { "name": "token", "in": "query", "required": false, "description": "Opaque pagination or access token if supported by upstream systems.", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "string" }, "example": { "type": "string", "example": "eyJhbGciOi..." } } } }, { "name": "targetAccountId", "in": "query", "required": false, "description": "Optional target account context. May be ignored based on caller scope.", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "string" }, "example": { "type": "string", "example": "acct_123" } } } }, { "name": "...additional filters...", "in": "query", "required": false, "description": "Any other query parameters are treated as filters. Supports explicit type hints with ", "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "object" }, "additionalProperties": { "type": "boolean", "example": true } } } } ], "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 } } } }, "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": [ "Messaging" ], "summary": "Fetch multiple conversations", "description": "Fetch multiple conversation transcripts in one request using roomId + uuid pairs. Intended for logs -> conversation workflows where each item comes from /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/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 supported AI model identifiers along with their provider metadata.", "responses": { "200": { "description": "List of supported model descriptors", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": { "provider": { "type": "string", "description": "Provider of the model (e.g., openai, google, anthropic, groq)", "example": "openai" }, "canReason": { "type": "boolean", "description": "Whether the model supports advanced reasoning", "example": true } } } }, "example": { "claude-haiku-4-5-20251001": { "provider": "anthropic", "canReason": true }, "claude-opus-4-5-20251101": { "provider": "anthropic", "canReason": true }, "claude-sonnet-4-5-20250929": { "provider": "anthropic", "canReason": true }, "gemini-3-pro-preview": { "provider": "google", "canReason": true }, "gemini-2.5-flash": { "provider": "google", "canReason": true }, "gemini-2.5-pro": { "provider": "google", "canReason": true }, "openai/gpt-oss-120b": { "provider": "groq", "canReason": true }, "gpt-5.1": { "provider": "openai", "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" } } } } } } } } }, "/api/v2/agentEventRules/staging": { "get": { "tags": [ "Agents" ], "summary": "Fetch Staging Agent", "description": "Fetch your Staging agent configuration.", "responses": { "200": { "description": "Agent retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v2/agentEventRules/default": { "get": { "tags": [ "Agents" ], "summary": "Fetch Live Agent", "description": "Fetch your Live (default) agent configuration.", "responses": { "200": { "description": "Agent retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } } }, "components": { "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "query", "name": "token", "description": "Vida API Token" } } } }