Creates a one-time use agent with automatic expiration.
Ephemeral agents are more appropiate for use cases where you want to spin up an customized agent without persisting it long-term in the iwy dashboard. Ephemeral agents won’t appear in the dashboard. The agent will automatically expire after a specified time to live (TTL).
POST
/
ephemeral-agent
Create ephemeral agent
curl --request POST \
--url https://api.iwy.ai/v1/ephemeral-agent \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"configuration": {
"llm": {
"model": "gemini-2.0-flash",
"provider": "google",
"system_prompt": "You are a helpful assistant for a product demo",
"first_message": "Welcome to the demo! How can I help you today?"
},
"tts": {
"provider": "elevenlabs",
"voice_id": "21m00Tcm4TlvDq8ikWAM"
},
"video": {
"provider": "binary",
"character_id": "0001"
}
}
}
'
import requests
url = "https://api.iwy.ai/v1/ephemeral-agent"
payload = { "configuration": {
"llm": {
"model": "gemini-2.0-flash",
"provider": "google",
"system_prompt": "You are a helpful assistant for a product demo",
"first_message": "Welcome to the demo! How can I help you today?"
},
"tts": {
"provider": "elevenlabs",
"voice_id": "21m00Tcm4TlvDq8ikWAM"
},
"video": {
"provider": "binary",
"character_id": "0001"
}
} }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
configuration: {
llm: {
model: 'gemini-2.0-flash',
provider: 'google',
system_prompt: 'You are a helpful assistant for a product demo',
first_message: 'Welcome to the demo! How can I help you today?'
},
tts: {provider: 'elevenlabs', voice_id: '21m00Tcm4TlvDq8ikWAM'},
video: {provider: 'binary', character_id: '0001'}
}
})
};
fetch('https://api.iwy.ai/v1/ephemeral-agent', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.iwy.ai/v1/ephemeral-agent",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'configuration' => [
'llm' => [
'model' => 'gemini-2.0-flash',
'provider' => 'google',
'system_prompt' => 'You are a helpful assistant for a product demo',
'first_message' => 'Welcome to the demo! How can I help you today?'
],
'tts' => [
'provider' => 'elevenlabs',
'voice_id' => '21m00Tcm4TlvDq8ikWAM'
],
'video' => [
'provider' => 'binary',
'character_id' => '0001'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.iwy.ai/v1/ephemeral-agent"
payload := strings.NewReader("{\n \"configuration\": {\n \"llm\": {\n \"model\": \"gemini-2.0-flash\",\n \"provider\": \"google\",\n \"system_prompt\": \"You are a helpful assistant for a product demo\",\n \"first_message\": \"Welcome to the demo! How can I help you today?\"\n },\n \"tts\": {\n \"provider\": \"elevenlabs\",\n \"voice_id\": \"21m00Tcm4TlvDq8ikWAM\"\n },\n \"video\": {\n \"provider\": \"binary\",\n \"character_id\": \"0001\"\n }\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}
HttpResponse<String> response = Unirest.post("https://api.iwy.ai/v1/ephemeral-agent")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"configuration\": {\n \"llm\": {\n \"model\": \"gemini-2.0-flash\",\n \"provider\": \"google\",\n \"system_prompt\": \"You are a helpful assistant for a product demo\",\n \"first_message\": \"Welcome to the demo! How can I help you today?\"\n },\n \"tts\": {\n \"provider\": \"elevenlabs\",\n \"voice_id\": \"21m00Tcm4TlvDq8ikWAM\"\n },\n \"video\": {\n \"provider\": \"binary\",\n \"character_id\": \"0001\"\n }\n }\n}")
.asString();
require 'uri'
require 'net/http'
url = URI("https://api.iwy.ai/v1/ephemeral-agent")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"configuration\": {\n \"llm\": {\n \"model\": \"gemini-2.0-flash\",\n \"provider\": \"google\",\n \"system_prompt\": \"You are a helpful assistant for a product demo\",\n \"first_message\": \"Welcome to the demo! How can I help you today?\"\n },\n \"tts\": {\n \"provider\": \"elevenlabs\",\n \"voice_id\": \"21m00Tcm4TlvDq8ikWAM\"\n },\n \"video\": {\n \"provider\": \"binary\",\n \"character_id\": \"0001\"\n }\n }\n}"
response = http.request(request)
puts response.read_body
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"iwy.ai Documentation","colors":{"primary":"#300040","light":"#e77ff5","dark":"#300040"},"logo":{"light":"https://mintcdn.com/iwy/G25hY7NOv8_8zjPz/logo/light.svg?fit=max\u0026auto=format\u0026n=G25hY7NOv8_8zjPz\u0026q=85\u0026s=90364bd7576f99beaec49d7b01a6b375","dark":"https://mintcdn.com/iwy/G25hY7NOv8_8zjPz/logo/dark.svg?fit=max\u0026auto=format\u0026n=G25hY7NOv8_8zjPz\u0026q=85\u0026s=838712dacbfc0f01cfc065bccd6aa52f"},"favicon":"/favicon.svg","api":{"playground":{}},"background":{"image":"https://mintlify.s3.us-west-1.amazonaws.com/iwy/images/background.png","color":{"light":"#fefdf6","dark":"#1a1a1a"}},"navbar":{"links":[{"label":"Homepage","href":"https://www.iwy.ai"},{"label":"Contact","href":"https://www.iwy.ai/contact"}],"primary":{"type":"button","label":"Start Building","href":"https://app.iwy.ai"}},"footer":{"socials":{"github":"https://github.com/iwy-ai"}},"styling":{"codeblocks":"dark","latex":false},"contextual":{"options":["copy","view","mcp"]},"navigation":{"global":{"anchors":[{"anchor":"Homepage","icon":"house","href":"https://www.iwy.ai"},{"anchor":"Dashboard","icon":"gear","href":"https://app.iwy.ai"},{"anchor":"GitHub","icon":"github","href":"https://github.com/iwy-ai"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"iwy","hasAudioNarration":false,"actualSubdomain":"iwy","customDomains":["docs.iwy.ai"],"gitSource":{"type":"github","owner":"iwy-ai","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6a21e7388d1fcd719df04d2a","collectionId":"6cce78fc-8db1-4542-b3be-1b66c34e1fbe","schemaVersion":"v2"},"entitlements":{},"buildId":"6a21e7388d1fcd719df04d2a:success","clientVersion":"0.0.4044","searchFilterCounts":[{"language":"default","tag":"API Reference","count":19},{"language":"default","tag":"Tools","count":7},{"language":"default","tag":"Permanent Agents","count":6},{"language":"default","tag":"Overview","count":6},{"language":"default","tag":"Connect \u0026 Embed","count":5},{"language":"default","tag":"Single-Use Agents","count":2},{"language":"default","tag":"Sessions","count":2},{"language":"default","tag":"Examples","count":1}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/code-first/create-ephemeral-agent","slug":"/api-reference/code-first/create-ephemeral-agent","pageMetadata":{"openapi":"post /ephemeral-agent","title":"Create ephemeral agent","description":"Creates a one-time use agent with automatic expiration. \n\n Ephemeral agents are more appropiate for use cases where you want to spin up an customized agent without persisting it long-term in the iwy dashboard. Ephemeral agents won't appear in the dashboard. The agent will automatically expire after a specified time to live (TTL).\n","href":"/api-reference/code-first/create-ephemeral-agent","hidden":false},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Creates a one-time use agent with automatic expiration.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Ephemeral agents are more appropiate for use cases where you want to spin up an customized agent without persisting it long-term in the iwy dashboard. Ephemeral agents won’t appear in the dashboard. The agent will automatically expire after a specified time to live (TTL).\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"codeStyling":"dark","config":{},"pageMetadata":{"openapi":"post /ephemeral-agent","title":"Create ephemeral agent","description":"Creates a one-time use agent with automatic expiration. \n\n Ephemeral agents are more appropiate for use cases where you want to spin up an customized agent without persisting it long-term in the iwy dashboard. Ephemeral agents won't appear in the dashboard. The agent will automatically expire after a specified time to live (TTL).\n","href":"/api-reference/code-first/create-ephemeral-agent","hidden":false}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"tags":["Ephemeral Agents"],"summary":"Create ephemeral agent","description":"Creates a one-time use agent with automatic expiration. \n\n Ephemeral agents are more appropiate for use cases where you want to spin up an customized agent without persisting it long-term in the iwy dashboard. Ephemeral agents won't appear in the dashboard. The agent will automatically expire after a specified time to live (TTL).\n","operationId":"createEphemeralAgent","requestBody":"4ce64d80-b397-431e-a899-40001be6a635","responses":{"201":"1718d440-0e19-401f-9d28-4c61c76a2c7d","400":"fc8b2bcf-84a8-45af-9c1c-5fc2b67cd1e1","401":"48e7ffcc-88f4-4601-b6b2-e2fbc9a206d8","500":"4b8c7bd8-6e29-401e-8921-59d6b382b782"},"method":"post","type":"path","servers":["ec365b07-20c7-48bc-b6f6-4ed6eedfa2f7"],"security":["176ecb09-507f-472f-be15-4aa5980a65b4"],"path":"/ephemeral-agent","baseUrlOptions":["https://api.iwy.ai/v1"],"title":"Create ephemeral agent","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Request to create a one-time use ephemeral agent","required":["configuration"],"properties":{"configuration":{"type":"object","description":"Agent configuration (same as regular agents)","required":["llm","stt","tts","video"],"properties":{"llm":{"type":"object","description":"Large Language Model configuration","required":["model","provider","system_prompt","first_message"],"properties":{"model":{"type":"string","description":"LLM model name","example":"gemini-2.0-flash","isRequired":true,"uniqueKey":"configuration.llm.model","typeLabel":"string"},"provider":{"type":"string","description":"LLM provider","example":"google","isRequired":true,"uniqueKey":"configuration.llm.provider","typeLabel":"string"},"system_prompt":{"type":"string","description":"Instructions defining the agent's personality and behavior","example":"You are a helpful customer service assistant","isRequired":true,"uniqueKey":"configuration.llm.system_prompt","typeLabel":"string"},"first_message":{"type":"string","description":"Initial greeting message","example":"Hello! How can I help you today?","isRequired":true,"uniqueKey":"configuration.llm.first_message","typeLabel":"string"},"voice":{"type":"string","description":"Voice identifier for the LLM (if supported)","uniqueKey":"configuration.llm.voice","typeLabel":"string"},"custom_url":{"type":"string","description":"Custom API endpoint URL","uniqueKey":"configuration.llm.custom_url","typeLabel":"string"},"cost_per_minute":{"type":"number","format":"float","description":"Cost per minute of LLM usage","example":0.001532,"uniqueKey":"configuration.llm.cost_per_minute","typeLabel":"number\u003cfloat>"}},"isRequired":true,"uniqueKey":"configuration.llm","typeLabel":"object"},"stt":{"type":"object","description":"Speech-to-Text configuration","required":["model","provider"],"properties":{"model":{"type":"string","description":"STT model name","example":"nova-3-general","isRequired":true,"uniqueKey":"configuration.stt.model","typeLabel":"string"},"provider":{"type":"string","description":"STT provider","example":"deepgram","isRequired":true,"uniqueKey":"configuration.stt.provider","typeLabel":"string"},"cost_per_minute":{"type":"number","format":"float","description":"Cost per minute of STT usage","example":0.01,"uniqueKey":"configuration.stt.cost_per_minute","typeLabel":"number\u003cfloat>"}},"isRequired":true,"uniqueKey":"configuration.stt","typeLabel":"object"},"tts":{"type":"object","description":"Text-to-Speech configuration","required":["provider","voice_id"],"properties":{"provider":{"type":"string","description":"TTS provider","example":"elevenlabs","isRequired":true,"uniqueKey":"configuration.tts.provider","typeLabel":"string"},"voice_id":{"type":"string","description":"Voice identifier","example":"21m00Tcm4TlvDq8ikWAM","isRequired":true,"uniqueKey":"configuration.tts.voice_id","typeLabel":"string"},"cost_per_minute":{"type":"number","format":"float","description":"Cost per minute of TTS usage","example":0.03,"uniqueKey":"configuration.tts.cost_per_minute","typeLabel":"number\u003cfloat>"}},"isRequired":true,"uniqueKey":"configuration.tts","typeLabel":"object"},"video":{"type":"object","description":"Video avatar configuration","required":["provider","character_id"],"properties":{"provider":{"type":"string","description":"Video provider","example":"binary","isRequired":true,"uniqueKey":"configuration.video.provider","typeLabel":"string"},"character_id":{"type":"string","description":"Avatar character identifier","example":"0001","isRequired":true,"uniqueKey":"configuration.video.character_id","typeLabel":"string"},"cost_per_minute":{"type":"number","format":"float","description":"Cost per minute of video usage","example":0,"uniqueKey":"configuration.video.cost_per_minute","typeLabel":"number\u003cfloat>"}},"isRequired":true,"uniqueKey":"configuration.video","typeLabel":"object"},"tool_calling":{"type":"object","description":"Tool integration configuration","properties":{"selected_tool_ids":{"type":"array","description":"Array of tool IDs this agent can use","items":{"type":"string","format":"uuid","uniqueKey":"configuration.tool_calling.selected_tool_ids.items.[INDEX]","typeLabel":"string\u003cuuid>"},"example":["dcfae097-1b37-4444-bb0c-1a6abb0320fd"],"uniqueKey":"configuration.tool_calling.selected_tool_ids","typeLabel":"string\u003cuuid>[]"}},"uniqueKey":"configuration.tool_calling","typeLabel":"object"},"end_of_conversation":{"type":"object","description":"Configuration for conversation end events","properties":{"callback_url":{"type":"string","format":"uri","description":"URL to send callback when conversation ends","uniqueKey":"configuration.end_of_conversation.callback_url","typeLabel":"string\u003curi>"},"send_data_on_end":{"type":"boolean","description":"Whether to send conversation data on end","default":false,"uniqueKey":"configuration.end_of_conversation.send_data_on_end","typeLabel":"boolean"}},"uniqueKey":"configuration.end_of_conversation","typeLabel":"object"}},"isRequired":true,"uniqueKey":"configuration","typeLabel":"object"},"ttl_seconds":{"type":"integer","description":"Time-to-live in seconds. The agent will expire after this duration.","default":300,"minimum":60,"maximum":86400,"example":600,"uniqueKey":"ttl_seconds","typeLabel":"integer"},"metadata":{"type":"object","description":"Optional metadata for tracking or internal use","additionalProperties":true,"example":{"purpose":"product_demo","campaign":"summer_2025"},"uniqueKey":"metadata","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"configuration":{"llm":{"model":"gemini-2.0-flash","provider":"google","system_prompt":"You are a helpful assistant for a product demo","first_message":"Welcome to the demo! How can I help you today?"},"tts":{"provider":"elevenlabs","voice_id":"21m00Tcm4TlvDq8ikWAM"},"video":{"provider":"binary","character_id":"0001"}}},"examples":{"Example":{"title":"Example","value":{"configuration":{"llm":{"model":"gemini-2.0-flash","provider":"google","system_prompt":"You are a helpful assistant for a product demo","first_message":"Welcome to the demo! How can I help you today?"},"tts":{"provider":"elevenlabs","voice_id":"21m00Tcm4TlvDq8ikWAM"},"video":{"provider":"binary","character_id":"0001"}}}}},"exampleType":"examples"}},"exampleType":"examples"},"responses":{"1718d440-0e19-401f-9d28-4c61c76a2c7d":{"description":"Ephemeral agent created successfully","content":{"application/json":{"schema":{"type":"object","description":"Response containing the created ephemeral agent details","required":["agent"],"properties":{"agent":{"type":"object","description":"The created ephemeral agent","required":["id","expires_at","created_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the ephemeral agent. Use this ID in your frontend widget.","example":"550e8400-e29b-41d4-a716-446655440099","isRequired":true,"uniqueKey":"agent.id","typeLabel":"string\u003cuuid>"},"expires_at":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the agent will expire","example":"2025-01-15T10:30:00.000Z","isRequired":true,"uniqueKey":"agent.expires_at","typeLabel":"string\u003cdate-time>"},"created_at":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the agent was created","example":"2025-01-15T10:20:00.000Z","isRequired":true,"uniqueKey":"agent.created_at","typeLabel":"string\u003cdate-time>"}},"isRequired":true,"uniqueKey":"agent","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"agent":{"id":"550e8400-e29b-41d4-a716-446655440099","expires_at":"2025-01-15T10:30:00.000Z","created_at":"2025-01-15T10:20:00.000Z"}},"examples":{"Example":{"title":"Example","value":{"agent":{"id":"550e8400-e29b-41d4-a716-446655440099","expires_at":"2025-01-15T10:30:00.000Z","created_at":"2025-01-15T10:20:00.000Z"}}}},"exampleType":"examples"}},"exampleType":"examples"},"fc8b2bcf-84a8-45af-9c1c-5fc2b67cd1e1":{"description":"Invalid request - validation failed","content":{"application/json":{"schema":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","example":false,"isRequired":true,"uniqueKey":"success","typeLabel":"boolean"},"error":{"type":"string","description":"Error message","example":"Parameter validation failed","isRequired":true,"uniqueKey":"error","typeLabel":"string"},"details":{"oneOf":[{"type":"string","description":"Additional error details","uniqueKey":"details.oneOf.0","typeLabel":"string"},{"type":"object","description":"Additional error details","uniqueKey":"details.oneOf.1","typeLabel":"object"}],"uniqueKey":"details","typeLabel":"string | object"},"execution_time_ms":{"type":"integer","description":"Execution time before error occurred","uniqueKey":"execution_time_ms","typeLabel":"integer"}},"uniqueKey":"","typeLabel":"object"},"example":{"success":false,"error":"Bad request","details":"Missing required field: name"},"examples":{"Example":{"title":"Example","value":{"success":false,"error":"Bad request","details":"Missing required field: name"}}},"exampleType":"examples"}},"exampleType":"examples"},"48e7ffcc-88f4-4601-b6b2-e2fbc9a206d8":{"description":"Authentication failed - invalid or missing API key","content":{"application/json":{"schema":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","example":false,"isRequired":true,"uniqueKey":"success","typeLabel":"boolean"},"error":{"type":"string","description":"Error message","example":"Parameter validation failed","isRequired":true,"uniqueKey":"error","typeLabel":"string"},"details":{"oneOf":[{"type":"string","description":"Additional error details","uniqueKey":"details.oneOf.0","typeLabel":"string"},{"type":"object","description":"Additional error details","uniqueKey":"details.oneOf.1","typeLabel":"object"}],"uniqueKey":"details","typeLabel":"string | object"},"execution_time_ms":{"type":"integer","description":"Execution time before error occurred","uniqueKey":"execution_time_ms","typeLabel":"integer"}},"uniqueKey":"","typeLabel":"object"},"example":{"success":false,"error":"Unauthorized","details":"Invalid or missing API key"},"examples":{"Example":{"title":"Example","value":{"success":false,"error":"Unauthorized","details":"Invalid or missing API key"}}},"exampleType":"examples"}},"exampleType":"examples"},"4b8c7bd8-6e29-401e-8921-59d6b382b782":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","example":false,"isRequired":true,"uniqueKey":"success","typeLabel":"boolean"},"error":{"type":"string","description":"Error message","example":"Parameter validation failed","isRequired":true,"uniqueKey":"error","typeLabel":"string"},"details":{"oneOf":[{"type":"string","description":"Additional error details","uniqueKey":"details.oneOf.0","typeLabel":"string"},{"type":"object","description":"Additional error details","uniqueKey":"details.oneOf.1","typeLabel":"object"}],"uniqueKey":"details","typeLabel":"string | object"},"execution_time_ms":{"type":"integer","description":"Execution time before error occurred","uniqueKey":"execution_time_ms","typeLabel":"integer"}},"uniqueKey":"","typeLabel":"object"},"example":{"success":false,"error":"Internal server error","details":"An unexpected error occurred"},"examples":{"Example":{"title":"Example","value":{"success":false,"error":"Internal server error","details":"An unexpected error occurred"}}},"exampleType":"examples"}},"exampleType":"examples"}},"security":{"176ecb09-507f-472f-be15-4aa5980a65b4":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Your iwy Service API Key. Find it at [app.iwy.ai/settings](https://app.iwy.ai/settings).\n\nInclude it in the Authorization header:\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n","scopes":[]}}},"servers":{"ec365b07-20c7-48bc-b6f6-4ed6eedfa2f7":{"url":"https://api.iwy.ai/v1","description":"Production server"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Your iwy Service API Key. Find it at [app.iwy.ai/settings](https://app.iwy.ai/settings).\n\nInclude it in the Authorization header:\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n","scopes":[]},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"Your iwy Service API Key. Find it at [app.iwy.ai/settings](https://app.iwy.ai/settings).\n\nInclude it in the Authorization header:\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"bearerAuth","name":"Authorization"}],"title":"bearerAuth"}]},"originalFileLocation":"api-reference/openapi.json"},"subdomain":"iwy","siteName":"iwy.ai Documentation","title":"Create ephemeral agent - iwy.ai Documentation","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-01-27T14:46:14.442Z","originalFileLocation":"api-reference/code-first/create-ephemeral-agent.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Creates a one-time use agent with automatic expiration. Ephemeral agents are more appropiate for use cases where you want to spin up an customized agent without persisting it long-term in the iwy dashboard. Ephemeral agents won\u0026#x27;t appear in the dashboard. The agent will automatically expire after a specified time to live (TTL).\">\u003cmeta data-mint-head name=\"application-name\" content=\"iwy.ai Documentation\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/iwy/dzp0S6E4dNydtu5G/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/iwy/dzp0S6E4dNydtu5G/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/iwy/dzp0S6E4dNydtu5G/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/iwy/dzp0S6E4dNydtu5G/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/iwy/dzp0S6E4dNydtu5G/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/iwy/dzp0S6E4dNydtu5G/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/iwy/dzp0S6E4dNydtu5G/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/iwy/dzp0S6E4dNydtu5G/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/iwy/dzp0S6E4dNydtu5G/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Create ephemeral agent - iwy.ai Documentation\">\u003cmeta data-mint-head property=\"og:description\" content=\"Creates a one-time use agent with automatic expiration. Ephemeral agents are more appropiate for use cases where you want to spin up an customized agent without persisting it long-term in the iwy dashboard. Ephemeral agents won\u0026#x27;t appear in the dashboard. The agent will automatically expire after a specified time to live (TTL).\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"iwy.ai Documentation\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.iwy.ai/api-reference/code-first/create-ephemeral-agent\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://iwy.mintlify.app/_mintlify/api/og/v2?division=Single-Use+Agents\u0026amp;title=Create+ephemeral+agent\u0026amp;description=Creates+a+one-time+use+agent+with+automatic+expiration.+%0A%0A+Ephemeral+agents+are+more+appropiate+for+use+cases+where+you+want+to+spin+up+an+customized+agent+with\u0026amp;theme=44bc1d1355f9460d40fa2ecc\u0026amp;signature=33a76c79ff3573c5977d9646c84d2798c3ba981c79b08fccf58bef2962bde10f\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Create ephemeral agent - iwy.ai Documentation\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Creates a one-time use agent with automatic expiration. Ephemeral agents are more appropiate for use cases where you want to spin up an customized agent without persisting it long-term in the iwy dashboard. Ephemeral agents won\u0026#x27;t appear in the dashboard. The agent will automatically expire after a specified time to live (TTL).\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://iwy.mintlify.app/_mintlify/api/og/v2?division=Single-Use+Agents\u0026amp;title=Create+ephemeral+agent\u0026amp;description=Creates+a+one-time+use+agent+with+automatic+expiration.+%0A%0A+Ephemeral+agents+are+more+appropiate+for+use+cases+where+you+want+to+spin+up+an+customized+agent+with\u0026amp;theme=44bc1d1355f9460d40fa2ecc\u0026amp;signature=33a76c79ff3573c5977d9646c84d2798c3ba981c79b08fccf58bef2962bde10f\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/iwy/dzp0S6E4dNydtu5G/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"iwy.ai Documentation\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#300040\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.iwy.ai/api-reference/code-first/create-ephemeral-agent\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/code-first/create-ephemeral-agent.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.iwy.ai/#organization\",\"name\":\"iwy.ai Documentation\",\"url\":\"https://docs.iwy.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/iwy/G25hY7NOv8_8zjPz/logo/light.svg?fit=max\u0026auto=format\u0026n=G25hY7NOv8_8zjPz\u0026q=85\u0026s=90364bd7576f99beaec49d7b01a6b375\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.iwy.ai#website\",\"name\":\"iwy.ai Documentation\",\"url\":\"https://docs.iwy.ai\",\"publisher\":{\"@id\":\"https://docs.iwy.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.iwy.ai/api-reference/code-first/create-ephemeral-agent#webpage\",\"url\":\"https://docs.iwy.ai/api-reference/code-first/create-ephemeral-agent\",\"name\":\"Create ephemeral agent\",\"description\":\"Creates a one-time use agent with automatic expiration. Ephemeral agents are more appropiate for use cases where you want to spin up an customized agent without persisting it long-term in the iwy dashboard. Ephemeral agents won't appear in the dashboard. The agent will automatically expire after a specified time to live (TTL).\",\"dateModified\":\"2026-01-27T14:46:14.442Z\",\"isPartOf\":{\"@id\":\"https://docs.iwy.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.iwy.ai/api-reference/code-first/create-ephemeral-agent#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.iwy.ai/api-reference/code-first/create-ephemeral-agent#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Single-Use Agents\",\"item\":\"https://docs.iwy.ai/api-reference/code-first/overview\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Create ephemeral agent\",\"item\":\"https://docs.iwy.ai/api-reference/code-first/create-ephemeral-agent\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.iwy.ai/api-reference/code-first/create-ephemeral-agent#apireference\",\"headline\":\"Create ephemeral agent\",\"name\":\"Create ephemeral agent\",\"description\":\"Creates a one-time use agent with automatic expiration. Ephemeral agents are more appropiate for use cases where you want to spin up an customized agent without persisting it long-term in the iwy dashboard. Ephemeral agents won't appear in the dashboard. The agent will automatically expire after a specified time to live (TTL).\",\"url\":\"https://docs.iwy.ai/api-reference/code-first/create-ephemeral-agent\",\"mainEntityOfPage\":{\"@id\":\"https://docs.iwy.ai/api-reference/code-first/create-ephemeral-agent#webpage\"},\"dateModified\":\"2026-01-27T14:46:14.442Z\",\"publisher\":{\"@id\":\"https://docs.iwy.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.iwy.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"iwy.ai Documentation\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"iwy.ai Documentation","nav":{"global":{"anchors":[{"anchor":"Homepage","icon":"house","href":"https://www.iwy.ai"},{"anchor":"Dashboard","icon":"gear","href":"https://app.iwy.ai"},{"anchor":"GitHub","icon":"github","href":"https://github.com/iwy-ai"}]},"tabs":[{"tab":"Overview","pages":[{"title":"Overview","href":""}]},{"tab":"Examples","pages":[{"title":"Examples","href":"/examples/common-use-cases"}]},{"tab":"Connect \u0026 Embed","pages":[{"title":"Connect \u0026 Embed","href":"/connect-embed"}]},{"tab":"API Reference","groups":[{"group":"API Reference","pages":[{"title":"API Reference","href":"/api-reference/api-reference"}]},{"group":"Single-Use Agents","pages":[{"title":"Single-Use Agents","description":"Create agents that activate once and then expire","href":"/api-reference/code-first/overview"},{"openapi":"post /ephemeral-agent","title":"Create ephemeral agent","href":"/api-reference/code-first/create-ephemeral-agent"}]},{"group":"Permanent Agents","pages":[{"title":"Permanent Agents","description":"Create reusable agents manageable via the iwy dashboard","href":"/api-reference/dashboard/overview"},{"openapi":"get /agent","title":"List all agents","href":"/api-reference/dashboard/agents/list-all-agents"},{"openapi":"post /agent","title":"Create a new agent","href":"/api-reference/dashboard/agents/create-a-new-agent"},{"openapi":"get /agent/{id}","title":"Get agent by ID","href":"/api-reference/dashboard/agents/get-agent-by-id"},{"openapi":"patch /agent/{id}","title":"Update agent configuration","href":"/api-reference/dashboard/agents/update-agent-configuration"},{"openapi":"delete /agent/{id}","title":"Delete agent","href":"/api-reference/dashboard/agents/delete-agent"}]},{"group":"Tools","pages":[{"title":"Tools","href":"/api-reference/dashboard/tools/overview"},{"openapi":"get /tool","title":"List all tools","href":"/api-reference/dashboard/tools/list-all-tools"},{"openapi":"post /tool","title":"Create a new tool","href":"/api-reference/dashboard/tools/create-a-new-tool"},{"openapi":"get /tool/{id}","title":"Get tool by ID","href":"/api-reference/dashboard/tools/get-tool-by-id"},{"openapi":"patch /tool/{id}","title":"Update tool configuration","href":"/api-reference/dashboard/tools/update-tool-configuration"},{"openapi":"delete /tool/{id}","title":"Delete tool","href":"/api-reference/dashboard/tools/delete-tool"},{"openapi":"post /tool/{id}/test","title":"Test tool execution","href":"/api-reference/dashboard/tools/test-tool-execution"}]},{"group":"Sessions","pages":[{"title":"Sessions \u0026 Deployment","href":"/api-reference/dashboard/sessions/overview"},{"openapi":"post /start-agent-session","title":"Start agent session","href":"/api-reference/dashboard/sessions/start-agent-session"}]}]}]},"basePath":"","title":"Create ephemeral agent - iwy.ai Documentation","buildId":"dpl_DeHjVRGfFnhYQwHnfC2pjeXXv8h9","deploymentId":"dpl_DeHjVRGfFnhYQwHnfC2pjeXXv8h9","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-CS552b7R.js","utils-DDTCYAF2.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-De8ttokP.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-DrwRDvAh.js","snippetPresets-DtAN0nWx.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-D5rWArI6.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-O2i12wsz.js","shallow-DV8xABTt.js","getApiPlaygroundDisplay-DBZ0B5Jx.js","CodeSnippet-BVi0tPUX.js","CodeSnippets-CqASbIwY.js","Page-m07pfKpT.js","getPastedJson-DG9vsMS8.js","icon-CXzRSCr8.js","MethodPill-BdKVtEuX.js","DuplicateIcon-CZlmBrJI.js","createIcon-biFEUKPL.js","DynamicMarkdown-B54_zNBF.js","SectionHeading-DwwHK3Pt.js","axios-vUo_bRtp.js","Markdown-DfhCTwyA.js","clsx-xpJZXxdP.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-BTZUMDnx.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-DqdKa2R4.js"]}