Configuring the HTTP API

Warning: This document is for an old version of Rasa. The latest version is 1.10.26.

Using Rasa’s HTTP API

Note: The instructions below are relevant for configuring how a model is run within a Docker container or for testing the HTTP API locally. If you want to deploy your assistant to users, see Deploying Your Rasa Assistant.

You can run a simple HTTP server that handles requests using your trained Rasa model with:

rasa run -m models --enable-api --log-file out.log

All the endpoints this API exposes are documented in HTTP API.

The different parameters are:

-m: the path to the folder containing your Rasa model,
--enable-api: enable this additional API, and
--log-file: the path to the log file.

Rasa can load your model in three different ways:

Fetch the model from a server (see Fetching Models from a Server), or
Fetch the model from a remote storage (see Cloud Storage).
Load the model specified via -m from your local storage system,

Rasa tries to load a model in the above mentioned order, i.e. it only tries to load your model from your local storage system if no model server and no remote storage were configured.

Warning: Make sure to secure your server, either by restricting access to the server (e.g. using firewalls), or by enabling an authentication method: Security Considerations.

Fetching Models from a Server

You can configure the HTTP server to fetch models from another URL:

rasa run --enable-api --log-file out.log --endpoints my_endpoints.yml

The model server is specified in the endpoint configuration (my_endpoints.yml), where you specify the server URL Rasa regularly queries for zipped Rasa models:

models:
  url: http://my-server.com/models/default@latest
  wait_time_between_pulls: 10   # [optional](default: 100)

Note: If you want to pull the model just once from the server, set wait_time_between_pulls to None.

Fetching Models from a Remote Storage

You can also configure the Rasa server to fetch your model from a remote storage:

rasa run -m 20190506-100418.tar.gz --enable-api --log-file out.log --remote-storage aws

The model will be downloaded and stored in a temporary directory on your local storage system. For more information see Cloud Storage.

Configuring SSL / HTTPS

By default the Rasa server is using HTTP for its communication. To secure the communication with SSL, you need to provide a valid certificate and the corresponding private key file.

You can specify these files as part of the rasa run command:

rasa run --ssl-certificate myssl.crt --ssl-keyfile myssl.key

If you encrypted your keyfile with a password during creation, you need to add this password to the command:

rasa run --ssl-certificate myssl.crt --ssl-keyfile myssl.key --ssl-password mypassword

Security Considerations

We recommend to not expose the Rasa Server to the outside world, but rather connect to it from your backend over a private connection (e.g. between docker containers).

Nevertheless, there are two authentication methods built in:

Token Based Auth:

Pass in the token using --auth-token thisismysecret when starting the server:

rasa run \
    -m models \
    --enable-api \
    --log-file out.log \
    --auth-token thisismysecret

Your requests should pass the token, in our case thisismysecret, as a parameter:

$ curl -XGET localhost:5005/conversations/default/tracker?token=thisismysecret

JWT Based Auth:

Enable JWT based authentication using --jwt-secret thisismysecret. Requests to the server need to contain a valid JWT token in the Authorization header that is signed using this secret and the HS256 algorithm.

Your requests should set a proper JWT header:

"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiIsIWF0IjoxNTE2MjM5MDIyfQ.qdrr2_a7Sd80gmCWjnDomOGl8eZFVfKXA6jhncgRn-I"

Endpoint Configuration

To connect Rasa to other endpoints, you can specify an endpoint configuration within a YAML file. Then run Rasa with the flag --endpoints <path to endpoint configuration.yml>.

For example:

rasa run \
    --m <Rasa model> \
    --endpoints <path to endpoint configuration>.yml

Note: You can use environment variables within configuration files by specifying them with ${name of environment variable}. These placeholders are then replaced by the value of the environment variable.

Connecting a Tracker Store

To configure a tracker store within your endpoint configuration, see Tracker Stores.

Connecting an Event Broker

To configure an event broker within your endpoint configuration, see Event Brokers.

👋 I can help you get started with Rasa and answer your technical questions.