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

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

@endgroup

@group projects
@endpoint POST /v1/projects/{project_id}/agents
@required {project_id: str, config: str}
@optional {metadata: map, api_version: int=1}
@returns(200) {agent_id: str, config: map, metadata: map}
@errors {400}

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

@endpoint GET /v1/projects/{project_id}/agents/{agent_id}
@required {project_id: str, agent_id: str}
@returns(200) {agent_id: str, config: map, metadata: map, created_at: str(date-time), updated_at: str(date-time)}
@errors {400}

@endpoint PUT /v1/projects/{project_id}/agents/{agent_id}
@required {project_id: str, agent_id: str, metadata: map}
@returns(200) {agent_id: str, config: map, metadata: map, created_at: str(date-time), updated_at: str(date-time)}
@errors {400}

@endpoint DELETE /v1/projects/{project_id}/agents/{agent_id}
@required {project_id: str, agent_id: str}
@returns(200)
@errors {400}

@endpoint POST /v1/projects/{project_id}/agent-variables
@required {project_id: str, key: str, value: any}
@optional {api_version: int=1}
@returns(200) {variable_id: str, key: str, value: any, created_at: str(date-time), updated_at: str(date-time)}
@errors {400}

@endpoint GET /v1/projects/{project_id}/agent-variables
@required {project_id: str}
@returns(200) {variables: [map]}
@errors {400}

@endpoint GET /v1/projects/{project_id}/agent-variables/{variable_id}
@required {project_id: str, variable_id: str}
@returns(200) {variable_id: str, key: str, value: any, created_at: str(date-time), updated_at: str(date-time)}
@errors {400}

@endpoint PATCH /v1/projects/{project_id}/agent-variables/{variable_id}
@required {project_id: str, variable_id: str, value: any}
@returns(200) {variable_id: str, key: str, value: any, created_at: str(date-time), updated_at: str(date-time)}
@errors {400}

@endpoint DELETE /v1/projects/{project_id}/agent-variables/{variable_id}
@required {project_id: str, variable_id: str}
@returns(200)
@errors {400}

@endgroup

@group listen
@endpoint POST /v1/listen
@required {url: str(uri)}
@optional {callback: str, callback_method: str=POST, extra: any, sentiment: bool=false, summarize: any, tag: any, topics: bool=false, custom_topic: any, custom_topic_mode: str=extended, intents: bool=false, custom_intent: any, custom_intent_mode: str=extended, detect_entities: bool=false, detect_language: any, diarize: bool=false, diarize_model: str, dictation: bool=false, encoding: str, 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(double)=0.8, version: any=latest, mip_opt_out: bool=false}
@returns(200)
@errors {400}

@endgroup

@group speak
@endpoint POST /v1/speak
@required {text: str}
@optional {callback: str, callback_method: str=POST, mip_opt_out: bool=false, tag: any, bit_rate: any=48000, container: any=wav, encoding: any=mp3, model: str=aura-asteria-en, sample_rate: any=24000, speed: num(double)=1}
@returns(200)
@errors {400}

@endgroup

@group read
@endpoint POST /v1/read
@optional {callback: str, callback_method: str=POST, sentiment: bool=false, summarize: any, tag: any, topics: bool=false, custom_topic: any, custom_topic_mode: str=extended, intents: bool=false, custom_intent: any, custom_intent_mode: str=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: int, output_tokens: int}, sentiment_info: map{model_uuid: str(uuid), input_tokens: int, output_tokens: int}, topics_info: map{model_uuid: str(uuid), input_tokens: int, output_tokens: int}, intents_info: map{model_uuid: str(uuid), input_tokens: int, output_tokens: int}}}, 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(double)}}}}
@errors {400}

@endgroup

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

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

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

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

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

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

@endpoint GET /v1/projects/{project_id}/models/{model_id}
@required {project_id: str, model_id: str}
@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}
@required {model_id: str}
@returns(200)
@errors {400}

@endgroup

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

@endpoint POST /v1/projects/{project_id}/keys
@required {project_id: str}
@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}
@required {project_id: str, key_id: str}
@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}
@required {project_id: str, key_id: str}
@returns(200) {message: str}
@errors {400}

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

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

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

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

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

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

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

@endpoint GET /v1/projects/{project_id}/requests
@required {project_id: str}
@optional {start: str(date-time), end: str(date-time), limit: num(double)=10, page: num(double), accessor: str, request_id: str, deployment: str, endpoint: str, method: str, status: str}
@returns(200) {page: num(double), limit: num(double), requests: [map]}
@errors {400}

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

@endpoint GET /v1/projects/{project_id}/usage
@required {project_id: str}
@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, detect_entities: bool, detect_language: bool, diarize: bool, dictation: bool, encoding: bool, endpoint: str, extra: bool, filler_words: bool, intents: bool, keyterm: bool, keywords: bool, language: bool, measurements: bool, method: str, 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(double)}}
@errors {400}

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

@endpoint GET /v1/projects/{project_id}/usage/breakdown
@required {project_id: str}
@optional {start: str(date), end: str(date), grouping: str, 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, detect_entities: bool, detect_language: bool, diarize: bool, dictation: bool, encoding: bool, endpoint: str, extra: bool, filler_words: bool, intents: bool, keyterm: bool, keywords: bool, language: bool, measurements: bool, method: str, 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(double)}, results: [map]}
@errors {400}

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

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

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

@endpoint GET /v1/projects/{project_id}/billing/fields
@required {project_id: str}
@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}/purchases
@required {project_id: str}
@optional {limit: num(double)=10}
@returns(200) {orders: [map]}
@errors {400}

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

@endpoint POST /v1/projects/{project_id}/self-hosted/distribution/credentials
@required {project_id: str}
@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}
@required {project_id: str, distribution_credentials_id: 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 DELETE /v1/projects/{project_id}/self-hosted/distribution/credentials/{distribution_credentials_id}
@required {project_id: str, distribution_credentials_id: 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}

@endgroup

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

@endgroup

@end