API for creating and managing interactive real-time AI agents that combine digital avatar streaming with large language models, RAG-based knowledge bases, and custom tools. Supports WebRTC and LiveKit-powered streaming sessions, conversation memory, chat export, and integration with third-party LLM providers. Enables face-to-face AI conversations at scale.
openapi: 3.0.3
info:
title: D-ID Agents API
description: >
API for creating and managing interactive real-time AI agents that combine
digital avatar streaming with large language models, RAG-based knowledge
bases, and custom tools. Supports WebRTC and LiveKit-powered streaming
sessions, conversation memory, chat export, and integration with third-party
LLM providers. Enables face-to-face AI conversations at scale.
version: 1.0.0
contact:
url: https://www.d-id.com
termsOfService: https://www.d-id.com/terms-of-use/
externalDocs:
description: D-ID Agents API Reference
url: https://docs.d-id.com/reference/agents
servers:
- url: https://api.d-id.com
description: D-ID Production API
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Agents
description: Create and manage AI agent definitions
- name: Sessions
description: Manage real-time streaming sessions for agents
- name: Chat
description: Send messages and receive responses in an agent chat
- name: Knowledge
description: Manage knowledge bases and documents for RAG
- name: Client Keys
description: Manage scoped client keys for SDK embedding
paths:
/agents:
get:
operationId: listmyagents
summary: List agents
description: Retrieve all agents belonging to the authenticated user.
tags:
- Agents
responses:
'200':
description: Array of agent objects.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AgentResponseDto'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createagent
summary: Create an agent
description: >
Create a new interactive AI agent combining a digital avatar presenter,
an LLM backend, and an optional knowledge base.
tags:
- Agents
parameters:
- name: x-api-key-external
in: header
description: Optional ElevenLabs API key for TTS with IVC voices.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentCreateDto'
responses:
'200':
description: Created agent object.
content:
application/json:
schema:
$ref: '#/components/schemas/AgentResponseDto'
'401':
$ref: '#/components/responses/Unauthorized'
/agents/{id}:
get:
operationId: getagent
summary: Get an agent
description: Retrieve details of a specific agent by ID.
tags:
- Agents
security:
- basicAuth: []
- bearerAuth: []
- clientKeyAuth: []
parameters:
- $ref: '#/components/parameters/resourceId'
responses:
'200':
description: Agent object.
content:
application/json:
schema:
$ref: '#/components/schemas/AgentResponseDto'
'401':
$ref: '#/components/responses/Unauthorized'
patch:
operationId: updateagent
summary: Update an agent
description: Update configuration for an existing agent.
tags:
- Agents
parameters:
- $ref: '#/components/parameters/resourceId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentCreateDto'
responses:
'200':
description: Updated agent object.
content:
application/json:
schema:
$ref: '#/components/schemas/AgentResponseDto'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteagent
summary: Delete an agent
description: Permanently delete an agent.
tags:
- Agents
parameters:
- $ref: '#/components/parameters/resourceId'
responses:
'200':
description: Agent deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v2/agents/{agentId}/sessions:
post:
operationId: createsession
summary: Create a session
description: >
Establish a new streaming session for an Expressive Agent, returning
session credentials required to connect via WebRTC or LiveKit.
tags:
- Sessions
security:
- basicAuth: []
- bearerAuth: []
- clientKeyAuth: []
parameters:
- name: agentId
in: path
required: true
description: Agent identifier.
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/InitSessionV2Request'
responses:
'201':
description: Session created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SessionResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Agent not found.
content:
application/json:
schema:
$ref: '#/components/schemas/JsonError'
/agents/{agentId}/sessions:
get:
operationId: listsessions
summary: List sessions
description: Retrieve all sessions for a specific agent.
tags:
- Sessions
parameters:
- name: agentId
in: path
required: true
schema:
type: string
responses:
'200':
description: Array of session objects.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SessionResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/agents/{agentId}/sessions/{sessionId}:
get:
operationId: getsession
summary: Get a session
description: Retrieve details of a specific session.
tags:
- Sessions
parameters:
- name: agentId
in: path
required: true
schema:
type: string
- name: sessionId
in: path
required: true
schema:
type: string
responses:
'200':
description: Session object.
content:
application/json:
schema:
$ref: '#/components/schemas/SessionResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/agents/{agentId}/chat/{chatId}:
post:
operationId: agentchat
summary: Send a chat message
description: >
Send a message to an agent's chat and receive a response including
optional knowledge matches, video ID, and chat mode.
tags:
- Chat
security:
- basicAuth: []
- bearerAuth: []
- clientKeyAuth: []
parameters:
- name: agentId
in: path
required: true
description: Agent identifier.
schema:
type: string
- name: chatId
in: path
required: true
description: Chat identifier.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChatMessageRequest'
responses:
'200':
description: Chat response.
content:
application/json:
schema:
$ref: '#/components/schemas/ChatMessageResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/knowledge:
get:
operationId: getknowledges
summary: List knowledge bases
description: Retrieve all knowledge bases for the authenticated user.
tags:
- Knowledge
responses:
'200':
description: Array of knowledge base objects.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ILogicalKnowledge'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createknowledge
summary: Create a knowledge base
description: >
Create a new knowledge base for RAG. Each knowledge base can hold up
to 5 documents.
tags:
- Knowledge
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateKnowledgeDto'
responses:
'200':
description: Created knowledge base.
content:
application/json:
schema:
$ref: '#/components/schemas/ILogicalKnowledge'
'401':
$ref: '#/components/responses/Unauthorized'
/knowledge/{id}:
get:
operationId: getknowledge
summary: Get a knowledge base
description: Retrieve a specific knowledge base by ID.
tags:
- Knowledge
parameters:
- $ref: '#/components/parameters/resourceId'
responses:
'200':
description: Knowledge base object.
content:
application/json:
schema:
$ref: '#/components/schemas/ILogicalKnowledge'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateknowledge
summary: Update a knowledge base
tags:
- Knowledge
parameters:
- $ref: '#/components/parameters/resourceId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateKnowledgeDto'
responses:
'200':
description: Updated knowledge base.
content:
application/json:
schema:
$ref: '#/components/schemas/ILogicalKnowledge'
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteknowledge
summary: Delete a knowledge base
tags:
- Knowledge
parameters:
- $ref: '#/components/parameters/resourceId'
responses:
'200':
description: Knowledge base deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/knowledge/{knowledgeId}/documents:
get:
operationId: getdocuments
summary: List documents
description: Retrieve all documents in a knowledge base.
tags:
- Knowledge
parameters:
- name: knowledgeId
in: path
required: true
schema:
type: string
responses:
'200':
description: Array of document objects.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ILogicalKnowledge'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createdocument
summary: Create a document
description: Add a document to an existing knowledge base.
tags:
- Knowledge
parameters:
- name: knowledgeId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
type: string
source_url:
type: string
format: uri
responses:
'200':
description: Created document.
content:
application/json:
schema:
$ref: '#/components/schemas/ILogicalKnowledge'
'401':
$ref: '#/components/responses/Unauthorized'
/knowledge/{knowledgeId}/documents/{documentId}:
get:
operationId: getdocument
summary: Get a document
tags:
- Knowledge
parameters:
- name: knowledgeId
in: path
required: true
schema:
type: string
- name: documentId
in: path
required: true
schema:
type: string
responses:
'200':
description: Document object.
content:
application/json:
schema:
$ref: '#/components/schemas/ILogicalKnowledge'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deletedocument
summary: Delete a document
tags:
- Knowledge
parameters:
- name: knowledgeId
in: path
required: true
schema:
type: string
- name: documentId
in: path
required: true
schema:
type: string
responses:
'200':
description: Document deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: HTTP Basic Authentication using API key as username.
bearerAuth:
type: http
scheme: bearer
description: Bearer token authentication.
clientKeyAuth:
type: apiKey
in: header
name: Authorization
description: Scoped client key for SDK embedding.
parameters:
resourceId:
name: id
in: path
required: true
description: Unique resource identifier.
schema:
type: string
responses:
BadRequest:
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/JsonError'
Unauthorized:
description: Authentication failure.
content:
application/json:
schema:
$ref: '#/components/schemas/JsonError'
example:
kind: AuthorizationError
description: user unauthenticated
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/JsonError'
schemas:
JsonError:
type: object
properties:
kind:
type: string
example: AuthorizationError
description:
type: string
example: user unauthenticated
PresenterConfig:
type: object
description: >
Avatar presenter configuration. Supports Talk (V2 photo avatar),
Clip (V3 personal avatar), or Expressive (V4) presenter types.
properties:
type:
type: string
enum:
- talk
- clip
- expressive
source_url:
type: string
format: uri
description: Image URL for talk-type presenters.
presenter_id:
type: string
description: Presenter ID for clip or expressive types.
voice:
type: object
properties:
type:
type: string
voice_id:
type: string
LLMConfig:
type: object
description: Language model configuration.
properties:
provider:
type: string
enum:
- openai
- google
- d-id
- custom
- external
description: LLM provider.
model:
type: string
description: Model identifier.
instructions:
type: string
description: System prompt / persona instructions.
template:
type: string
description: Response formatting template.
AgentCreateDto:
type: object
required:
- presenter
properties:
presenter:
$ref: '#/components/schemas/PresenterConfig'
preview_name:
type: string
description: Agent display name.
preview_description:
type: string
description: Agent description.
llm:
$ref: '#/components/schemas/LLMConfig'
knowledge:
type: object
properties:
id:
type: string
description: Knowledge base ID for RAG.
starter_message:
type: array
items:
type: string
description: Suggested conversation starters.
greetings:
type: array
items:
type: string
description: Greeting messages (randomly selected per session).
user_data:
type: string
description: Custom user data (1–1,000 characters).
minLength: 1
maxLength: 1000
embed:
type: boolean
description: Enable SDK/website embedding.
triggers:
type: object
description: Event-based configurations (webhooks, tools).
AgentResponseDto:
type: object
properties:
id:
type: string
description: Agent identifier.
preview_description:
type: string
presenter:
$ref: '#/components/schemas/PresenterConfig'
llm:
$ref: '#/components/schemas/LLMConfig'
knowledge:
type: object
properties:
id:
type: string
starter_message:
type: array
items:
type: string
greetings:
type: array
items:
type: string
provider:
type: string
example: d-id-agents
error:
type: object
description: Error details if applicable.
triggers:
type: object
client_key:
type: string
description: Auto-generated scoped client key.
metadata:
type: object
description: Plan information.
embed:
type: boolean
InitSessionV2Request:
type: object
properties:
chat_persist:
type: boolean
description: Whether to persist the chat history across sessions.
default: false
SessionResponse:
type: object
properties:
id:
type: string
description: Session identifier.
session_url:
type: string
format: uri
description: URL for connecting to the session stream.
session_token:
type: string
description: Authentication token for the session.
interrupt_enabled:
type: boolean
description: Whether interrupt (barge-in) is enabled.
ChatMessage:
type: object
properties:
role:
type: string
enum:
- user
- assistant
- system
content:
type: string
created_at:
type: string
format: date-time
ChatMessageRequest:
type: object
required:
- messages
properties:
messages:
type: array
items:
$ref: '#/components/schemas/ChatMessage'
description: Conversation messages. Must contain at least one message.
streamId:
type: string
description: Optional stream ID to link video response.
sessionId:
type: string
description: Optional session ID for WebRTC stream.
chatMode:
type: string
enum:
- Functional
- TextOnly
- Maintenance
- Playground
description: Chat operating mode (Playground deprecated).
KnowledgeMatch:
type: object
properties:
id:
type: string
data:
type: string
title:
type: string
document_id:
type: string
knowledge_id:
type: string
source_url:
type: string
format: uri
ChatMessageResponse:
type: object
properties:
matches:
type: array
items:
$ref: '#/components/schemas/KnowledgeMatch'
description: Relevant knowledge base matches.
documentIds:
type: array
items:
type: string
result:
type: string
description: Text response from the agent.
chatMode:
type: string
videoId:
type: string
description: ID of the generated avatar video response.
CreateKnowledgeDto:
type: object
required:
- name
- description
properties:
name:
type: string
description: Knowledge base identifier name.
description:
type: string
description: Description of the knowledge base content.
starter_message:
type: array
items:
type: string
description: Suggested chat starters (deprecated; prefer agent.starter_messages).
ILogicalKnowledge:
type: object
properties:
id:
type: string
description: Knowledge / document identifier.
type:
type: string
enum:
- knowledge
- document
- record
name:
type: string
description:
type: string
owner_id:
type: string
created_by:
type: string
status:
type: string
created_at:
type: string
format: date-time
modified_at:
type: string
format: date-time