> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getdial.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getdial.ai/_mcp/server.

# Apply a Self-Hosted state transition

POST https://api.getdial.ai/api/v1/self-hosted
Content-Type: application/json

Applies **one** Self-Hosted state transition, discriminated by `action`: `save` a mode's config (no on/off or active-mode change), `activate` a mode (enable Self-Hosted and route calls through it — enable or switch), or `disable`. Each mode (`llm`/`audio`) has its own independent config.

The signing secret for a mode is minted the first time you `save` a `wsUrl` for it. Retrieve it from `GET /api/v1/self-hosted/secret?mode=…` and set up your server's `X-Dial-Signature` verification *before* you `activate` (activating routes your calls at the server immediately). Returns the full configuration after the change.

Reference: https://docs.getdial.ai/api-reference/rest-api/self-hosted/apply-self-hosted-action

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: rest
  version: 1.0.0
paths:
  /api/v1/self-hosted:
    post:
      operationId: apply-self-hosted-action
      summary: Apply a Self-Hosted state transition
      description: >-
        Applies **one** Self-Hosted state transition, discriminated by `action`:
        `save` a mode's config (no on/off or active-mode change), `activate` a
        mode (enable Self-Hosted and route calls through it — enable or switch),
        or `disable`. Each mode (`llm`/`audio`) has its own independent config.


        The signing secret for a mode is minted the first time you `save` a
        `wsUrl` for it. Retrieve it from `GET /api/v1/self-hosted/secret?mode=…`
        and set up your server's `X-Dial-Signature` verification *before* you
        `activate` (activating routes your calls at the server immediately).
        Returns the full configuration after the change.
      tags:
        - selfHosted
      parameters:
        - name: Authorization
          in: header
          description: 'Your Dial API key, sent as `Authorization: Bearer sk_live_...`'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The full configuration after the change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SelfHostedConfig'
        '400':
          description: The request body failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SelfHostedAction'
servers:
  - url: https://api.getdial.ai
    description: Dial REST API
components:
  schemas:
    SelfHostedSaveActionAction:
      type: string
      enum:
        - save
      title: SelfHostedSaveActionAction
    SelfHostedLlmConfigInputType:
      type: string
      enum:
        - llm
      title: SelfHostedLlmConfigInputType
    SelfHostedAudioConfigInputType:
      type: string
      enum:
        - audio
      title: SelfHostedAudioConfigInputType
    SelfHostedAudioFormat:
      type: string
      enum:
        - mulaw_8000
        - alaw_8000
        - l16_8000
        - l16_16000
        - l16_24000
      description: >-
        An audio-pipe format: G.711 μ-law/A-law at 8 kHz, or 16-bit
        little-endian linear PCM at 8/16/24 kHz. Defaults to `mulaw_8000`.
      title: SelfHostedAudioFormat
    SelfHostedConfigInput:
      oneOf:
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/SelfHostedLlmConfigInputType'
            wsUrl:
              type: string
              format: uri
              description: The `wss://` URL Dial connects to for each call.
          required:
            - type
            - wsUrl
          description: llm variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/SelfHostedAudioConfigInputType'
            wsUrl:
              type: string
              format: uri
              description: The `wss://` URL Dial connects to for each call.
            audioInboundFormat:
              $ref: '#/components/schemas/SelfHostedAudioFormat'
            audioOutboundFormat:
              $ref: '#/components/schemas/SelfHostedAudioFormat'
          required:
            - type
            - wsUrl
          description: audio variant
      discriminator:
        propertyName: type
      description: A mode's config, tagged by `type` (the mode).
      title: SelfHostedConfigInput
    SelfHostedActivateActionAction:
      type: string
      enum:
        - activate
      title: SelfHostedActivateActionAction
    SelfHostedDisableActionAction:
      type: string
      enum:
        - disable
      title: SelfHostedDisableActionAction
    SelfHostedAction:
      oneOf:
        - type: object
          properties:
            action:
              $ref: '#/components/schemas/SelfHostedSaveActionAction'
            config:
              $ref: '#/components/schemas/SelfHostedConfigInput'
          required:
            - action
            - config
          description: >-
            Persist a mode's config. Does **not** change which mode is active or
            whether Self-Hosted is on. The signing secret (and, for `llm`, the
            `urlKey`) is minted the first time a mode is saved.
        - type: object
          properties:
            action:
              $ref: '#/components/schemas/SelfHostedActivateActionAction'
            config:
              $ref: '#/components/schemas/SelfHostedConfigInput'
          required:
            - action
            - config
          description: >-
            A `save` (same `config` body) that **also** enables Self-Hosted and
            routes calls through `config.type` — enable, or switch from the
            other mode. Affects new calls only.
        - type: object
          properties:
            action:
              $ref: '#/components/schemas/SelfHostedDisableActionAction'
          required:
            - action
          description: Turn Self-Hosted off. Both modes' configs are kept.
      discriminator:
        propertyName: action
      description: >-
        One Self-Hosted state transition, tagged by `action`: `save` (persist a
        mode's config), `activate` (a `save` that also enables/switches to that
        mode), or `disable` (turn off).
      title: SelfHostedAction
    SelfHostedConfigActiveMode:
      type: string
      enum:
        - llm
        - audio
      description: >-
        Which mode drives calls when `enabled`: `"llm"` (Dial runs voice; your
        server drives the conversation in text) or `"audio"` (Dial pipes the raw
        call audio to your server, full duplex).
      title: SelfHostedConfigActiveMode
    SelfHostedLlmConfigType:
      type: string
      enum:
        - llm
      title: SelfHostedLlmConfigType
    SelfHostedLlmConfig:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/SelfHostedLlmConfigType'
        wsUrl:
          type: string
          format: uri
          description: The `wss://` URL of the server Dial connects to for each call.
        urlKey:
          type: string
          description: >-
            The unguessable per-account path segment Dial uses when connecting.
            Stable once the URL is first set.
        secretMasked:
          type: string
          description: >-
            A masked preview of the signing secret (`shs_••••••••<last4>`). Copy
            the full value from `GET /api/v1/self-hosted/secret?mode=llm`.
      required:
        - type
        - wsUrl
        - urlKey
        - secretMasked
      description: >-
        The LLM variant — Dial handles telephony, speech-to-text, and
        text-to-speech; your server answers with the agent's text turns over the
        Self-hosted LLM protocol.
      title: SelfHostedLlmConfig
    SelfHostedAudioConfigType:
      type: string
      enum:
        - audio
      title: SelfHostedAudioConfigType
    SelfHostedAudioConfig:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/SelfHostedAudioConfigType'
        wsUrl:
          type: string
          format: uri
          description: The `wss://` URL of the server Dial connects to for each call.
        secretMasked:
          type: string
          description: >-
            A masked preview of the signing secret (`shs_••••••••<last4>`). Copy
            the full value from `GET /api/v1/self-hosted/secret?mode=audio`.
        audioInboundFormat:
          $ref: '#/components/schemas/SelfHostedAudioFormat'
        audioOutboundFormat:
          $ref: '#/components/schemas/SelfHostedAudioFormat'
      required:
        - type
        - wsUrl
        - secretMasked
        - audioInboundFormat
        - audioOutboundFormat
      description: >-
        The audio variant — Dial pipes the raw call audio to your server, full
        duplex, over the Self-hosted audio protocol. Your server brings the
        entire voice stack.
      title: SelfHostedAudioConfig
    SelfHostedConfig:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether Self-Hosted mode is currently driving the account's calls.
        activeMode:
          $ref: '#/components/schemas/SelfHostedConfigActiveMode'
          description: >-
            Which mode drives calls when `enabled`: `"llm"` (Dial runs voice;
            your server drives the conversation in text) or `"audio"` (Dial
            pipes the raw call audio to your server, full duplex).
        llm:
          oneOf:
            - $ref: '#/components/schemas/SelfHostedLlmConfig'
            - type: 'null'
          description: The LLM-mode config, or `null` until that mode is configured.
        audio:
          oneOf:
            - $ref: '#/components/schemas/SelfHostedAudioConfig'
            - type: 'null'
          description: The audio-mode config, or `null` until that mode is configured.
      required:
        - enabled
        - activeMode
      description: >-
        The account's Self-Hosted configuration. Each mode owns an
        **independent** config (`llm` and `audio`), both readable at once;
        `activeMode` is which one drives calls when `enabled`.
      title: SelfHostedConfig
    ErrorError:
      oneOf:
        - type: string
        - type: object
          additionalProperties:
            description: Any type
      description: An error message, or a validation-error object for 400 responses.
      title: ErrorError
    Error:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorError'
          description: An error message, or a validation-error object for 400 responses.
      title: Error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your Dial API key, sent as `Authorization: Bearer sk_live_...`'

```

## Examples



**Request**

```json
{
  "action": "save",
  "config": {
    "type": "llm",
    "wsUrl": "wss://llm.example.com/call"
  }
}
```

**Response**

```json
{
  "enabled": true,
  "activeMode": "llm",
  "llm": {
    "type": "llm",
    "wsUrl": "wss://llm.example.com/call",
    "urlKey": "a1b2c3d4e5f6g7h8",
    "secretMasked": "shs_••••••••9f4a"
  },
  "audio": {
    "type": "audio",
    "wsUrl": "wss://audio.example.com/stream",
    "secretMasked": "shs_••••••••7d3c",
    "audioInboundFormat": "mulaw_8000",
    "audioOutboundFormat": "mulaw_8000"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.getdial.ai/api/v1/self-hosted"

payload = {
    "action": "save",
    "config": {
        "type": "llm",
        "wsUrl": "wss://llm.example.com/call"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.getdial.ai/api/v1/self-hosted';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"action":"save","config":{"type":"llm","wsUrl":"wss://llm.example.com/call"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getdial.ai/api/v1/self-hosted"

	payload := strings.NewReader("{\n  \"action\": \"save\",\n  \"config\": {\n    \"type\": \"llm\",\n    \"wsUrl\": \"wss://llm.example.com/call\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.getdial.ai/api/v1/self-hosted")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"action\": \"save\",\n  \"config\": {\n    \"type\": \"llm\",\n    \"wsUrl\": \"wss://llm.example.com/call\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.getdial.ai/api/v1/self-hosted")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"action\": \"save\",\n  \"config\": {\n    \"type\": \"llm\",\n    \"wsUrl\": \"wss://llm.example.com/call\"\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.getdial.ai/api/v1/self-hosted', [
  'body' => '{
  "action": "save",
  "config": {
    "type": "llm",
    "wsUrl": "wss://llm.example.com/call"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.getdial.ai/api/v1/self-hosted");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"action\": \"save\",\n  \"config\": {\n    \"type\": \"llm\",\n    \"wsUrl\": \"wss://llm.example.com/call\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "action": "save",
  "config": [
    "type": "llm",
    "wsUrl": "wss://llm.example.com/call"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.getdial.ai/api/v1/self-hosted")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```