***

title: SWMLService
slug: /reference/python/agents/swml-service
description: SWML document generation and FastAPI service base class.
max-toc-depth: 3
---------------------

For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

[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.
</Info>

## **Properties**

<ParamField path="name" type="str" toc={true}>
  Service name/identifier used in logging and server startup messages.
</ParamField>

<ParamField path="route" type="str" toc={true}>
  HTTP route path where this service is accessible. Trailing slashes are stripped
  automatically during initialization.
</ParamField>

<ParamField path="host" type="str" toc={true}>
  Host address the web server binds to.
</ParamField>

<ParamField path="port" type="int" toc={true}>
  Port number the web server binds to.
</ParamField>

<ParamField path="schema_utils" type="SchemaUtils" toc={true}>
  Schema validation utilities for SWML documents. Provides verb validation,
  verb name enumeration, and schema property lookups.
</ParamField>

<ParamField path="verb_registry" type="VerbHandlerRegistry" toc={true}>
  Registry of specialized verb handlers. Manages custom handlers for complex SWML
  verbs that require logic beyond generic schema validation (e.g., the `ai` verb).
</ParamField>

<ParamField path="log" type="Logger" toc={true}>
  Structured logger instance bound to this service name.
</ParamField>

<ParamField path="security" type="SecurityConfig" toc={true}>
  Unified security configuration loaded from environment variables and optional
  config file. Controls SSL, CORS, and host allowlist settings.
</ParamField>

<ParamField path="ssl_enabled" type="bool" toc={true}>
  Whether SSL/HTTPS is enabled. Mirrors `security.ssl_enabled` for backward compatibility.
</ParamField>

<ParamField path="ssl_cert_path" type="str" toc={true}>
  Path to the SSL certificate file. Mirrors `security.ssl_cert_path` for backward compatibility.
</ParamField>

<ParamField path="ssl_key_path" type="str" toc={true}>
  Path to the SSL private key file. Mirrors `security.ssl_key_path` for backward compatibility.
</ParamField>

<ParamField path="domain" type="str" toc={true}>
  Domain name for SSL certificates. Mirrors `security.domain` for backward compatibility.
</ParamField>

<ParamField path="full_validation_enabled" type="bool" toc={true}>
  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.
</ParamField>

<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.
</Note>

## **Methods**

<CardGroup cols={3}>
  <Card title="add_section" href="/docs/server-sdks/reference/python/agents/swml-service/add-section">
    Add a new empty section to the SWML document.
  </Card>

  <Card title="add_verb" href="/docs/server-sdks/reference/python/agents/swml-service/add-verb">
    Add a SWML verb to the main section of the document.
  </Card>

  <Card title="add_verb_to_section" href="/docs/server-sdks/reference/python/agents/swml-service/add-verb-to-section">
    Add a SWML verb to a specific named section of the document.
  </Card>

  <Card title="as_router" href="/docs/server-sdks/reference/python/agents/swml-service/as-router">
    Create a FastAPI APIRouter for mounting the service into an existing application.
  </Card>

  <Card title="get_basic_auth_credentials" href="/docs/server-sdks/reference/python/agents/swml-service/get-basic-auth-credentials">
    Retrieve the HTTP Basic Auth credentials for the service.
  </Card>

  <Card title="get_document" href="/docs/server-sdks/reference/python/agents/swml-service/get-document">
    Get the current SWML document as a Python dictionary.
  </Card>

  <Card title="manual_set_proxy_url" href="/docs/server-sdks/reference/python/agents/swml-service/manual-set-proxy-url">
    Manually set the proxy URL base for webhook callback generation.
  </Card>

  <Card title="on_request" href="/docs/server-sdks/reference/python/agents/swml-service/on-request">
    Request handling hook for customizing SWML output per request.
  </Card>

  <Card title="extract_sip_username" href="/docs/server-sdks/reference/python/agents/swml-service/register-routing-callback">
    Static utility to extract the SIP username from request body data.
  </Card>

  <Card title="register_routing_callback" href="/docs/server-sdks/reference/python/agents/swml-service/register-routing-callback">
    Register routing callbacks for dynamic request handling and SIP routing.
  </Card>

  <Card title="register_verb_handler" href="/docs/server-sdks/reference/python/agents/swml-service/register-verb-handler">
    Register custom verb handlers for specialized SWML verb processing.
  </Card>

  <Card title="render_document" href="/docs/server-sdks/reference/python/agents/swml-service/render-document">
    Render the current SWML document as a JSON string.
  </Card>

  <Card title="reset_document" href="/docs/server-sdks/reference/python/agents/swml-service/reset-document">
    Reset the SWML document to an empty state.
  </Card>

  <Card title="serve" href="/docs/server-sdks/reference/python/agents/swml-service/serve">
    Start the FastAPI/Uvicorn web server for the SWML service.
  </Card>

  <Card title="stop" href="/docs/server-sdks/reference/python/agents/swml-service/stop">
    Set the internal running flag to False.
  </Card>
</CardGroup>

## **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()
```