deepgram-python-management-api - SKILL.md Agent Skill

name: deepgram-python-management-api description: 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".

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
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)

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).