deepgram-python-management-api

Using Deepgram Management API (Python SDK)

Administrative REST endpoints at api.deepgram.com/v1/projects, /v1/models, and reusable agent configuration storage. Project-scoped resources live under client.manage.v1.projects.* (keys, members, members.invites, usage, billing, models, requests). Global models at client.manage.v1.models. Think-model discovery at client.agent.v1.settings.think.models. Reusable agent configs at client.voice_agent.configurations.*.

When to use this product

• Discover / pin models: client.manage.v1.models.list() returns the active STT/TTS set.
• Project admin: list/get/update/delete/leave projects.
• API key lifecycle: list/create/delete project keys.
• Member + invite management: add/remove members, manage roles, send/revoke invites.
• Usage + billing: query request volume, balances.
• Reusable Voice Agent configs: persist the agent block of a Settings message on the server, reference by agent_id. The stored blob is the agent object only (listen / think / speak providers + prompt), not the full AgentV1Settings.

Use a different skill when:

• You want to actually talk to an agent → deepgram-python-voice-agent.
• You want to transcribe or synthesize → STT/TTS skills.

Authentication

from dotenv import load_dotenv
load_dotenv()

from deepgram import DeepgramClient
client = DeepgramClient()

Header: Authorization: Token <api_key>. All methods are REST.

Quick start — projects + models

# Projects
projects = client.manage.v1.projects.list()
for p in projects.projects:
    print(p.project_id, p.name)

project = client.manage.v1.projects.get(project_id=projects.projects[0].project_id)
client.manage.v1.projects.update(project_id=project.project_id, name="New name")
# client.manage.v1.projects.delete(project_id=...)   # irreversible
# client.manage.v1.projects.leave(project_id=...)

# Models
models = client.manage.v1.models.list()
print("STT:", [m.canonical_name for m in models.stt])
print("TTS:", [m.canonical_name for m in models.tts])

# Include deprecated/outdated models
older = client.manage.v1.models.list(include_outdated=True)

# Per-project model access
project_models = client.manage.v1.projects.models.list(project_id=project.project_id)

Quick start — keys / members / invites / usage / billing

All project-scoped resources live under client.manage.v1.projects.*:

# Keys — `create` takes a single `request=` payload, not top-level kwargs
keys = client.manage.v1.projects.keys.list(project_id=pid)
client.manage.v1.projects.keys.create(
    project_id=pid,
    request={"comment": "CI key", "scopes": ["usage:write"]},
)
client.manage.v1.projects.keys.delete(project_id=pid, key_id=kid)

# Members + invites (invites are nested under members; method is `create`, not `send`)
members = client.manage.v1.projects.members.list(project_id=pid)
invites = client.manage.v1.projects.members.invites.list(project_id=pid)
client.manage.v1.projects.members.invites.create(project_id=pid, email="[email protected]", scope="member")

# Usage (get, not list) + billing balances (nested)
usage = client.manage.v1.projects.usage.get(project_id=pid)
usage_breakdown = client.manage.v1.projects.usage.breakdown.list(project_id=pid)
balance = client.manage.v1.projects.billing.balances.get(project_id=pid)

See examples/51-55 for each sub-module.

Quick start — Voice Agent configurations

# List reusable configs
configs = client.voice_agent.configurations.list(project_id=pid)

# Create: `config` is a JSON string of the `agent` BLOCK ONLY — not the full
# Settings message. Do NOT include top-level Settings fields like `audio`;
# those are sent at connect-time in the live Settings message. The stored
# `agent_id` later replaces the inline `agent` object in a Settings message.
import json
config_json = json.dumps({
    "listen": {"provider": {"type": "deepgram", "model": "nova-3"}},
    "think":  {"provider": {"type": "open_ai", "model": "gpt-4o-mini"}, "prompt": "..."},
    "speak":  {"provider": {"type": "deepgram", "model": "aura-2-asteria-en"}},
})
created = client.voice_agent.configurations.create(
    project_id=pid,
    config=config_json,
    metadata={"label": "support-en"},
)
print(created.agent_id)

# Update metadata (immutable config body — create a new one to change behavior)
client.voice_agent.configurations.update(project_id=pid, agent_id=created.agent_id, metadata={"label": "v2"})

# Get / delete
one = client.voice_agent.configurations.get(project_id=pid, agent_id=created.agent_id)
# client.voice_agent.configurations.delete(project_id=pid, agent_id=...)

Think-provider model discovery (which LLMs Agent supports):

think_models = client.agent.v1.settings.think.models.list()

Async equivalent

from deepgram import AsyncDeepgramClient
client = AsyncDeepgramClient()
projects = await client.manage.v1.projects.list()

API reference (layered)

1. In-repo reference: reference.md — "Manage V1 Projects/Keys/Members/Invites/Usage/Billing/Models", "Voice Agent Configurations".
2. OpenAPI (REST): https://developers.deepgram.com/openapi.yaml
3. Context7: library ID /llmstxt/developers_deepgram_llms_txt.
4. Product docs:
   • https://developers.deepgram.com/reference/manage/projects/list
   • https://developers.deepgram.com/reference/manage/models/list
   • https://developers.deepgram.com/reference/voice-agent/agent-configurations/list-agent-configurations
   • https://developers.deepgram.com/reference/voice-agent/agent-configurations/create-agent-configuration
   • https://developers.deepgram.com/reference/voice-agent/think-models

Gotchas

1. Token auth, not Bearer.
2. Project-scoped resources are nested under .projects.*. There is no top-level client.manage.v1.keys / .members / .invites / .usage / .billing. Use client.manage.v1.projects.keys, ...projects.members, ...projects.members.invites, ...projects.usage, ...projects.billing.balances, and ...projects.requests for request logs. The only top-level client.manage.v1.* namespaces are projects and models.
3. Think-model discovery is on the Agent client, not Manage: client.agent.v1.settings.think.models.list(). There is no client.manage.v1.agent.*.
4. Agent config body is a JSON STRING on create, not a nested object. Pass config=json.dumps(...).
5. Agent config is the agent block only, not the full Settings message. Do not include top-level fields like audio — those go in the live Settings message at connect time.
6. Agent configs are immutable — you cannot edit the config body. Create a new one to change behavior. Only metadata is mutable.
7. Use include_outdated=True on models.list() when pinning older models.
8. Delete is irreversible. Wire tests typically comment out destructive calls.
9. Project-scoped vs global models: client.manage.v1.models.list() returns all; client.manage.v1.projects.models.list(project_id=...) returns what the project can access.
10. Returned agent configs are uninterpolated — raw stored JSON string. Parse before use.

Example files in this repo

• examples/50-management-projects.py
• examples/51-management-keys.py
• examples/52-management-members.py
• examples/53-management-invites.py
• examples/54-management-usage.py
• examples/55-management-billing.py
• examples/56-management-models.py
• tests/wire/test_manage_v1_projects.py
• tests/wire/test_manage_v1_models.py
• tests/wire/test_voiceAgent_configurations.py

Related skills

• deepgram-python-voice-agent — run an agent (use a config created here)

Central product skills

For cross-language Deepgram product knowledge — the consolidated API reference, documentation finder, focused runnable recipes, third-party integration examples, and MCP setup — install the central skills:

npx skills add deepgram/skills

This SDK ships language-idiomatic code skills; deepgram/skills ships cross-language product knowledge (see api, docs, recipes, examples, starters, setup-mcp).