{"openapi":"3.1.0","info":{"title":"Dialkit API","description":"Make real phone calls with an AI agent, then retrieve status, transcripts, outcomes, and billing. Obtain a personal API token from /account. Use Authorization: Bearer <token>. Call creation has real-world effects; use an Idempotency-Key and retain it across retries.","version":"0.1.0"},"servers":[{"url":"https://app.dialkit.ai"}],"paths":{"/v1/capabilities":{"get":{"summary":"Discover supported API capabilities","operationId":"getCapabilities","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","required":["call_idempotency_version"],"properties":{"call_idempotency_version":{"type":"integer","minimum":1}}},"example":{"call_idempotency_version":1}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"tags":["Calls"],"security":[{"BearerAuth":[]}]}},"/v1/call-submissions/{submission_key}":{"get":{"summary":"Recover an idempotent call submission","operationId":"getCallSubmission","parameters":[{"name":"submission_key","in":"path","required":true,"schema":{"type":"string","title":"Submission Key","minLength":16,"maxLength":128,"pattern":"^[A-Za-z0-9_-]{16,128}$"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MakeCallResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"No stored submission for this account and key"},"409":{"description":"Submission exists but its call record is unavailable"}},"tags":["Calls"],"security":[{"BearerAuth":[]}],"description":"Recover a call ID using the same account and Idempotency-Key. 404 means no stored submission. After an uncertain POST, retry the identical request and key; never create a new key just because a lookup failed."}},"/health":{"get":{"summary":"Check service health","operationId":"getHealth","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","required":["status","active_calls","app_version"],"properties":{"status":{"type":"string"},"active_calls":{"type":"integer"},"app_version":{"type":"string"}}}}}}},"tags":["Health"],"security":[]}},"/v1/calls":{"post":{"summary":"Place a real phone call","operationId":"makeCall","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MakeCallResponse"},"example":{"call_id":"call_example","status":"queued"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Concurrent call capacity reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"400":{"description":"Caller ID or call setup rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Credit or subscription renewal required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Caller ID or plan restriction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Agent or joined call not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency key conflicts with an earlier submission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Service not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"tags":["Calls"],"security":[{"BearerAuth":[]}],"description":"Starts a real, billable outbound call. Returns acceptance, not completion. Poll getCall until terminal. Requires verified caller ID and sufficient account credit. Use a stable Idempotency-Key for each confirmed task; retry the same key and identical body after network errors. Reusing the key for a different body returns 409.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MakeCallRequest"},"example":{"to":"+14165550123","purpose":"Confirm my appointment for tomorrow at 2 pm","max_duration":300}}}},"parameters":[{"in":"header","name":"Idempotency-Key","required":false,"description":"Persist before sending. Reuse with the identical body for this task only.","schema":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[A-Za-z0-9_-]{16,128}$"}}]}},"/v1/calls/{call_id}":{"get":{"summary":"Read a call, transcript, outcome, and billing","operationId":"getCall","parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"string","title":"Call Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallResponse"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"tags":["Calls"],"security":[{"BearerAuth":[]}]}},"/v1/calls/{call_id}/dtmf":{"post":{"summary":"Send keypad tones to an active call","operationId":"sendDtmf","parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"string","title":"Call Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendDtmfRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendDtmfResponse"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Conflict"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"tags":["Calls"],"security":[{"BearerAuth":[]}]}},"/v1/calls/{call_id}/recording/info":{"get":{"summary":"Check recording availability and retrieval cost","operationId":"getRecordingInfo","parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"string","title":"Call Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","required":["call_id","storage_class","size_bytes","is_cold","retrieval_fee_usd"],"properties":{"call_id":{"type":"string"},"storage_class":{"type":"string"},"size_bytes":{"type":"integer"},"is_cold":{"type":"boolean"},"retrieval_fee_usd":{"type":"number"}}}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"tags":["Recordings"],"security":[{"BearerAuth":[]}]}},"/v1/calls/{call_id}/recording":{"get":{"summary":"Download a WAV recording; cold retrieval may charge credit","operationId":"getRecording","parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"string","title":"Call Id"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","description":"stereo or mono","default":"stereo","title":"Format"},"description":"stereo or mono"}],"responses":{"200":{"description":"Successful Response","content":{"audio/wav":{"schema":{"type":"string","format":"binary"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"tags":["Recordings"],"security":[{"BearerAuth":[]}],"description":"Returns audio/wav. Check getRecordingInfo first: downloading cold storage recordings charges the returned retrieval_fee_usd. Obtain user approval for that cost. Recording must have been enabled for the call."}}},"components":{"schemas":{"ApiError":{"type":"object","required":["detail"],"properties":{"detail":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object"}}]}}},"CallResponse":{"properties":{"call_id":{"type":"string","title":"Call Id"},"status":{"$ref":"#/components/schemas/CallStatus"},"direction":{"type":"string","title":"Direction","default":"outbound"},"from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From"},"to":{"type":"string","title":"To"},"purpose":{"type":"string","title":"Purpose"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At"},"ended_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ended At"},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds"},"outcome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Outcome"},"transcript":{"items":{"$ref":"#/components/schemas/TranscriptEntry"},"type":"array","title":"Transcript","default":[]},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"billable_minutes":{"type":"integer","title":"Billable Minutes","default":0},"billable_amount_usd":{"type":"number","title":"Billable Amount Usd","default":0.0},"bridge_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bridge Id"}},"type":"object","required":["call_id","status","to","purpose"],"title":"CallResponse"},"CallStatus":{"type":"string","enum":["queued","ringing","in_progress","completed","failed","busy","no_answer"],"title":"CallStatus"},"ErrorResponse":{"properties":{"detail":{"anyOf":[{"type":"string"},{"items":{"additionalProperties":true,"type":"object"},"type":"array"}],"title":"Detail"}},"type":"object","required":["detail"],"title":"ErrorResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"MakeCallRequest":{"properties":{"to":{"description":"Phone number in E.164 format (e.g. +14165551234)","pattern":"^\\+[1-9]\\d{1,14}$","title":"To","type":"string"},"purpose":{"description":"What the call should accomplish","maxLength":2000,"minLength":5,"title":"Purpose","type":"string"},"instructions":{"anyOf":[{"maxLength":4000,"type":"string"},{"type":"null"}],"default":null,"description":"How the AI should behave","title":"Instructions"},"voice":{"default":"auto","description":"Voice to use (auto, or specific OpenAI voice name)","title":"Voice","type":"string"},"model":{"anyOf":[{"enum":["default","openai","gemini"],"type":"string"},{"type":"null"}],"default":null,"description":"AI voice provider to use. Builder and Enterprise only; default uses the agent or global setting.","title":"Model"},"max_duration":{"default":300,"description":"Max call duration in seconds","maximum":600,"minimum":10,"title":"Max Duration","type":"integer"},"from_number":{"anyOf":[{"pattern":"^\\+[1-9]\\d{1,14}$","type":"string"},{"type":"null"}],"default":null,"description":"Caller ID in E.164 format (e.g. +14165551234)","title":"From Number"},"agent":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Agent id or name to use on this call","title":"Agent"},"language":{"anyOf":[{"maxLength":8,"type":"string"},{"type":"null"}],"default":null,"description":"ISO 639-1 language code to force on this call (e.g. 'en', 'he').","title":"Language"},"join_call":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"call_id of an active call to conference into. The new leg joins that call's bridge.","title":"Join Call"},"loop_in_to":{"anyOf":[{"pattern":"^\\+[1-9]\\d{1,14}$","type":"string"},{"type":"null"}],"default":null,"description":"E.164 phone number to use as the 'owner' escalation target, overriding the agent default.","title":"Loop In To"}},"required":["to","purpose"],"title":"MakeCallRequest","type":"object"},"MakeCallResponse":{"properties":{"call_id":{"type":"string","title":"Call Id"},"status":{"$ref":"#/components/schemas/CallStatus"}},"type":"object","required":["call_id","status"],"title":"MakeCallResponse"},"SendDtmfRequest":{"properties":{"digits":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[0-9A-Da-d*#]+$","title":"Digits"},"between_ms":{"type":"integer","maximum":5000.0,"minimum":0.0,"title":"Between Ms","description":"Gap between digits in milliseconds","default":120},"duration_ms":{"type":"integer","maximum":5000.0,"minimum":40.0,"title":"Duration Ms","description":"Tone duration per digit in milliseconds","default":250},"before_ms":{"type":"integer","maximum":10000.0,"minimum":0.0,"title":"Before Ms","description":"Delay before first digit in milliseconds","default":0},"after_ms":{"type":"integer","maximum":10000.0,"minimum":0.0,"title":"After Ms","description":"Delay after last digit in milliseconds","default":0}},"type":"object","required":["digits"],"title":"SendDtmfRequest"},"SendDtmfResponse":{"properties":{"call_id":{"type":"string","title":"Call Id"},"status":{"type":"string","title":"Status"},"digits":{"type":"string","title":"Digits"}},"type":"object","required":["call_id","status","digits"],"title":"SendDtmfResponse"},"TranscriptEntry":{"properties":{"role":{"type":"string","title":"Role"},"text":{"type":"string","title":"Text"},"ts":{"type":"number","title":"Ts"}},"type":"object","required":["role","text","ts"],"title":"TranscriptEntry"},"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"}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal API token created in /account."}}},"externalDocs":{"description":"Guides, examples, and retry rules","url":"https://app.dialkit.ai/docs"}}