> ## Documentation Index > Fetch the complete documentation index at: https://docs.kupe.in/llms.txt > Use this file to discover all available pages before exploring further. # Create Agent ## OpenAPI ````yaml /openapi.yaml post /v1/orgs/{org_id}/projects/{project_id}/agents openapi: 3.1.0 info: title: Kupe API version: 0.1.0 description: >- Public Kupe REST API. Authenticate with `Authorization: Bearer sk-kupe-...` (project API key) or a Supabase user JWT. API-key callers can GET /v1/me for the org_id and project_id scoped to the key. servers: - url: https://x.kupe.in description: Production security: - BearerAuth: [] tags: - name: Me description: Current principal — org and project scoped to an API key. - name: Agents description: Agent CRUD, versions, tools, analyses, memories, and tests. - name: Realtime description: Mint an ephemeral Realtime session for the WebSocket. - name: Sessions description: LiveKit web sessions and telephony call sessions. - name: Inbound description: Bind an agent to a phone number with availability windows. - name: Campaigns description: 'Outbound batches: contacts, schedule, start/pause/resume.' - name: Recipient lists description: Reusable contact lists that attach to campaigns. - name: Tools description: Org tool catalog (webhooks, MCP, Composio-backed). - name: Composio description: Connect third-party apps and attach actions as tools. - name: Analyses description: Post-call analysis configs and session results. - name: Databases description: Call databases, rows, export, and agent attachments. - name: Knowledge bases description: Files and RAG search for agent context. - name: Audio assets description: Ambient audio presets and project uploads. - name: Phones description: Search, buy, and manage telephony numbers. - name: Voices description: Catalog voices, clones, preview, and speak. - name: Providers description: STT, LLM, and TTS catalog (defaults + enabled models). - name: Logs description: Session transcripts, recordings, and tool-call events. - name: Billing description: Wallet balance and invoices (not checkout). - name: Usage description: Cost summary and daily usage (no per-service breakdown). - name: Orgs description: Organizations. - name: Projects description: Projects inside an org. - name: Members description: Org membership. - name: API keys description: Project API keys (`sk-kupe-...`). - name: Feature flags description: Workspace feature flags. - name: Health description: Liveness and readiness probes. paths: /v1/orgs/{org_id}/projects/{project_id}/agents: post: tags: - Agents summary: Create Agent operationId: create_agent_v1_orgs__org_id__projects__project_id__agents_post parameters: - name: org_id in: path required: true schema: type: string title: Org Id - name: project_id in: path required: true schema: type: string title: Project Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentBody' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AgentOut' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: AgentBody: properties: name: type: string title: Name system_prompt: type: string title: System Prompt greeting: anyOf: - type: string - type: 'null' title: Greeting llm_id: anyOf: - type: string - type: 'null' title: Llm Id stt_id: anyOf: - type: string - type: 'null' title: Stt Id tts_id: anyOf: - type: string - type: 'null' title: Tts Id tts_voice_id: anyOf: - type: string - type: 'null' title: Tts Voice Id config: $ref: '#/components/schemas/AgentConfig' flow_definition: $ref: '#/components/schemas/FlowDefinition' type: object required: - name - system_prompt title: AgentBody AgentOut: properties: id: type: string title: Id org_id: type: string title: Org Id project_id: type: string title: Project Id name: type: string title: Name system_prompt: type: string title: System Prompt greeting: anyOf: - type: string - type: 'null' title: Greeting llm_id: type: string title: Llm Id stt_id: type: string title: Stt Id tts_id: type: string title: Tts Id tts_voice_id: anyOf: - type: string - type: 'null' title: Tts Voice Id config: additionalProperties: true type: object title: Config flow_definition: additionalProperties: true type: object title: Flow Definition version: type: integer title: Version created_at: type: string title: Created At updated_at: type: string title: Updated At archived_at: anyOf: - type: string - type: 'null' title: Archived At auto_database_id: anyOf: - type: string - type: 'null' title: Auto Database Id type: object required: - id - org_id - project_id - name - system_prompt - greeting - llm_id - stt_id - tts_id - tts_voice_id - config - version - created_at - updated_at title: AgentOut HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AgentConfig: properties: timezone: anyOf: - type: string - type: 'null' title: Timezone llm: $ref: '#/components/schemas/LlmConfig' tts: $ref: '#/components/schemas/TtsConfig' session: $ref: '#/components/schemas/SessionConfig' turn: $ref: '#/components/schemas/TurnConfig' audio: $ref: '#/components/schemas/AudioConfig' end_of_call_warning: $ref: '#/components/schemas/EndOfCallWarningConfig' silence_breaker: $ref: '#/components/schemas/SilenceBreakerConfig' thinking_sounds: $ref: '#/components/schemas/ThinkingSoundsConfig' voicemail_detection: $ref: '#/components/schemas/VoicemailDetectionConfig' auto_cut: $ref: '#/components/schemas/AutoCutConfig' call_transfer: $ref: '#/components/schemas/CallTransferConfig' memory: $ref: '#/components/schemas/MemoryConfig' dynamic_greeting: $ref: '#/components/schemas/DynamicGreetingConfig' variables: items: $ref: '#/components/schemas/PromptVariable' type: array title: Variables call_goal: anyOf: - $ref: '#/components/schemas/CallGoalConfig' - type: 'null' resolved_ambient: anyOf: - $ref: '#/components/schemas/ResolvedAmbient' - type: 'null' knowledge_base_ids: items: type: string type: array title: Knowledge Base Ids type: object title: AgentConfig FlowDefinition: properties: initial_node: type: string title: Initial Node default: start nodes: additionalProperties: $ref: '#/components/schemas/FlowNode' type: object title: Nodes type: object title: FlowDefinition ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError LlmConfig: properties: temperature: type: number title: Temperature default: 0.5 max_tokens: type: integer title: Max Tokens default: 1024 language: type: string title: Language default: hi allowed_languages: items: type: string type: array title: Allowed Languages multilingual_enabled: type: boolean title: Multilingual Enabled default: true auto_detect_language: type: boolean title: Auto Detect Language default: true output_numbers_indic: type: boolean title: Output Numbers Indic default: false switch_after_seconds: anyOf: - type: integer - type: 'null' title: Switch After Seconds type: object title: LlmConfig TtsConfig: properties: speaking_speed: type: number title: Speaking Speed description: >- Speech rate multiplier. Cartesia 0.6–1.5, ElevenLabs 0.7–1.2, Soniox/Kupe 0.7–1.3, OpenAI 0.25–4. default: 1 pitch: type: number title: Pitch description: Pitch offset (−5…5). Deepgram and Sarvam bulbul v2 only. default: 0 loudness: type: number title: Loudness description: Sarvam bulbul v2 loudness (0.3–3). default: 1 volume: type: number title: Volume description: Cartesia generation volume (0.5–2). default: 1 stability: type: number title: Stability description: ElevenLabs stability (0–1). default: 0.5 similarity_boost: type: number title: Similarity Boost description: ElevenLabs similarity (0–1). default: 0.75 style: type: number title: Style description: ElevenLabs style exaggeration (0–1). default: 0 speaker_boost: type: boolean title: Speaker Boost description: ElevenLabs speaker boost. default: true temperature: type: number title: Temperature description: >- Sarvam bulbul v3 voice temperature (0.01–1). Distinct from config.llm.temperature. default: 0.6 emotion: anyOf: - type: string - type: 'null' title: Emotion description: >- Cartesia emotion (neutral, happy, excited, content, calm, sad, angry, …). type: object title: TtsConfig description: >- Per-TTS speaking knobs. PATCH config.tts; only the selected model honors the fields listed on GET /v1/providers → tts_providers[].capabilities.speaking. SessionConfig: properties: max_duration_seconds: type: integer title: Max Duration Seconds default: 180 allow_interruptions: type: boolean title: Allow Interruptions default: true record_calls: type: boolean title: Record Calls default: true type: object title: SessionConfig TurnConfig: properties: vad_stop_secs: type: number title: Vad Stop Secs default: 0.2 eagerness: type: integer title: Eagerness default: 5 volume_threshold_db: type: number title: Volume Threshold Db default: -30 type: object title: TurnConfig AudioConfig: properties: noise_cancellation: type: string enum: - 'off' - low - medium - high title: Noise Cancellation default: medium background_noise: $ref: '#/components/schemas/BackgroundNoiseConfig' type: object title: AudioConfig EndOfCallWarningConfig: properties: enabled: type: boolean title: Enabled default: false warn_before_seconds: type: integer title: Warn Before Seconds default: 30 mode: type: string enum: - simple - session_aware title: Mode default: simple simple_message: type: string title: Simple Message default: This call will end in {remaining_seconds} seconds. session_aware_template: type: string title: Session Aware Template default: >- Just a heads up — we have about {remaining_seconds} seconds left in this {duration_seconds}-second call with {agent_name}. type: object title: EndOfCallWarningConfig SilenceBreakerConfig: properties: enabled: type: boolean title: Enabled default: false idle_seconds: type: number title: Idle Seconds default: 8 messages: items: $ref: '#/components/schemas/SilenceBreakerMessage' type: array title: Messages hangup_after_unanswered: type: boolean title: Hangup After Unanswered default: false type: object title: SilenceBreakerConfig ThinkingSoundsConfig: properties: mode: type: string enum: - 'off' - sounds - words - auto title: Mode default: auto enabled: type: boolean title: Enabled default: true type: object title: ThinkingSoundsConfig description: >- Short language-specific filler spoken via TTS as soon as the user turn ends, while the real reply is still generating. `mode` picks the vocabulary: "off" — say nothing. "sounds" — non-lexical hesitation (hmm, अं, ம்ம்). "words" — a real acknowledgement in the agent's language (अच्छा / ठीक है / બરાબર / சரி / "got it"). "auto" — the ThinkSpark model picks a context-aware spark on CPU from the caller's last turn + recent conversation, in the right language/script/register/emotion. When "auto" is selected the agent's own LLM is instructed NOT to produce reactions/fillers (ThinkSpark speaks them), and ThinkSpark's latency is reported to PostHog. This is the default for new agents. `enabled` is the pre-`mode` boolean. It is kept in the payload and mirrors `mode != "off"` so older clients and running workers keep working; new writers should send `mode`. VoicemailDetectionConfig: properties: enabled: type: boolean title: Enabled default: true message: type: string title: Message default: Sorry we missed you. Please call us back when you can. response_delay: type: number title: Response Delay default: 2 type: object title: VoicemailDetectionConfig description: >- Outbound AMD: classify the callee as human vs voicemail, leave a message, then hang up. Default on, and only wired for *outbound* telephony sessions -- an inbound caller dialled us, so there is nothing to classify. AutoCutConfig: properties: enabled: type: boolean title: Enabled default: false mode: type: string enum: - warm - instant title: Mode default: warm type: object title: AutoCutConfig description: >- Server-side `end_call` tool the LLM can invoke to hang up. Default off. `mode` controls what happens to the agent's speech at hangup: "warm" lets the closing line finish playing first, "instant" cuts the line as soon as the tool fires (and tells the agent not to say goodbye at all). CallTransferConfig: properties: enabled: type: boolean title: Enabled default: false destinations: items: $ref: '#/components/schemas/TransferDestination' type: array title: Destinations type: object title: CallTransferConfig MemoryConfig: properties: enabled: type: boolean title: Enabled default: true retention_days: type: integer title: Retention Days default: 30 max_calls: type: integer title: Max Calls default: 5 scope: type: string enum: - agent - project title: Scope default: agent type: object title: MemoryConfig description: |- Persistent per-caller memory. On by default. When enabled, every completed call is summarized after hangup (see app/tasks/memory_tasks.py) and stored against the caller's phone number. The next call from that number loads the most recent `max_calls` summaries into the agent's system prompt, so the agent can pick up where it left off instead of meeting the caller cold every time. DynamicGreetingConfig: properties: enabled: type: boolean title: Enabled default: false instructions: type: string title: Instructions default: '' type: object title: DynamicGreetingConfig description: |- The session LLM speaks first instead of the stored `greeting`. When enabled, joining a call runs the agent's own LLM with `instructions` as the first prompt (or "start the conversation" when that is empty). The reply is spoken through the normal TTS path. The stored `greeting` is ignored for that call. PromptVariable: properties: key: type: string title: Key description: type: string title: Description default: '' example: type: string title: Example default: '' type: object required: - key title: PromptVariable description: |- Named placeholder usable in prompt/greeting/flow, e.g. `{{first_name}}`. `example` doubles as the fallback value applied whenever a call doesn't supply an explicit override (see sessions_service.create_session / create_batch_session). CallGoalConfig: properties: output_field: type: string title: Output Field field_operator: type: string enum: - eq - neq - in - not_in - gt title: Field Operator value: type: string title: Value type: object required: - output_field - field_operator - value title: CallGoalConfig description: |- Scores every call on one output-variable field extracted by the agent's attached post-call-analysis. `output_field` is an AnalysisField.name (see app/schemas/post_call_analyses.py) -- resolved against the analysis result at read time, not stored redundantly here. ResolvedAmbient: properties: kind: type: string enum: - preset - url title: Kind key: anyOf: - type: string - type: 'null' title: Key url: anyOf: - type: string - type: 'null' title: Url volume: type: number title: Volume default: 0.25 type: object required: - kind title: ResolvedAmbient description: Runtime-only ambient resolution attached when dispatching a job. FlowNode: properties: name: type: string title: Name role_message: anyOf: - type: string - type: 'null' title: Role Message task_messages: items: $ref: '#/components/schemas/FlowTaskMessage' type: array title: Task Messages functions: items: $ref: '#/components/schemas/FlowNodeFunction' type: array title: Functions respond_immediately: type: boolean title: Respond Immediately default: true position: anyOf: - additionalProperties: type: number type: object - type: 'null' title: Position type: object required: - name title: FlowNode BackgroundNoiseConfig: properties: enabled: type: boolean title: Enabled default: false source: type: string enum: - preset - asset title: Source default: preset id: type: string title: Id default: office volume: type: number title: Volume default: 0.25 type: object title: BackgroundNoiseConfig SilenceBreakerMessage: properties: text: type: string title: Text default: Are you still there? after_seconds: type: number title: After Seconds default: 10 type: object title: SilenceBreakerMessage TransferDestination: properties: id: type: string title: Id name: type: string title: Name description: type: string title: Description description: >- When to transfer: the situation in which the agent should pick this destination. default: '' ring_strategy: type: string enum: - simultaneous - sequential title: Ring Strategy default: sequential ring_timeout_seconds: type: integer title: Ring Timeout Seconds default: 20 numbers: items: $ref: '#/components/schemas/TransferNumber' type: array title: Numbers transfer_message: type: string title: Transfer Message default: One moment, I'm transferring you now. no_answer_message: type: string title: No Answer Message description: >- Deprecated and unused. After transfer the agent has left; unanswered dials hang up. default: '' type: object required: - name title: TransferDestination FlowTaskMessage: properties: role: type: string title: Role default: system content: type: string title: Content type: object required: - content title: FlowTaskMessage FlowNodeFunction: properties: kind: type: string enum: - transition - tool title: Kind name: anyOf: - type: string - type: 'null' title: Name description: anyOf: - type: string - type: 'null' title: Description next_node: anyOf: - type: string - type: 'null' title: Next Node tool_id: anyOf: - type: string - type: 'null' title: Tool Id type: object required: - kind title: FlowNodeFunction TransferNumber: properties: number: type: string title: Number label: type: string title: Label default: '' type: object required: - number title: TransferNumber description: |- A single dial target within a TransferDestination. Stored as strict E.164 -- normalized by AgentsService (org context required), not here. See Global Constraints deviation note in the implementation plan. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API key description: Project API key (`sk-kupe-...`) or a Supabase user JWT. ````