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="new@example.com", 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 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)
- In-repo reference:
reference.md — "Manage V1 Projects/Keys/Members/Invites/Usage/Billing/Models", "Voice Agent Configurations".
- OpenAPI (REST): https://developers.deepgram.com/openapi.yaml
- Context7: library ID
/llmstxt/developers_deepgram_llms_txt.
- Product docs:
Gotchas
Token auth, not Bearer.
- 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.
- Think-model discovery is on the Agent client, not Manage:
client.agent.v1.settings.think.models.list(). There is no client.manage.v1.agent.*.
- Agent config body is a JSON STRING on create, not a nested object. Pass
config=json.dumps(...).
- 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.
- Agent configs are immutable — you cannot edit the config body. Create a new one to change behavior. Only metadata is mutable.
- Use
include_outdated=True on models.list() when pinning older models.
- Delete is irreversible. Wire tests typically comment out destructive calls.
- 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.
- 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).
1---2name: deepgram-python-management-api3description: Use when writing or reviewing Python code in this repo that calls Deepgram Management APIs - projects, API keys, members, invites, usage, billing, models, and reusable Voice Agent configurations. Covers `client.manage.v1.projects`, project-scoped resources under `client.manage.v1.projects.*` (keys, members, members.invites, usage, billing, models, requests), global `client.manage.v1.models`, think-model discovery at `client.agent.v1.settings.think.models`, and `client.voice_agent.configurations.*`. Use `deepgram-python-voice-agent` when you want to run an agent interactively, this skill to PERSIST/LIST agent configs. Triggers include "management API", "list projects", "API keys", "members", "usage stats", "billing", "list models", "agent configurations", "manage.v1".4metadata:5 source: https://skillmd.com/skills/deepgram/deepgram-python-management-api6---78# Using Deepgram Management API (Python SDK)910Administrative 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.*`.1112## When to use this product1314- **Discover / pin models**: `client.manage.v1.models.list()` returns the active STT/TTS set.15- **Project admin**: list/get/update/delete/leave projects.16- **API key lifecycle**: list/create/delete project keys.17- **Member + invite management**: add/remove members, manage roles, send/revoke invites.18- **Usage + billing**: query request volume, balances.19- **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`.2021**Use a different skill when:**22- You want to actually talk to an agent → `deepgram-python-voice-agent`.23- You want to transcribe or synthesize → STT/TTS skills.2425## Authentication2627```python28from dotenv import load_dotenv29load_dotenv()3031from deepgram import DeepgramClient32client = DeepgramClient()33```3435Header: `Authorization: Token <api_key>`. All methods are REST.3637## Quick start — projects + models3839```python40# Projects41projects = client.manage.v1.projects.list()42for p in projects.projects:43 print(p.project_id, p.name)4445project = client.manage.v1.projects.get(project_id=projects.projects[0].project_id)46client.manage.v1.projects.update(project_id=project.project_id, name="New name")47# client.manage.v1.projects.delete(project_id=...) # irreversible48# client.manage.v1.projects.leave(project_id=...)4950# Models51models = client.manage.v1.models.list()52print("STT:", [m.canonical_name for m in models.stt])53print("TTS:", [m.canonical_name for m in models.tts])5455# Include deprecated/outdated models56older = client.manage.v1.models.list(include_outdated=True)5758# Per-project model access59project_models = client.manage.v1.projects.models.list(project_id=project.project_id)60```6162## Quick start — keys / members / invites / usage / billing6364All project-scoped resources live under `client.manage.v1.projects.*`:6566```python67# Keys — `create` takes a single `request=` payload, not top-level kwargs68keys = client.manage.v1.projects.keys.list(project_id=pid)69client.manage.v1.projects.keys.create(70 project_id=pid,71 request={"comment": "CI key", "scopes": ["usage:write"]},72)73client.manage.v1.projects.keys.delete(project_id=pid, key_id=kid)7475# Members + invites (invites are nested under members; method is `create`, not `send`)76members = client.manage.v1.projects.members.list(project_id=pid)77invites = client.manage.v1.projects.members.invites.list(project_id=pid)78client.manage.v1.projects.members.invites.create(project_id=pid, email="new@example.com", scope="member")7980# Usage (get, not list) + billing balances (nested)81usage = client.manage.v1.projects.usage.get(project_id=pid)82usage_breakdown = client.manage.v1.projects.usage.breakdown.list(project_id=pid)83balance = client.manage.v1.projects.billing.balances.get(project_id=pid)84```8586See `examples/51-55` for each sub-module.8788## Quick start — Voice Agent configurations8990```python91# List reusable configs92configs = client.voice_agent.configurations.list(project_id=pid)9394# Create: `config` is a JSON string of the `agent` BLOCK ONLY — not the full95# Settings message. Do NOT include top-level Settings fields like `audio`;96# those are sent at connect-time in the live Settings message. The stored97# `agent_id` later replaces the inline `agent` object in a Settings message.98import json99config_json = json.dumps({100 "listen": {"provider": {"type": "deepgram", "model": "nova-3"}},101 "think": {"provider": {"type": "open_ai", "model": "gpt-4o-mini"}, "prompt": "..."},102 "speak": {"provider": {"type": "deepgram", "model": "aura-2-asteria-en"}},103})104created = client.voice_agent.configurations.create(105 project_id=pid,106 config=config_json,107 metadata={"label": "support-en"},108)109print(created.agent_id)110111# Update metadata (immutable config body — create a new one to change behavior)112client.voice_agent.configurations.update(project_id=pid, agent_id=created.agent_id, metadata={"label": "v2"})113114# Get / delete115one = client.voice_agent.configurations.get(project_id=pid, agent_id=created.agent_id)116# client.voice_agent.configurations.delete(project_id=pid, agent_id=...)117```118119Think-provider model discovery (which LLMs Agent supports):120121```python122think_models = client.agent.v1.settings.think.models.list()123```124125## Async equivalent126127```python128from deepgram import AsyncDeepgramClient129client = AsyncDeepgramClient()130projects = await client.manage.v1.projects.list()131```132133## API reference (layered)1341351. **In-repo reference**: `reference.md` — "Manage V1 Projects/Keys/Members/Invites/Usage/Billing/Models", "Voice Agent Configurations".1362. **OpenAPI (REST)**: https://developers.deepgram.com/openapi.yaml1373. **Context7**: library ID `/llmstxt/developers_deepgram_llms_txt`.1384. **Product docs**:139 - https://developers.deepgram.com/reference/manage/projects/list140 - https://developers.deepgram.com/reference/manage/models/list141 - https://developers.deepgram.com/reference/voice-agent/agent-configurations/list-agent-configurations142 - https://developers.deepgram.com/reference/voice-agent/agent-configurations/create-agent-configuration143 - https://developers.deepgram.com/reference/voice-agent/think-models144145## Gotchas1461471. **`Token` auth, not `Bearer`.**1482. **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`.1493. **Think-model discovery is on the Agent client**, not Manage: `client.agent.v1.settings.think.models.list()`. There is no `client.manage.v1.agent.*`.1504. **Agent config body is a JSON STRING on create**, not a nested object. Pass `config=json.dumps(...)`.1515. **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.1526. **Agent configs are immutable** — you cannot edit the config body. Create a new one to change behavior. Only metadata is mutable.1537. **Use `include_outdated=True`** on `models.list()` when pinning older models.1548. **Delete is irreversible.** Wire tests typically comment out destructive calls.1559. **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.15610. **Returned agent configs are uninterpolated** — raw stored JSON string. Parse before use.157158## Example files in this repo159160- `examples/50-management-projects.py`161- `examples/51-management-keys.py`162- `examples/52-management-members.py`163- `examples/53-management-invites.py`164- `examples/54-management-usage.py`165- `examples/55-management-billing.py`166- `examples/56-management-models.py`167- `tests/wire/test_manage_v1_projects.py`168- `tests/wire/test_manage_v1_models.py`169- `tests/wire/test_voiceAgent_configurations.py`170171## Related skills172173- `deepgram-python-voice-agent` — run an agent (use a config created here)174175## Central product skills176177For 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:178179```bash180npx skills add deepgram/skills181```182183This SDK ships language-idiomatic code skills; `deepgram/skills` ships cross-language product knowledge (see `api`, `docs`, `recipes`, `examples`, `starters`, `setup-mcp`).