id | sidebar_label | title | description | abstract |
---|---|---|---|---|
http-api |
HTTP API |
Rasa Open Source HTTP API |
Read about Rasa's HTTP API that has endpoints for conversations, training models, and configuring your bot. |
You can use the HTTP API to interact with a running Rasa Open Source server. With the API, you can train models, send messages, run tests, and more. |
:::tip Looking for API endpoints? Check out the API Spec for all of the available endpoints as well as their request and response formats.
:::
By default, running a Rasa server does not enable the API endpoints. Interactions
with the bot can happen over the exposed webhooks/<channel>/webhook
endpoints.
To enable the API for direct interaction with conversation trackers and other
bot endpoints, add the --enable-api
parameter to your run command:
rasa run --enable-api
Note that you start the server with an NLU-only model, not all the available endpoints can be called. Some endpoints will return a 409 status code, as a trained dialogue model is needed to process the request.
:::caution Make sure to secure your server, either by restricting access to the server (e.g. using firewalls), or by enabling an authentication method. See Security Considerations.
:::
By default, the HTTP server runs as a single process. You can change the number
of worker processes using the SANIC_WORKERS
environment variable. It is
recommended that you set the number of workers to the number of available CPU cores
(check out the
Sanic docs
for more details). This will only work in combination with the
RedisLockStore
(see Lock Stores.
:::caution The SocketIO channel does not support multiple worker processes.
:::
We recommend that you don't expose the Rasa Server to the outside world directly, but rather connect to it via e.g. Nginx.
Nevertheless, there are two authentication methods built in:
To use a plaintext token to secure your server, specify the token in the argument --auth-token thisismysecret
when starting
the server:
rasa run \
--enable-api \
--auth-token thisismysecret
Any clients sending requests to the server must pass the token as a query parameter, or the request will be rejected. For example, to fetch a tracker from the server:
curl -XGET localhost:5005/conversations/default/tracker?token=thisismysecret
To use JWT based authentication, specify the JWT secret in the argument --jwt-secret thisismysecret
on startup of the server:
rasa run \
--enable-api \
--jwt-secret thisismysecret
Client requests to the server will need to contain a valid JWT token in
the Authorization
header that is signed using this secret
and the HS256
algorithm e.g.
"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ"
"zdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIi"
"wiaWF0IjoxNTE2MjM5MDIyfQ.qdrr2_a7Sd80gmCWjnDomO"
"Gl8eZFVfKXA6jhncgRn-I"
The token's payload must contain an object under the user
key,
which in turn must contain the username
and role
attributes.
The following is an example payload for a JWT token:
{
"user": {
"username": "<sender_id>",
"role": "user"
}
}
If the role
is admin
, all endpoints are accessible.
If the role
is user
, endpoints with a sender_id
parameter are only accessible
if the sender_id
matches the payload's username
property.
rasa run \
-m models \
--enable-api \
--jwt-secret thisismysecret
To create and encode the token, you can use tools such as the JWT Debugger, or a Python module such as PyJWT.