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

# WebService

> Static file serving service with HTTP API, authentication, and security headers.

[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**

**`app`** `FastAPI`

The underlying FastAPI application instance. `None` if FastAPI is not installed.

---

**`port`** `int` — default: 8002

The port the server listens on.

---

**`directories`** `dict[str, str]`

Dictionary mapping URL route paths to local directory paths.

---

**`enable_directory_browsing`** `bool` — default: False

Whether directory listing is enabled for mounted directories.

---

**`max_file_size`** `int` — default: 104857600

Maximum file size in bytes that the server will serve (default: 100 MB).

---

**`enable_cors`** `bool` — default: True

Whether CORS middleware is enabled.

---

**`allowed_extensions`** `list[str] | None` — default: None

If set, only files with these extensions are served (e.g., `[".html", ".css"]`).
When `None`, all extensions except those in `blocked_extensions` are allowed.

---

**`blocked_extensions`** `list[str] | None` — default: None

File extensions and names that are never served. Defaults to
`.env`, `.git`, `.gitignore`, `.key`, `.pem`, `.crt`, `.pyc`, `__pycache__`,
`.DS_Store`, `.swp`.

---

**`security`** `SecurityConfig`

The [`SecurityConfig`][securityconfig] instance
managing authentication and security headers.

---

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

## **Methods**

#### [add\_directory](/docs/server-sdks/reference/python/agents/web-service/add-directory)

Mount a new directory at a URL route.

#### [remove\_directory](/docs/server-sdks/reference/python/agents/web-service/remove-directory)

Remove a directory from being served.

#### [start](/docs/server-sdks/reference/python/agents/web-service/start)

Start the HTTP server with optional HTTPS support.

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

Stop the service (placeholder, currently a no-op).

> Static file serving service with HTTP API, authentication, and security headers.

## Docs

- [add_directory](https://signalwire.com/docs/server-sdks/reference/python/agents/web-service/add-directory.md): Mount a new directory at a URL route.
- [remove_directory](https://signalwire.com/docs/server-sdks/reference/python/agents/web-service/remove-directory.md): Remove a directory from being served.
- [start](https://signalwire.com/docs/server-sdks/reference/python/agents/web-service/start.md): Start the HTTP server with optional HTTPS support.
- [stop](https://signalwire.com/docs/server-sdks/reference/python/agents/web-service/stop.md): Stop the service and run cleanup tasks.