> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# SWMLService

> SWML document generation and FastAPI service base class.

[agentbase]: /docs/server-sdks/reference/python/agents/agent-base

[swml]: /docs/swml/reference/ai

[swml-reference]: /docs/swml/reference/ai

[configloader]: /docs/server-sdks/reference/python/agents/configuration/config-loader

[addsection]: /docs/server-sdks/reference/python/agents/swml-service/add-section

[addverb]: /docs/server-sdks/reference/python/agents/swml-service/add-verb

[addverbtosection]: /docs/server-sdks/reference/python/agents/swml-service/add-verb-to-section

[asrouter]: /docs/server-sdks/reference/python/agents/swml-service/as-router

[getbasicauthcredentials]: /docs/server-sdks/reference/python/agents/swml-service/get-basic-auth-credentials

[getdocument]: /docs/server-sdks/reference/python/agents/swml-service/get-document

[manualsetproxyurl]: /docs/server-sdks/reference/python/agents/swml-service/manual-set-proxy-url

[onrequest]: /docs/server-sdks/reference/python/agents/swml-service/on-request

[extractsipusername]: /docs/server-sdks/reference/python/agents/swml-service/register-routing-callback

[registerroutingcallback]: /docs/server-sdks/reference/python/agents/swml-service/register-routing-callback

[registerverbhandler]: /docs/server-sdks/reference/python/agents/swml-service/register-verb-handler

[renderdocument]: /docs/server-sdks/reference/python/agents/swml-service/render-document

[resetdocument]: /docs/server-sdks/reference/python/agents/swml-service/reset-document

[serve]: /docs/server-sdks/reference/python/agents/swml-service/serve

[stop]: /docs/server-sdks/reference/python/agents/swml-service/stop

SWMLService is the foundation class for creating and serving SWML (SignalWire Markup
Language) documents. It provides SWML document generation with schema validation,
a built-in FastAPI web server for serving documents over HTTP, and basic authentication
for securing endpoints. Most developers will use
[`AgentBase`][agentbase] (which extends SWMLService)
rather than working with SWMLService directly. Use SWMLService when you need
low-level control over SWML document construction without the AI agent abstractions.

[`AgentBase`][agentbase] extends SWMLService — it
inherits all document generation, serving, and authentication capabilities documented here.

> **Info**
>
> SWMLService generates and serves [SWML][swml] documents over HTTP.
> See the [SWML reference][swml-reference] for the full document specification.

> **Note**
>
> SWMLService also hosts SWAIG tools directly. It owns a tool registry (via `ToolMixin`)
> and serves a `/swaig` endpoint, so SWAIG functions can be registered and dispatched
> without subclassing [`AgentBase`][agentbase]. The tool-registration and dispatch methods
> (for example `define_tool` and `on_function_call`) are documented under
> [`AgentBase`][agentbase], which inherits them.

## **Properties**

**`name`** `str`

Service name/identifier used in logging and server startup messages.

---

**`route`** `str`

HTTP route path where this service is accessible. Trailing slashes are stripped
automatically during initialization.

---

**`host`** `str`

Host address the web server binds to.

---

**`port`** `int`

Port number the web server binds to.

---

**`schema_utils`** `SchemaUtils`

Schema validation utilities for SWML documents. Provides verb validation,
verb name enumeration, and schema property lookups.

---

**`verb_registry`** `VerbHandlerRegistry`

Registry of specialized verb handlers. Manages custom handlers for complex SWML
verbs that require logic beyond generic schema validation (e.g., the `ai` verb).

---

**`log`** `Logger`

Structured logger instance bound to this service name.

---

**`security`** `SecurityConfig`

Unified security configuration loaded from environment variables and optional
config file. Controls SSL, CORS, and host allowlist settings.

---

**`ssl_enabled`** `bool`

Whether SSL/HTTPS is enabled. Mirrors `security.ssl_enabled` for backward compatibility.

---

**`ssl_cert_path`** `str`

Path to the SSL certificate file. Mirrors `security.ssl_cert_path` for backward compatibility.

---

**`ssl_key_path`** `str`

Path to the SSL private key file. Mirrors `security.ssl_key_path` for backward compatibility.

---

**`domain`** `str`

Domain name for SSL certificates. Mirrors `security.domain` for backward compatibility.

---

**`full_validation_enabled`** `bool`

Read-only property indicating whether full JSON Schema validation is active.
Controlled by the `schema_validation` property or the
`SWML_SKIP_SCHEMA_VALIDATION` environment variable.

---

> **Note**
>
> The constructor also accepts `basic_auth`, `schema_path`, `config_file`, and
> `schema_validation` parameters. These are not exposed as public instance attributes
> after initialization. Use `get_basic_auth_credentials()` to retrieve auth credentials
> and `full_validation_enabled` to check validation status.

## **Methods**

#### [add\_section](/docs/server-sdks/reference/python/agents/swml-service/add-section)

Add a new empty section to the SWML document.

#### [add\_verb](/docs/server-sdks/reference/python/agents/swml-service/add-verb)

Add a SWML verb to the main section of the document.

#### [add\_verb\_to\_section](/docs/server-sdks/reference/python/agents/swml-service/add-verb-to-section)

Add a SWML verb to a specific named section of the document.

#### [as\_router](/docs/server-sdks/reference/python/agents/swml-service/as-router)

Create a FastAPI APIRouter for mounting the service into an existing application.

#### [extract\_sip\_username](/docs/server-sdks/reference/python/agents/swml-service/register-routing-callback)

Static utility to extract the SIP username from request body data.

#### [get\_basic\_auth\_credentials](/docs/server-sdks/reference/python/agents/swml-service/get-basic-auth-credentials)

Retrieve the HTTP Basic Auth credentials for the service.

#### [get\_document](/docs/server-sdks/reference/python/agents/swml-service/get-document)

Get the current SWML document as a Python dictionary.

#### [handle\_request](/docs/server-sdks/reference/python/agents/swml-service/handle-request)

Dispatch one HTTP request without a web framework.

#### [manual\_set\_proxy\_url](/docs/server-sdks/reference/python/agents/swml-service/manual-set-proxy-url)

Manually set the proxy URL base for webhook callback generation.

#### [on\_request](/docs/server-sdks/reference/python/agents/swml-service/on-request)

Request handling hook for customizing SWML output per request.

#### [register\_routing\_callback](/docs/server-sdks/reference/python/agents/swml-service/register-routing-callback)

Register routing callbacks for dynamic request handling and SIP routing.

#### [register\_verb\_handler](/docs/server-sdks/reference/python/agents/swml-service/register-verb-handler)

Register custom verb handlers for specialized SWML verb processing.

#### [render\_document](/docs/server-sdks/reference/python/agents/swml-service/render-document)

Render the current SWML document as a JSON string.

#### [reset\_document](/docs/server-sdks/reference/python/agents/swml-service/reset-document)

Reset the SWML document to an empty state.

#### [serve](/docs/server-sdks/reference/python/agents/swml-service/serve)

Start the FastAPI/Uvicorn web server for the SWML service.

#### [stop](/docs/server-sdks/reference/python/agents/swml-service/stop)

Set the internal running flag to False.

## **Example**

```python {4,7}
from signalwire import SWMLService

# Basic service with defaults
service = SWMLService(name="ivr")

# Service with custom route and auth
service = SWMLService(
    name="ivr",
    route="/swml",
    port=8080,
    basic_auth=("admin", "secret123")
)

# Build a SWML document
service.add_verb("answer", {})
service.add_verb("play", {"url": "https://example.com/welcome.mp3"})
service.add_verb("hangup", {})

# Serve it
service.serve()
```

> SWML document generation and FastAPI service base class.

## Docs

- [add_section](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-service/add-section.md): Add a new empty section to the SWML document.
- [add_verb](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-service/add-verb.md): Add a SWML verb to the main section of the document.
- [add_verb_to_section](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-service/add-verb-to-section.md): Add a SWML verb to a specific named section of the document.
- [as_router](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-service/as-router.md): Create a FastAPI APIRouter for mounting the service into an existing application.
- [get_basic_auth_credentials](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-service/get-basic-auth-credentials.md): Retrieve the HTTP Basic Auth credentials for the service.
- [get_document](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-service/get-document.md): Get the current SWML document as a Python dictionary.
- [handle_request](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-service/handle-request.md): Dispatch one HTTP request to the service without a web framework.
- [manual_set_proxy_url](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-service/manual-set-proxy-url.md): Manually set the proxy URL base for webhook callback generation.
- [on_request](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-service/on-request.md): Request handling hook for customizing SWML output per request.
- [register_routing_callback](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-service/register-routing-callback.md): Register routing callbacks for dynamic request handling and SIP routing.
- [register_verb_handler](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-service/register-verb-handler.md): Register custom verb handlers for specialized SWML verb processing.
- [render_document](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-service/render-document.md): Render the current SWML document as a JSON string.
- [reset_document](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-service/reset-document.md): Reset the SWML document to an empty state.
- [serve](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-service/serve.md): Start the FastAPI/Uvicorn web server for the SWML service.
- [stop](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-service/stop.md): Set the internal running flag (does not stop a running Uvicorn server).