***

title: WebService
slug: /reference/python/agents/web-service
description: Static file serving service with HTTP API, authentication, and security headers.
max-toc-depth: 3
---------------------

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

[securityconfig]: /docs/server-sdks/reference/python/agents/configuration/security-config

[adddirectory]: /docs/server-sdks/reference/python/agents/web-service/add-directory

[removedirectory]: /docs/server-sdks/reference/python/agents/web-service/remove-directory

[start]: /docs/server-sdks/reference/python/agents/web-service/start

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

WebService provides a standalone FastAPI-based HTTP server for serving static
files alongside your SignalWire agents. It includes security features such as
Basic authentication, CORS, path traversal prevention, file extension filtering,
and configurable security headers.

Use WebService when your agent needs to serve audio files, web pages, or other
static assets over HTTP/HTTPS.

```python {3}
from signalwire import WebService

web = WebService(
    port=8002,
    directories={"/audio": "./audio_files", "/docs": "./public"},
    enable_directory_browsing=True
)
web.start()
```

## **Properties**

<ParamField path="app" type="FastAPI" toc={true}>
  The underlying FastAPI application instance. `None` if FastAPI is not installed.
</ParamField>

<ParamField path="port" type="int" default="8002" toc={true}>
  The port the server listens on.
</ParamField>

<ParamField path="directories" type="dict[str, str]" toc={true}>
  Dictionary mapping URL route paths to local directory paths.
</ParamField>

<ParamField path="enable_directory_browsing" type="bool" default="False" toc={true}>
  Whether directory listing is enabled for mounted directories.
</ParamField>

<ParamField path="max_file_size" type="int" default="104857600" toc={true}>
  Maximum file size in bytes that the server will serve (default: 100 MB).
</ParamField>

<ParamField path="enable_cors" type="bool" default="True" toc={true}>
  Whether CORS middleware is enabled.
</ParamField>

<ParamField path="allowed_extensions" type="Optional[list[str]]" toc={true}>
  If set, only files with these extensions are served (e.g., `[".html", ".css"]`).
  When `None`, all extensions except those in `blocked_extensions` are allowed.
</ParamField>

<ParamField path="blocked_extensions" type="Optional[list]" toc={true}>
  File extensions and names that are never served. Defaults to
  `.env`, `.git`, `.gitignore`, `.key`, `.pem`, `.crt`, `.pyc`, `__pycache__`,
  `.DS_Store`, `.swp`.
</ParamField>

<ParamField path="security" type="SecurityConfig" toc={true}>
  The [`SecurityConfig`][securityconfig] instance
  managing authentication and security headers.
</ParamField>

<Note>
  The constructor also accepts `basic_auth` (`Optional[tuple[str, str]]`) and
  `config_file` (`Optional[str]`) parameters. These are not exposed as public
  instance attributes after initialization.
</Note>

## **Methods**

<CardGroup cols={2}>
  <Card title="add_directory" href="/docs/server-sdks/reference/python/agents/web-service/add-directory">
    Mount a new directory at a URL route.
  </Card>

  <Card title="remove_directory" href="/docs/server-sdks/reference/python/agents/web-service/remove-directory">
    Remove a directory from being served.
  </Card>

  <Card title="start" href="/docs/server-sdks/reference/python/agents/web-service/start">
    Start the HTTP server with optional HTTPS support.
  </Card>

  <Card title="stop" href="/docs/server-sdks/reference/python/agents/web-service/stop">
    Stop the service (placeholder, currently a no-op).
  </Card>
</CardGroup>