Dedalus Labs Chat API
The Chat API from Dedalus Labs — 1 operation(s) for chat.
OpenAPI Specification
openapi: 3.1.0
info:
title: Dedalus Audio Chat API
description: 'MCP gateway for AI agents. Mix-and-match any model with any tool from our marketplace.
## Authentication
Use Bearer token or X-API-Key header authentication:
```
Authorization: Bearer your-api-key-here
```
```
x-api-key: your-api-key-here
```
## Available Endpoints
- **GET /v1/models**: list available models
- **POST /v1/chat/completions**: Chat completions with MCP tools
- **GET /health**: Service health check'
version: 0.0.1
servers:
- url: https://api.dedaluslabs.ai
description: Official Dedalus API
tags:
- name: Chat
paths:
/v1/chat/completions:
post:
tags:
- Chat
summary: Create Chat Completion
description: "Create a chat completion.\n\nGenerates a model response for the given conversation and configuration.\nSupports OpenAI-compatible parameters and provider-specific extensions.\n\nHeaders:\n - Authorization: bearer key for the calling account.\n - X-Provider / X-Provider-Key: optional headers for using your own provider API key.\n\nBehavior:\n - If multiple models are supplied, the first one is used, and the agent may hand off to another model.\n - Tools may be invoked on the server or signaled for the client to run.\n - Streaming responses emit incremental deltas; non-streaming returns a single object.\n - Usage metrics are computed when available and returned in the response.\n\nResponses:\n - 200 OK: JSON completion object with choices, message content, and usage.\n - 400 Bad Request: validation error.\n - 401 Unauthorized: authentication failed.\n - 402 Payment Required or 429 Too Many Requests: quota, balance, or rate limit issue.\n - 500 Internal Server Error: unexpected failure.\n\nBilling:\n - Token usage metered by the selected model(s).\n - Tool calls and MCP sessions may be billed separately.\n - Streaming is settled after the stream ends via an async task.\n\nExample (non-streaming HTTP):\n POST /v1/chat/completions\n Content-Type: application/json\n Authorization: Bearer <key>\n\n {\n \"model\": \"provider/model-name\",\n \"messages\": [{\"role\": \"user\", \"content\": \"Hello\"}]\n }\n\n 200 OK\n {\n \"id\": \"cmpl_123\",\n \"object\": \"chat.completion\",\n \"choices\": [\n {\"index\": 0, \"message\": {\"role\": \"assistant\", \"content\": \"Hi there!\"}, \"finish_reason\": \"stop\"}\n ],\n \"usage\": {\"prompt_tokens\": 3, \"completion_tokens\": 4, \"total_tokens\": 7}\n }\n\nExample (streaming over SSE):\n POST /v1/chat/completions\n Accept: text/event-stream\n\n data: {\"id\":\"cmpl_123\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"Hi\"}}]}\n data: {\"id\":\"cmpl_123\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\" there!\"}}]}\n data: [DONE]"
operationId: create_chat_completion_v1_chat_completions_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ChatCompletionRequest'
required: true
responses:
'200':
description: JSON or SSE stream of ChatCompletionChunk events
content:
application/json:
schema:
$ref: '#/components/schemas/ChatCompletion'
text/event-stream:
schema:
$ref: '#/components/schemas/ChatCompletionStreamResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- Bearer: []
x-codeSamples:
- lang: typescript
label: Typescript
source: 'const client = new Dedalus();
const result = await client.chat.completions.create({ ...params });'
- lang: python
label: Python
source: 'client = Dedalus()
result = client.chat.completions.create(**params)'
- lang: go
label: Go
source: 'client := dedalus.NewClient()
result, err := client.Chat.Completions.New(ctx, body githubcomdedaluslabsdedalussdkgo.ChatCompletionNewParams)'
components:
schemas:
ChatCompletionRequestDeveloperMessage:
properties:
content:
anyOf:
- type: string
- items:
$ref: '#/components/schemas/ChatCompletionRequestMessageContentPartText'
type: array
minItems: 1
title: ChatCompletionRequestDeveloperMessageContentArray
title: Content
description: The contents of the developer message.
x-order: 0
role:
type: string
const: developer
title: Role
description: The role of the messages author, in this case `developer`.
x-order: 1
name:
type: string
title: Name
description: An optional name for the participant. Provides the model information to differentiate between participants of the same role.
x-order: 2
type: object
required:
- content
- role
title: ChatCompletionRequestDeveloperMessage
description: 'Developer-provided instructions that the model should follow, regardless of
messages sent by the user. With o1 models and newer, `developer` messages
replace the previous `system` messages.
Fields:
- content (required): str | Annotated[list[ChatCompletionRequestMessageContentPartText], MinLen(1), ArrayTitle("ChatCompletionRequestDeveloperMessageContentArray")]
- role (required): Literal["developer"]
- name (optional): str'
CompletionUsage:
properties:
completion_tokens:
type: integer
title: Completion Tokens
description: Number of tokens in the generated completion.
x-order: 0
prompt_tokens:
type: integer
title: Prompt Tokens
description: Number of tokens in the prompt.
x-order: 1
total_tokens:
type: integer
title: Total Tokens
description: Total number of tokens used in the request (prompt + completion).
x-order: 2
completion_tokens_details:
$ref: '#/components/schemas/CompletionTokensDetails'
description: Breakdown of tokens used in a completion.
x-order: 3
prompt_tokens_details:
$ref: '#/components/schemas/PromptTokensDetails'
description: Breakdown of tokens used in the prompt.
x-order: 4
type: object
required:
- completion_tokens
- prompt_tokens
- total_tokens
title: CompletionUsage
description: 'Usage statistics for the completion request.
Fields:
- completion_tokens (required): int
- prompt_tokens (required): int
- total_tokens (required): int
- completion_tokens_details (optional): CompletionTokensDetails
- prompt_tokens_details (optional): PromptTokensDetails'
ChatCompletionRequestUserMessage:
properties:
content:
anyOf:
- type: string
- items:
oneOf:
- $ref: '#/components/schemas/ChatCompletionRequestMessageContentPartText'
- $ref: '#/components/schemas/ChatCompletionRequestMessageContentPartImage'
- $ref: '#/components/schemas/ChatCompletionRequestMessageContentPartAudio'
- $ref: '#/components/schemas/ChatCompletionRequestMessageContentPartFile'
discriminator:
propertyName: type
mapping:
file: '#/components/schemas/ChatCompletionRequestMessageContentPartFile'
image_url: '#/components/schemas/ChatCompletionRequestMessageContentPartImage'
input_audio: '#/components/schemas/ChatCompletionRequestMessageContentPartAudio'
text: '#/components/schemas/ChatCompletionRequestMessageContentPartText'
type: array
minItems: 1
title: ChatCompletionRequestUserMessageContentArray
title: Content
description: The contents of the user message.
x-order: 0
role:
type: string
const: user
title: Role
description: The role of the messages author, in this case `user`.
x-order: 1
name:
type: string
title: Name
description: An optional name for the participant. Provides the model information to differentiate between participants of the same role.
x-order: 2
type: object
required:
- content
- role
title: ChatCompletionRequestUserMessage
description: 'Messages sent by an end user, containing prompts or additional context
information.
Fields:
- content (required): str | Annotated[list[ChatCompletionRequestUserMessageContentPart], MinLen(1), ArrayTitle("ChatCompletionRequestUserMessageContentArray")]
- role (required): Literal["user"]
- name (optional): str'
ChatCompletionRequestMessageContentPartRefusal:
properties:
type:
type: string
const: refusal
title: Type
description: The type of the content part.
x-order: 0
refusal:
type: string
title: Refusal
description: The refusal message generated by the model.
x-order: 1
type: object
required:
- type
- refusal
title: ChatCompletionRequestMessageContentPartRefusal
description: 'Schema for ChatCompletionRequestMessageContentPartRefusal.
Fields:
- type (required): Literal["refusal"]
- refusal (required): str'
JSONValue:
anyOf:
- type: string
- type: integer
- type: number
- type: boolean
- additionalProperties:
$ref: '#/components/schemas/JSONValue'
type: object
- items:
$ref: '#/components/schemas/JSONValue'
type: array
- type: 'null'
Credential:
properties:
connection_name:
type: string
title: Connection Name
description: Connection name. Must match a connection in MCPServer.connections.
values:
additionalProperties:
anyOf:
- type: string
- type: integer
- type: boolean
type: object
title: Values
description: Credential values. Keys are credential field names, values are the secrets.
additionalProperties: false
type: object
required:
- connection_name
- values
title: Credential
description: 'Credential for MCP server authentication.
Passed at endpoint level (e.g., chat.completions.create) and matched
to MCP servers by connection name. Wire format matches dedalus_mcp.Credential.to_dict().'
ChatCompletionResponseMessage:
properties:
content:
anyOf:
- type: string
- type: 'null'
title: Content
description: The contents of the message.
x-order: 0
refusal:
anyOf:
- type: string
- type: 'null'
title: Refusal
description: The refusal message generated by the model.
x-order: 1
tool_calls:
items:
oneOf:
- $ref: '#/components/schemas/ChatCompletionMessageToolCall'
- $ref: '#/components/schemas/ChatCompletionMessageCustomToolCall'
discriminator:
propertyName: type
mapping:
custom: '#/components/schemas/ChatCompletionMessageCustomToolCall'
function: '#/components/schemas/ChatCompletionMessageToolCall'
type: array
title: Tool Calls
description: The tool calls generated by the model, such as function calls.
x-order: 2
annotations:
items:
properties:
type:
type: string
const: url_citation
title: Type
description: The type of the URL citation. Always `url_citation`.
x-order: 0
url_citation:
properties:
end_index:
type: integer
title: End Index
description: The index of the last character of the URL citation in the message.
x-order: 0
start_index:
type: integer
title: Start Index
description: The index of the first character of the URL citation in the message.
x-order: 1
url:
type: string
title: Url
description: The URL of the web resource.
x-order: 2
title:
type: string
title: Title
description: The title of the web resource.
x-order: 3
type: object
required:
- end_index
- start_index
- url
- title
description: 'A URL citation when using web search.
Fields:
- end_index (required): int
- start_index (required): int
- url (required): str
- title (required): str'
type: object
required:
- type
- url_citation
description: 'A URL citation when using web search.
Fields:
- type (required): Literal["url_citation"]
- url_citation (required): UrlCitation'
type: array
title: Annotations
description: 'Annotations for the message, when applicable, as when using the
[web search tool](/docs/guides/tools-web-search?api-mode=chat).'
x-order: 3
role:
type: string
const: assistant
title: Role
description: The role of the author of this message.
x-order: 4
function_call:
properties:
arguments:
type: string
title: Arguments
description: The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.
x-order: 0
name:
type: string
title: Name
description: The name of the function to call.
x-order: 1
type: object
required:
- arguments
- name
description: 'Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.
Fields:
- arguments (required): str
- name (required): str'
audio:
anyOf:
- properties:
id:
type: string
title: Id
description: Unique identifier for this audio response.
x-order: 0
expires_at:
type: integer
title: Expires At
description: 'The Unix timestamp (in seconds) for when this audio response will
no longer be accessible on the server for use in multi-turn
conversations.'
x-order: 1
data:
type: string
title: Data
description: 'Base64 encoded audio bytes generated by the model, in the format
specified in the request.'
x-order: 2
transcript:
type: string
title: Transcript
description: Transcript of the audio generated by the model.
x-order: 3
type: object
required:
- id
- expires_at
- data
- transcript
description: 'If the audio output modality is requested, this object contains data
about the audio response from the model. [Learn more](/docs/guides/audio).
Fields:
- id (required): str
- expires_at (required): int
- data (required): str
- transcript (required): str'
- type: 'null'
description: 'If the audio output modality is requested, this object contains data
about the audio response from the model. [Learn more](/docs/guides/audio).'
x-order: 6
type: object
required:
- content
- refusal
- role
title: ChatCompletionResponseMessage
description: 'A chat completion message generated by the model.
Fields:
- content (required): str | None
- refusal (required): str | None
- tool_calls (optional): ChatCompletionMessageToolCalls
- annotations (optional): list[AnnotationsItem]
- role (required): Literal["assistant"]
- function_call (optional): ChatCompletionResponseMessageFunctionCall
- audio (optional): ChatCompletionResponseMessageAudio | None'
ChatCompletionRequestMessageContentPartText:
properties:
type:
type: string
const: text
title: Type
description: The type of the content part.
x-order: 0
text:
type: string
title: Text
description: The text content.
x-order: 1
type: object
required:
- type
- text
title: ChatCompletionRequestMessageContentPartText
description: 'Learn about [text inputs](/docs/guides/text-generation).
Fields:
- type (required): Literal["text"]
- text (required): str'
JSONObject:
additionalProperties:
$ref: '#/components/schemas/JSONValue'
type: object
FunctionCall:
properties:
arguments:
type: string
title: Arguments
description: The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.
x-order: 0
name:
type: string
title: Name
description: The name of the function to call.
x-order: 1
type: object
required:
- arguments
- name
title: FunctionCall
description: 'Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.
Fields:
- arguments (required): str
- name (required): str'
x-ddls-inline: true
ChatCompletionRequestSystemMessage:
properties:
content:
anyOf:
- type: string
- items:
$ref: '#/components/schemas/ChatCompletionRequestMessageContentPartText'
type: array
minItems: 1
title: ChatCompletionRequestSystemMessageContentArray
title: Content
description: The contents of the system message.
x-order: 0
role:
type: string
const: system
title: Role
description: The role of the messages author, in this case `system`.
x-order: 1
name:
type: string
title: Name
description: An optional name for the participant. Provides the model information to differentiate between participants of the same role.
x-order: 2
type: object
required:
- content
- role
title: ChatCompletionRequestSystemMessage
description: 'Developer-provided instructions that the model should follow, regardless of
messages sent by the user. With o1 models and newer, use `developer` messages
for this purpose instead.
Fields:
- content (required): str | Annotated[list[ChatCompletionRequestSystemMessageContentPart], MinLen(1), ArrayTitle("ChatCompletionRequestSystemMessageContentArray")]
- role (required): Literal["system"]
- name (optional): str'
MCPCredentials:
items:
$ref: '#/components/schemas/Credential'
type: array
title: MCPCredentials
description: List of credentials for MCP server authentication.
x-stainless-variantName: MCPCredentials
ChatCompletionStreamResponseDelta:
description: 'A chat completion delta generated by streamed model responses.
Fields:
- content (optional): str | None
- function_call (optional): ChatCompletionStreamResponseDeltaFunctionCall
- tool_calls (optional): list[ChatCompletionMessageToolCallChunk]
- role (optional): Literal["developer", "system", "user", "assistant", "tool"]
- refusal (optional): str | None'
properties:
content:
anyOf:
- type: string
- type: 'null'
default: null
description: The contents of the chunk message.
title: Content
x-order: 0
function_call:
description: 'Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.
Fields:
- arguments (optional): str
- name (optional): str'
properties:
arguments:
default: null
description: The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.
title: Arguments
type: string
x-order: 0
name:
default: null
description: The name of the function to call.
title: Name
type: string
x-order: 1
type: object
tool_calls:
default: null
items:
$ref: '#/components/schemas/ChatCompletionMessageToolCallChunk'
title: Tool Calls
type: array
x-order: 2
role:
default: null
description: The role of the author of this message.
enum:
- developer
- system
- user
- assistant
- tool
title: Role
type: string
x-order: 3
refusal:
anyOf:
- type: string
- type: 'null'
default: null
description: The refusal message generated by the model.
title: Refusal
x-order: 4
title: ChatCompletionStreamResponseDelta
type: object
ChatCompletionMessageCustomToolCall:
properties:
id:
type: string
title: Id
description: The ID of the tool call.
x-order: 0
type:
type: string
const: custom
title: Type
description: The type of the tool. Always `custom`.
x-order: 1
custom:
properties:
name:
type: string
title: Name
description: The name of the custom tool to call.
x-order: 0
input:
type: string
title: Input
description: The input for the custom tool call generated by the model.
x-order: 1
type: object
required:
- name
- input
description: 'The custom tool that the model called.
Fields:
- name (required): str
- input (required): str'
type: object
required:
- id
- type
- custom
title: ChatCompletionMessageCustomToolCall
description: 'A call to a custom tool created by the model.
Fields:
- id (required): str
- type (required): Literal["custom"]
- custom (required): ChatCompletionMessageCustomToolCallCustom'
VoiceIdsOrCustomVoiceInline:
properties:
id:
type: string
title: Id
description: The custom voice ID, e.g. `voice_1234`.
x-order: 0
type: object
required:
- id
title: VoiceIdsOrCustomVoiceInline
description: 'Custom voice reference.
Fields:
- id (required): str'
x-ddls-inline: true
DedalusModel:
properties:
model:
type: string
title: Model
description: Model identifier with provider prefix (e.g., 'openai/gpt-5', 'anthropic/claude-3-5-sonnet').
settings:
anyOf:
- $ref: '#/components/schemas/ModelSettings'
- type: 'null'
description: Optional default generation settings (e.g., temperature, max_tokens) applied when this model is selected.
additionalProperties: false
type: object
required:
- model
title: DedalusModel
description: 'Structured model selection entry used in request payloads.
Supports OpenAI-style semantics (string model id) while enabling
optional per-model default settings for Dedalus multi-model routing.'
ChatCompletionTokenLogprob:
properties:
token:
type: string
title: Token
description: The token.
x-order: 0
logprob:
type: number
title: Logprob
description: The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.
x-order: 1
bytes:
anyOf:
- items:
type: integer
type: array
- type: 'null'
title: Bytes
description: A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.
x-order: 2
top_logprobs:
items:
properties:
token:
type: string
title: Token
description: The token.
x-order: 0
logprob:
type: number
title: Logprob
description: The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.
x-order: 1
bytes:
anyOf:
- items:
type: integer
type: array
- type: 'null'
title: Bytes
description: A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.
x-order: 2
type: object
required:
- token
- logprob
- bytes
description: Token and its log probability.
type: array
title: Top Logprobs
description: List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested `top_logprobs` returned.
x-order: 3
type: object
required:
- token
- logprob
- bytes
- top_logprobs
title: ChatCompletionTokenLogprob
description: Token log probability information.
ChatCompletionStreamResponseChoicesItemLogprobs:
description: 'Log probability information for the choice.
Fields:
- content (required): list[ChatCompletionTokenLogprob]
- refusal (required): list[ChatCompletionTokenLogprob]'
properties:
content:
anyOf:
- items:
$ref: '#/components/schemas/ChatCompletionTokenLogprob'
type: array
- type: 'null'
description: A list of message content tokens with log probability information.
title: Content
x-order: 0
refusal:
anyOf:
- items:
$ref: '#/components/schemas/ChatCompletionTokenLogprob'
type: array
- type: 'null'
description: A list of message refusal tokens with log probability information.
title: Refusal
x-order: 1
required:
- content
- refusal
title: ChatCompletionStreamResponseChoicesItemLogprobs
type: object
x-ddls-inline: true
PredictionContent:
properties:
type:
type: string
const: content
title: Type
description: 'The type of the predicted content you want to provide. This type is
currently always `content`.'
x-order: 0
content:
anyOf:
- type: string
- items:
$ref: '#/components/schemas/ChatCompletionRequestMessageContentPartText'
type: array
minItems: 1
title: PredictionContentArray
title: Content
description: 'The content that should be matched when generating a model response.
If generated tokens would match this content, the entire model response
can be returned much more quickly.'
x-order: 1
type: object
required:
- type
- content
title: PredictionContent
description: 'Static predicted output content, such as the content of a text file that is
being regenerated.
Fields:
- type (required): Literal["content"]
- content (required): str | Annotated[list[ChatCompletionRequestMessageContentPartText], MinLen(1), ArrayTitle("PredictionContentArray")]'
ChatCompletionStreamResponseChoicesItem:
description: 'Schema for ChatCompletionStreamResponseChoicesItem.
Fields:
- delta (required): ChatCompletionStreamResponseDelta
- logprobs (optional): ChatCompletionStreamResponseChoicesItemLogprobs
- finish_reason (required): Literal["stop", "length", "tool_calls", "content_filter", "function_call"]
- index (required): int'
properties:
delta:
$ref: '#/components/schemas/ChatCompletionStreamResponseDelta'
description: A chat completion delta generated by streamed model responses.
x-order: 0
logprobs:
anyOf:
- $ref: '#/components/schemas/ChatCompletionStreamResponseChoicesItemLogprobs'
- type: 'null'
default: null
description: Log probability information for the choice.
x-order: 1
finish_reason:
anyOf:
- enum:
- stop
- length
- tool_calls
- content_filter
- function_call
type: string
- type: 'null'
description: 'The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence,
`length` if the maximum number of tokens specified in the request was reached,
`content_filter` if content was omitted due to a flag from our content filters,
`tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function.'
title: Finish Reason
x-order: 2
index:
description: The index of the choice in the list of choices.
title: Index
type: integer
x-order: 3
required:
- d
# --- truncated at 32 KB (111 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dedaluslabs/refs/heads/main/openapi/dedaluslabs-chat-api-openapi.yml