@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Deepgram API Specification
@base https://api.deepgram.com
@version 1.0.0
@auth ApiKey Authorization in header | Bearer bearer
@endpoints 39
@hint download_for_search
@toc agent(1), auth(1), listen(1), models(2), projects(32), read(1), speak(1)

@group agent
@endpoint GET /v1/agent/settings/think/models
@returns(200) {models: [any]}
@errors {400}

@endgroup

@group auth
@endpoint POST /v1/auth/grant
@optional {ttl_seconds: num}
@returns(200) {access_token: str, expires_in: num}
@errors {400}

@endgroup

@group listen
@endpoint POST /v1/listen
@required {url: str(uri)}
@optional {callback: str, callback_method: any(POST/PUT)=POST, extra: any, sentiment: bool=false, summarize: any, tag: any, topics: bool=false, custom_topic: any, custom_topic_mode: str(extended/strict)=extended, intents: bool=false, custom_intent: any, custom_intent_mode: str(extended/strict)=extended, detect_entities: bool=false, detect_language: any, diarize: bool=false, dictation: bool=false, encoding: str(linear16/flac/mulaw/amr-nb/amr-wb/opus/speex/g729), filler_words: bool=false, keyterm: [str], keywords: any, language: str=en, measurements: bool=false, model: any=base-general, multichannel: bool=false, numerals: bool=false, paragraphs: bool=false, profanity_filter: bool=false, punctuate: bool=false, redact: any=false, replace: any, search: any, smart_format: bool=false, utterances: bool=false, utt_split: num=0.8, version: any=latest, mip_opt_out: bool=false}
@returns(200)
@errors {400}

@endgroup

@group models
@endpoint GET /v1/models
@optional {include_outdated: bool}
@returns(200) {stt: [map], tts: [map]}
@errors {400}

@endpoint GET /v1/models/{model_id}
@returns(200)
@errors {400}

@endgroup

@group projects
@endpoint GET /v1/projects
@returns(200) {projects: [map]}
@errors {400}

@endpoint GET /v1/projects/{project_id}
@optional {limit: num=10, page: num}
@returns(200) {project_id: str, mip_opt_out: bool, name: str}
@errors {400}

@endpoint PATCH /v1/projects/{project_id}
@optional {name: str}
@returns(200) {message: str}
@errors {400}

@endpoint DELETE /v1/projects/{project_id}
@returns(200) {message: str}
@errors {400}

@endpoint GET /v1/projects/{project_id}/balances
@returns(200) {balances: [map]}
@errors {400}

@endpoint GET /v1/projects/{project_id}/balances/{balance_id}
@returns(200) {balance_id: str, amount: num, units: str, purchase_order_id: str}
@errors {400}

@endpoint GET /v1/projects/{project_id}/billing/breakdown
@optional {start: str(date), end: str(date), accessor: str, deployment: str(hosted/beta/self-hosted), tag: str, line_item: str, grouping: [str]}
@returns(200) {start: str(date), end: str(date), resolution: map{units: str, amount: num}, results: [map]}
@errors {400}

@endpoint GET /v1/projects/{project_id}/billing/fields
@optional {start: str(date), end: str(date)}
@returns(200) {accessors: [str(uuid)], deployments: [str], tags: [str], line_items: map}
@errors {400}

@endpoint GET /v1/projects/{project_id}/invites
@returns(200) {invites: [map]}
@errors {400}

@endpoint POST /v1/projects/{project_id}/invites
@required {email: str, scope: str}
@returns(200) {message: str}
@errors {400}

@endpoint DELETE /v1/projects/{project_id}/invites/{email}
@returns(200) {message: str}
@errors {400}

@endpoint GET /v1/projects/{project_id}/keys
@optional {status: str(active/expired)}
@returns(200) {api_keys: [map]}
@errors {400}

@endpoint POST /v1/projects/{project_id}/keys
@required {comment: str, scopes: [str]}
@optional {tags: [str], expiration_date: str(date-time), time_to_live_in_seconds: num}
@returns(200) {api_key_id: str, key: str, comment: str, scopes: [str], tags: [str], expiration_date: str(date-time)}
@errors {400}

@endpoint GET /v1/projects/{project_id}/keys/{key_id}
@returns(200) {item: map{member: map{member_id: str, email: str, first_name: str, last_name: str, api_key: map{api_key_id: str, comment: str, scopes: [str], tags: [str], expiration_date: str(date-time), created: str(date-time)}}}}
@errors {400}

@endpoint DELETE /v1/projects/{project_id}/keys/{key_id}
@returns(200) {message: str}
@errors {400}

@endpoint DELETE /v1/projects/{project_id}/leave
@returns(200) {message: str}
@errors {400}

@endpoint GET /v1/projects/{project_id}/members
@returns(200) {members: [map]}
@errors {400}

@endpoint DELETE /v1/projects/{project_id}/members/{member_id}
@returns(200) {message: str}
@errors {400}

@endpoint GET /v1/projects/{project_id}/members/{member_id}/scopes
@returns(200) {scopes: [str]}
@errors {400}

@endpoint PUT /v1/projects/{project_id}/members/{member_id}/scopes
@required {scope: str}
@returns(200) {message: str}
@errors {400}

@endpoint GET /v1/projects/{project_id}/models
@optional {include_outdated: bool}
@returns(200) {stt: [map], tts: [map]}
@errors {400}

@endpoint GET /v1/projects/{project_id}/models/{model_id}
@returns(200)
@errors {400}

@endpoint GET /v1/projects/{project_id}/purchases
@optional {limit: num=10}
@returns(200) {orders: [map]}
@errors {400}

@endpoint GET /v1/projects/{project_id}/requests
@optional {start: str(date-time), end: str(date-time), limit: num=10, page: num, accessor: str, request_id: str, deployment: str(hosted/beta/self-hosted), endpoint: str(listen/read/speak/agent), method: str(sync/async/streaming), status: str(succeeded/failed)}
@returns(200) {page: num, limit: num, requests: [map]}
@errors {400}

@endpoint GET /v1/projects/{project_id}/requests/{request_id}
@returns(200) {request: map{request_id: str, project_uuid: str, created: str(date-time), path: str, api_key_id: str, response: map, code: num, deployment: str, callback: str}}
@errors {400}

@endpoint GET /v1/projects/{project_id}/self-hosted/distribution/credentials
@returns(200) {distribution_credentials: [map]}
@errors {400}

@endpoint POST /v1/projects/{project_id}/self-hosted/distribution/credentials
@optional {scopes: [str]=self-hosted:products, provider: str=quay, comment: str}
@returns(200) {member: map{member_id: str(uuid), email: str(email)}, distribution_credentials: map{distribution_credentials_id: str(uuid), provider: str, comment: str, scopes: [str], created: str(date-time)}}
@errors {400}

@endpoint GET /v1/projects/{project_id}/self-hosted/distribution/credentials/{distribution_credentials_id}
@returns(200) {member: map{member_id: str(uuid), email: str(email)}, distribution_credentials: map{distribution_credentials_id: str(uuid), provider: str, comment: str, scopes: [str], created: str(date-time)}}
@errors {400}

@endpoint DELETE /v1/projects/{project_id}/self-hosted/distribution/credentials/{distribution_credentials_id}
@returns(200) {member: map{member_id: str(uuid), email: str(email)}, distribution_credentials: map{distribution_credentials_id: str(uuid), provider: str, comment: str, scopes: [str], created: str(date-time)}}
@errors {400}

@endpoint GET /v1/projects/{project_id}/usage
@optional {start: str(date), end: str(date), accessor: str, alternatives: bool, callback_method: bool, callback: bool, channels: bool, custom_intent_mode: bool, custom_intent: bool, custom_topic_mode: bool, custom_topic: bool, deployment: str(hosted/beta/self-hosted), detect_entities: bool, detect_language: bool, diarize: bool, dictation: bool, encoding: bool, endpoint: str(listen/read/speak/agent), extra: bool, filler_words: bool, intents: bool, keyterm: bool, keywords: bool, language: bool, measurements: bool, method: str(sync/async/streaming), model: str, multichannel: bool, numerals: bool, paragraphs: bool, profanity_filter: bool, punctuate: bool, redact: bool, replace: bool, sample_rate: bool, search: bool, sentiment: bool, smart_format: bool, summarize: bool, tag: str, topics: bool, utt_split: bool, utterances: bool, version: bool}
@returns(200) {start: str(date), end: str(date), resolution: map{units: str, amount: num}}
@errors {400}

@endpoint GET /v1/projects/{project_id}/usage/breakdown
@optional {start: str(date), end: str(date), grouping: str(accessor/endpoint/feature_set/models/method/tags/deployment), accessor: str, alternatives: bool, callback_method: bool, callback: bool, channels: bool, custom_intent_mode: bool, custom_intent: bool, custom_topic_mode: bool, custom_topic: bool, deployment: str(hosted/beta/self-hosted), detect_entities: bool, detect_language: bool, diarize: bool, dictation: bool, encoding: bool, endpoint: str(listen/read/speak/agent), extra: bool, filler_words: bool, intents: bool, keyterm: bool, keywords: bool, language: bool, measurements: bool, method: str(sync/async/streaming), model: str, multichannel: bool, numerals: bool, paragraphs: bool, profanity_filter: bool, punctuate: bool, redact: bool, replace: bool, sample_rate: bool, search: bool, sentiment: bool, smart_format: bool, summarize: bool, tag: str, topics: bool, utt_split: bool, utterances: bool, version: bool}
@returns(200) {start: str(date), end: str(date), resolution: map{units: str, amount: num}, results: [map]}
@errors {400}

@endpoint GET /v1/projects/{project_id}/usage/fields
@optional {start: str(date), end: str(date)}
@returns(200) {tags: [str], models: [map], processing_methods: [str], features: [str]}
@errors {400}

@endgroup

@group read
@endpoint POST /v1/read
@optional {callback: str, callback_method: any(POST/PUT)=POST, sentiment: bool=false, summarize: any, tag: any, topics: bool=false, custom_topic: any, custom_topic_mode: str(extended/strict)=extended, intents: bool=false, custom_intent: any, custom_intent_mode: str(extended/strict)=extended, language: str=en}
@returns(200) {metadata: map{metadata: map{request_id: str(uuid), created: str(date-time), language: str, summary_info: map{model_uuid: str(uuid), input_tokens: num, output_tokens: num}, sentiment_info: map{model_uuid: str(uuid), input_tokens: num, output_tokens: num}, topics_info: map{model_uuid: str(uuid), input_tokens: num, output_tokens: num}, intents_info: map{model_uuid: str(uuid), input_tokens: num, output_tokens: num}}}, results: map{summary: map{results: map{summary: map}}, topics: map{results: map{topics: map}}, intents: map{results: map{intents: map}}, sentiments: map{segments: [map], average: map{sentiment: str, sentiment_score: num}}}}
@errors {400}

@endgroup

@group speak
@endpoint POST /v1/speak
@required {text: str}
@optional {callback: str, callback_method: any(POST/PUT)=POST, mip_opt_out: bool=false, tag: any, bit_rate: any=48000, container: any=wav, encoding: any=mp3, model: str(aura-asteria-en/aura-luna-en/aura-stella-en/aura-athena-en/aura-hera-en/aura-orion-en/aura-arcas-en/aura-perseus-en/aura-angus-en/aura-orpheus-en/aura-helios-en/aura-zeus-en/aura-2-amalthea-en/aura-2-andromeda-en/aura-2-apollo-en/aura-2-arcas-en/aura-2-aries-en/aura-2-asteria-en/aura-2-athena-en/aura-2-atlas-en/aura-2-aurora-en/aura-2-callista-en/aura-2-cordelia-en/aura-2-cora-en/aura-2-delia-en/aura-2-draco-en/aura-2-electra-en/aura-2-harmonia-en/aura-2-helena-en/aura-2-hera-en/aura-2-hermes-en/aura-2-hyperion-en/aura-2-iris-en/aura-2-janus-en/aura-2-juno-en/aura-2-jupiter-en/aura-2-luna-en/aura-2-mars-en/aura-2-minerva-en/aura-2-neptune-en/aura-2-odysseus-en/aura-2-ophelia-en/aura-2-orion-en/aura-2-orpheus-en/aura-2-pandora-en/aura-2-phoebe-en/aura-2-pluto-en/aura-2-saturn-en/aura-2-selene-en/aura-2-thalia-en/aura-2-theia-en/aura-2-vesta-en/aura-2-zeus-en/aura-2-sirio-es/aura-2-nestor-es/aura-2-carina-es/aura-2-celeste-es/aura-2-alvaro-es/aura-2-diana-es/aura-2-aquila-es/aura-2-selena-es/aura-2-estrella-es/aura-2-javier-es)=aura-asteria-en, sample_rate: any=24000}
@returns(200)
@errors {400}

@endgroup

@end