{"openapi":"3.1.0","info":{"title":"BluePenguin API","description":"Build and run voice agents on phone numbers you connect to BluePenguin.\n\nAuthenticate every request with a private API key from **Settings → API keys**:\n`Authorization: Bearer bp_live_…`. Keys act on one business. Limits: 240 requests per minute per key.","version":"1.0.0"},"paths":{"/assistants":{"get":{"tags":["Assistants"],"summary":"List assistants","operationId":"list_assistants_assistants_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"tags":["Assistants"],"summary":"Create an assistant","operationId":"create_assistant_assistants_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantCreate"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/assistants/{assistant_id}":{"get":{"tags":["Assistants"],"summary":"Get an assistant","operationId":"get_assistant_assistants__assistant_id__get","parameters":[{"name":"assistant_id","in":"path","required":true,"schema":{"type":"integer","title":"Assistant Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["Assistants"],"summary":"Update an assistant","operationId":"update_assistant_assistants__assistant_id__patch","parameters":[{"name":"assistant_id","in":"path","required":true,"schema":{"type":"integer","title":"Assistant Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Assistants"],"summary":"Delete an assistant","operationId":"delete_assistant_assistants__assistant_id__delete","parameters":[{"name":"assistant_id","in":"path","required":true,"schema":{"type":"integer","title":"Assistant Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/calls":{"get":{"tags":["Calls"],"summary":"List calls","operationId":"list_calls_calls_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"assistant_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Assistant Id"}},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(inbound|outbound)$"},{"type":"null"}],"title":"Direction"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Calls"],"summary":"Start an outbound call","operationId":"create_call_calls_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallCreate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/calls/{call_id}":{"get":{"tags":["Calls"],"summary":"Get a call with its transcript, analysis and metrics","operationId":"get_call_calls__call_id__get","parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"integer","title":"Call Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/phone-numbers":{"get":{"tags":["Phone numbers"],"summary":"List phone numbers","operationId":"list_numbers_phone_numbers_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/tools":{"get":{"tags":["Tools"],"summary":"List tools","operationId":"list_tools_tools_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"AdvancedCfg":{"properties":{"max_duration_s":{"type":"integer","maximum":3600.0,"minimum":30.0,"title":"Max Duration S","default":600},"silence_timeout_s":{"type":"integer","maximum":120.0,"minimum":5.0,"title":"Silence Timeout S","default":12},"idle_messages":{"items":{"type":"string"},"type":"array","maxItems":5,"title":"Idle Messages"},"idle_max":{"type":"integer","maximum":5.0,"minimum":1.0,"title":"Idle Max","default":2},"end_call_message":{"type":"string","maxLength":300,"title":"End Call Message","default":""},"end_call_phrases":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"End Call Phrases"},"recording":{"type":"boolean","title":"Recording","default":true},"recording_notice":{"type":"boolean","title":"Recording Notice","default":true},"ai_disclosure":{"type":"boolean","title":"Ai Disclosure","default":true},"waivers":{"additionalProperties":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"object"},"type":"object","title":"Waivers"},"interrupt_min_words":{"type":"integer","maximum":5.0,"minimum":1.0,"title":"Interrupt Min Words","default":1},"background":{"type":"string","enum":["off","office"],"title":"Background","default":"off"},"voicemail_detection":{"type":"boolean","title":"Voicemail Detection","default":true},"voicemail_message":{"type":"string","maxLength":600,"title":"Voicemail Message","default":""},"server_url":{"type":"string","maxLength":500,"title":"Server Url","default":""},"hipaa":{"type":"boolean","title":"Hipaa","default":false},"memory":{"type":"boolean","title":"Memory","default":true},"safety_fallback":{"type":"boolean","title":"Safety Fallback","default":true},"fillers":{"type":"boolean","title":"Fillers","default":true},"interruptions":{"type":"string","enum":["anytime","after_greeting","never"],"title":"Interruptions","default":"anytime"},"greeting_delay_ms":{"type":"integer","maximum":3000.0,"minimum":0.0,"title":"Greeting Delay Ms","default":0},"greet_after_silence_s":{"type":"integer","maximum":15.0,"minimum":0.0,"title":"Greet After Silence S","default":0},"keypad":{"type":"boolean","title":"Keypad","default":true},"redact":{"items":{"type":"string","enum":["card","ssn","email","phone","dob"]},"type":"array","maxItems":5,"title":"Redact"},"keep_days":{"type":"integer","maximum":3650.0,"minimum":0.0,"title":"Keep Days","default":0},"server_events":{"items":{"type":"string","enum":["call.started","call.transferred","call.completed"]},"type":"array","maxItems":3,"title":"Server Events"}},"type":"object","title":"AdvancedCfg"},"AnalysisCfg":{"properties":{"summary_prompt":{"type":"string","maxLength":2000,"title":"Summary Prompt","default":""},"success_rubric":{"type":"string","maxLength":2000,"title":"Success Rubric","default":""},"success_scale":{"type":"string","enum":["pass_fail","score_10","descriptive"],"title":"Success Scale","default":"score_10"},"structured":{"items":{"$ref":"#/components/schemas/StructuredField"},"type":"array","maxItems":40,"title":"Structured"}},"type":"object","title":"AnalysisCfg"},"AssistantConfig":{"properties":{"first_message_mode":{"type":"string","enum":["assistant_first","wait_for_user","model_generated"],"title":"First Message Mode","default":"assistant_first"},"first_message":{"type":"string","maxLength":1000,"title":"First Message","default":""},"system_prompt":{"type":"string","maxLength":30000,"title":"System Prompt","default":""},"business_context":{"type":"boolean","title":"Business Context","default":true},"language":{"type":"string","maxLength":16,"title":"Language","default":"en"},"mode":{"type":"string","enum":["standard","live"],"title":"Mode","default":"standard"},"live_voice":{"type":"string","title":"Live Voice","default":"marin"},"model":{"$ref":"#/components/schemas/ModelCfg"},"transcriber":{"$ref":"#/components/schemas/TranscriberCfg"},"voice":{"$ref":"#/components/schemas/VoiceCfg"},"builtin":{"$ref":"#/components/schemas/BuiltinTools"},"tool_ids":{"items":{"type":"integer"},"type":"array","maxItems":64,"title":"Tool Ids"},"knowledge_ids":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Knowledge Ids"},"analysis":{"$ref":"#/components/schemas/AnalysisCfg"},"advanced":{"$ref":"#/components/schemas/AdvancedCfg"},"variables":{"additionalProperties":{"type":"string"},"type":"object","title":"Variables"},"workflow_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Workflow Id"},"setup":{"anyOf":[{"$ref":"#/components/schemas/SimpleSetup"},{"type":"null"}]}},"type":"object","title":"AssistantConfig"},"AssistantCreate":{"properties":{"name":{"type":"string","maxLength":120,"title":"Name","default":""},"template":{"type":"string","title":"Template","description":"receptionist | scheduler | lead_qualifier | support | blank","default":"receptionist"},"config":{"anyOf":[{"$ref":"#/components/schemas/AssistantConfig"},{"type":"null"}],"description":"Full configuration; overrides the template"}},"type":"object","title":"AssistantCreate"},"AssistantUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":120,"minLength":1},{"type":"null"}],"title":"Name"},"config":{"anyOf":[{"$ref":"#/components/schemas/AssistantConfig"},{"type":"null"}]}},"type":"object","title":"AssistantUpdate"},"BuiltinTools":{"properties":{"booking":{"type":"boolean","title":"Booking","default":true},"messages":{"type":"boolean","title":"Messages","default":true},"transfer":{"type":"boolean","title":"Transfer","default":true},"sms":{"type":"boolean","title":"Sms","default":false},"payment_links":{"type":"boolean","title":"Payment Links","default":false},"knowledge":{"type":"boolean","title":"Knowledge","default":true},"end_call":{"type":"boolean","title":"End Call","default":true},"email_caller":{"type":"boolean","title":"Email Caller","default":true},"team_messages":{"type":"boolean","title":"Team Messages","default":true}},"type":"object","title":"BuiltinTools"},"CallCreate":{"properties":{"assistant_id":{"type":"integer","title":"Assistant Id"},"to":{"type":"string","title":"To","description":"The number to call, E.164 (+13125550142)"},"phone_number_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Phone Number Id","description":"Your BluePenguin number to call from; default: your first one"},"variables":{"additionalProperties":{"type":"string"},"type":"object","title":"Variables","description":"Values for {{variables}} in the prompt and first message"}},"type":"object","required":["assistant_id","to"],"title":"CallCreate"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ModelCfg":{"properties":{"provider":{"type":"string","enum":["openai","custom"],"title":"Provider","default":"openai"},"model":{"type":"string","maxLength":80,"title":"Model","default":"gpt-5.6-luna"},"temperature":{"type":"number","maximum":1.5,"minimum":0.0,"title":"Temperature","default":0.4},"max_tokens":{"type":"integer","maximum":2000.0,"minimum":40.0,"title":"Max Tokens","default":300},"custom_url":{"type":"string","maxLength":300,"title":"Custom Url","default":""},"custom_key_set":{"type":"boolean","title":"Custom Key Set","default":false},"priority":{"type":"boolean","title":"Priority","default":true},"race":{"type":"boolean","title":"Race","default":true}},"type":"object","title":"ModelCfg"},"Pronounce":{"properties":{"word":{"type":"string","maxLength":60,"minLength":1,"title":"Word"},"say":{"type":"string","maxLength":120,"minLength":1,"title":"Say"}},"type":"object","required":["word","say"],"title":"Pronounce"},"SimpleSetup":{"properties":{"role":{"type":"string","enum":["receptionist","scheduler","lead_qualifier","support"],"title":"Role","default":"receptionist"},"name":{"type":"string","maxLength":40,"title":"Name","default":""},"tone":{"type":"string","enum":["friendly","professional","relaxed"],"title":"Tone","default":"friendly"},"helps_with":{"type":"string","maxLength":1500,"title":"Helps With","default":""},"always":{"type":"string","maxLength":1500,"title":"Always","default":""},"never":{"type":"string","maxLength":1500,"title":"Never","default":""}},"type":"object","title":"SimpleSetup","description":"The plain-language form most businesses fill in instead of writing a system prompt.\n\nWhile an assistant has one, its system prompt is rebuilt from it on every save (prompt_from_setup).\nEditing the prompt by hand (Developer Mode) clears it."},"StructuredField":{"properties":{"name":{"type":"string","maxLength":60,"pattern":"^[A-Za-z_][A-Za-z0-9_]*$","title":"Name"},"type":{"type":"string","enum":["string","number","boolean","enum","date"],"title":"Type","default":"string"},"description":{"type":"string","maxLength":300,"title":"Description","default":""},"options":{"items":{"type":"string"},"type":"array","maxItems":30,"title":"Options"}},"type":"object","required":["name"],"title":"StructuredField"},"TranscriberCfg":{"properties":{"provider":{"type":"string","enum":["deepgram","openai"],"title":"Provider","default":"deepgram"},"model":{"type":"string","maxLength":60,"title":"Model","default":"flux-general-en"},"keyterms":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Keyterms"},"eot_threshold":{"type":"number","maximum":0.9,"minimum":0.5,"title":"Eot Threshold","default":0.7},"eager":{"type":"boolean","title":"Eager","default":true}},"type":"object","title":"TranscriberCfg"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VoiceCfg":{"properties":{"voice_id":{"type":"string","maxLength":80,"title":"Voice Id","default":""},"speed":{"type":"number","maximum":1.2,"minimum":0.7,"title":"Speed","default":1.0},"volume":{"type":"number","maximum":1.5,"minimum":0.5,"title":"Volume","default":1.0},"read_titles":{"type":"boolean","title":"Read Titles","default":true},"pronunciations":{"items":{"$ref":"#/components/schemas/Pronounce"},"type":"array","maxItems":100,"title":"Pronunciations"}},"type":"object","title":"VoiceCfg"}}},"servers":[{"url":"/api/v1"}]}