Skip to main content

Rasa Pro REST API

API docs by Redocly

Rasa - Server Endpoints (1.0.0)

Download OpenAPI specification:Download

The Rasa server provides endpoints to retrieve trackers of conversations as well as endpoints to modify them. Additionally, endpoints for training and testing models are provided.

Server Information

Health endpoint of Rasa Server

This URL can be used as an endpoint to run health checks against. When the server is running this will return 200.

Responses

Response samples

Content type
text/plain
Hello from Rasa: 1.0.0

Information about your Rasa Pro License

Returns the license information about your Rasa Pro License

Responses

Response samples

Content type
application/json
{
  • "id": "u5fn8888-e213-4c12-9542-0baslfdkjas",
  • "company": "acme",
  • "scope": "rasa:pro rasa:voice",
  • "email": "acme@email.com",
  • "expires": "2026-01-01T00:00:00+00:00"
}

Version of Rasa

Returns the version of Rasa.

Responses

Response samples

Content type
application/json
{
  • "version": "1.0.0",
  • "minimum_compatible_version": "1.0.0"
}

Status of the Rasa server

Information about the server and the currently loaded Rasa model.

Authorizations:
TokenAuthJWT

Responses

Response samples

Content type
application/json
{
  • "model_id": "75a985b7b86d442ca013d61ea4781b22",
  • "model_file": "20190429-103105.tar.gz",
  • "num_active_training_jobs": 2
}

Tracker

Retrieve a conversations tracker

The tracker represents the state of the conversation. The state of the tracker is created by applying a sequence of events, which modify the state. These events can optionally be included in the response.

Authorizations:
TokenAuthJWT
path Parameters
conversation_id
required
string
Example: default

Id of the conversation

query Parameters
include_events
string
Default: "AFTER_RESTART"
Enum: "ALL" "APPLIED" "AFTER_RESTART" "NONE"
Example: include_events=AFTER_RESTART

Specify which events of the tracker the response should contain.

  • ALL - every logged event.

  • APPLIED - only events that contribute to the trackers state. This excludes reverted utterances and actions that got undone.

  • AFTER_RESTART - all events since the last restarted event. This includes utterances that got reverted and actions that got undone.

  • NONE - no events.

until
number
Default: "None"
Example: until=1559744410

All events previous to the passed timestamp will be replayed. Events that occur exactly at the target time will be included.

Responses

Response samples

Content type
application/json
{
  • "sender_id": "default",
  • "slots": [
    ],
  • "latest_message": {
    },
  • "latest_event_time": 1537645578.314389,
  • "followup_action": "string",
  • "paused": false,
  • "stack": [
    ],
  • "events": [
    ],
  • "latest_input_channel": "rest",
  • "latest_action_name": "action_listen",
  • "latest_action": {
    },
  • "active_loop": {
    }
}

Append events to a tracker

Appends one or multiple new events to the tracker state of the conversation. Any existing events will be kept and the new events will be appended, updating the existing state. If events are appended to a new conversation ID, the tracker will be initialised with a new session.

Authorizations:
TokenAuthJWT
path Parameters
conversation_id
required
string
Example: default

Id of the conversation

query Parameters
include_events
string
Default: "AFTER_RESTART"
Enum: "ALL" "APPLIED" "AFTER_RESTART" "NONE"
Example: include_events=AFTER_RESTART

Specify which events of the tracker the response should contain.

  • ALL - every logged event.

  • APPLIED - only events that contribute to the trackers state. This excludes reverted utterances and actions that got undone.

  • AFTER_RESTART - all events since the last restarted event. This includes utterances that got reverted and actions that got undone.

  • NONE - no events.

output_channel
string
Enum: "latest" "slack" "callback" "facebook" "rocketchat" "telegram" "twilio" "webexteams" "socketio"
Example: output_channel=slack

The bot's utterances will be forwarded to this channel. It uses the credentials listed in credentials.yml to connect. In case the channel does not support this, the utterances will be returned in the response body. Use latest to try to send the messages to the latest channel the user used. Currently supported channels are listed in the permitted values for the parameter.

execute_side_effects
boolean
Default: false

If true, any BotUttered event will be forwarded to the channel specified in the output_channel parameter. Any ReminderScheduled or ReminderCancelled event will also be processed.

Request Body schema: application/json
required
One of
Any of
event
required
string
Value: "user"

Event name

timestamp
integer

Time of application

metadata
object
text
string or null

Text of user message.

input_channel
string or null
message_id
string or null
object (ParseResult)

NLU parser information. If set, message will not be passed through NLU, but instead this parsing information will be used.

Responses

Request samples

Content type
application/json
Example
{
  • "event": "user",
  • "timestamp": null,
  • "metadata": {
    },
  • "text": "string",
  • "input_channel": "string",
  • "message_id": "string",
  • "parse_data": {
    }
}

Response samples

Content type
application/json
{
  • "sender_id": "default",
  • "slots": [
    ],
  • "latest_message": {
    },
  • "latest_event_time": 1537645578.314389,
  • "followup_action": "string",
  • "paused": false,
  • "stack": [
    ],
  • "events": [
    ],
  • "latest_input_channel": "rest",
  • "latest_action_name": "action_listen",
  • "latest_action": {
    },
  • "active_loop": {
    }
}

Replace a trackers events

Replaces all events of a tracker with the passed list of events. This endpoint should not be used to modify trackers in a production setup, but rather for creating training data.

Authorizations:
TokenAuthJWT
path Parameters
conversation_id
required
string
Example: default

Id of the conversation

query Parameters
include_events
string
Default: "AFTER_RESTART"
Enum: "ALL" "APPLIED" "AFTER_RESTART" "NONE"
Example: include_events=AFTER_RESTART

Specify which events of the tracker the response should contain.

  • ALL - every logged event.

  • APPLIED - only events that contribute to the trackers state. This excludes reverted utterances and actions that got undone.

  • AFTER_RESTART - all events since the last restarted event. This includes utterances that got reverted and actions that got undone.

  • NONE - no events.

Request Body schema: application/json
required
Array
Any of
event
required
string
Value: "user"

Event name

timestamp
integer

Time of application

metadata
object
text
string or null

Text of user message.

input_channel
string or null
message_id
string or null
object (ParseResult)

NLU parser information. If set, message will not be passed through NLU, but instead this parsing information will be used.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "sender_id": "default",
  • "slots": [
    ],
  • "latest_message": {
    },
  • "latest_event_time": 1537645578.314389,
  • "followup_action": "string",
  • "paused": false,
  • "stack": [
    ],
  • "events": [
    ],
  • "latest_input_channel": "rest",
  • "latest_action_name": "action_listen",
  • "latest_action": {
    },
  • "active_loop": {
    }
}

Retrieve an end-to-end story corresponding to a conversation

The story represents the whole conversation in end-to-end format. This can be posted to the '/test/stories' endpoint and used as a test.

Authorizations:
TokenAuthJWT
path Parameters
conversation_id
required
string
Example: default

Id of the conversation

query Parameters
until
number
Default: "None"
Example: until=1559744410

All events previous to the passed timestamp will be replayed. Events that occur exactly at the target time will be included.

all_sessions
boolean
Default: false

Whether to fetch all sessions in a conversation, or only the latest session

  • true - fetch all conversation sessions.
  • false - [default] fetch only the latest conversation session.

Responses

Response samples

Content type
text/yml
- story: story_00055028
  steps:
  - user: |
      hello
    intent: greet
  - action: utter_ask_howcanhelp
  - user: |
      I'm looking for a [moderately priced]{"entity": "price", "value": "moderate"} [Indian]{"entity": "cuisine"} restaurant for [two]({"entity": "people"}) people
    intent: inform
  - action: utter_on_it
  - action: utter_ask_location

Run an action in a conversation Deprecated

DEPRECATED. Runs the action, calling the action server if necessary. Any responses sent by the executed action will be forwarded to the channel specified in the output_channel parameter. If no output channel is specified, any messages that should be sent to the user will be included in the response of this endpoint.

Authorizations:
TokenAuthJWT
path Parameters
conversation_id
required
string
Example: default

Id of the conversation

query Parameters
include_events
string
Default: "AFTER_RESTART"
Enum: "ALL" "APPLIED" "AFTER_RESTART" "NONE"
Example: include_events=AFTER_RESTART

Specify which events of the tracker the response should contain.

  • ALL - every logged event.

  • APPLIED - only events that contribute to the trackers state. This excludes reverted utterances and actions that got undone.

  • AFTER_RESTART - all events since the last restarted event. This includes utterances that got reverted and actions that got undone.

  • NONE - no events.

output_channel
string
Enum: "latest" "slack" "callback" "facebook" "rocketchat" "telegram" "twilio" "webexteams" "socketio"
Example: output_channel=slack

The bot's utterances will be forwarded to this channel. It uses the credentials listed in credentials.yml to connect. In case the channel does not support this, the utterances will be returned in the response body. Use latest to try to send the messages to the latest channel the user used. Currently supported channels are listed in the permitted values for the parameter.

Request Body schema: application/json
required
name
required
string

Name of the action to be executed.

policy
string or null

Name of the policy that predicted the action.

confidence
number or null

Confidence of the prediction.

Responses

Request samples

Content type
application/json
{
  • "name": "utter_greet",
  • "policy": "string",
  • "confidence": 0.987232
}

Response samples

Content type
application/json
{
  • "tracker": {
    },
  • "messages": [
    ]
}

Inject an intent into a conversation

Sends a specified intent and list of entities in place of a user message. The bot then predicts and executes a response action. Any responses sent by the executed action will be forwarded to the channel specified in the output_channel parameter. If no output channel is specified, any messages that should be sent to the user will be included in the response of this endpoint.

Authorizations:
TokenAuthJWT
path Parameters
conversation_id
required
string
Example: default

Id of the conversation

query Parameters
include_events
string
Default: "AFTER_RESTART"
Enum: "ALL" "APPLIED" "AFTER_RESTART" "NONE"
Example: include_events=AFTER_RESTART

Specify which events of the tracker the response should contain.

  • ALL - every logged event.

  • APPLIED - only events that contribute to the trackers state. This excludes reverted utterances and actions that got undone.

  • AFTER_RESTART - all events since the last restarted event. This includes utterances that got reverted and actions that got undone.

  • NONE - no events.

output_channel
string
Enum: "latest" "slack" "callback" "facebook" "rocketchat" "telegram" "twilio" "webexteams" "socketio"
Example: output_channel=slack

The bot's utterances will be forwarded to this channel. It uses the credentials listed in credentials.yml to connect. In case the channel does not support this, the utterances will be returned in the response body. Use latest to try to send the messages to the latest channel the user used. Currently supported channels are listed in the permitted values for the parameter.

Request Body schema: application/json
required
name
required
string

Name of the intent to be executed.

entities
object or null

Entities to be passed on.

Responses

Request samples

Content type
application/json
{
  • "name": "greet",
  • "entities": {
    }
}

Response samples

Content type
application/json
{
  • "tracker": {
    },
  • "messages": [
    ]
}

Predict the next action

Runs the conversations tracker through the model's policies to predict the scores of all actions present in the model's domain. Actions are returned in the 'scores' array, sorted on their 'score' values. The state of the tracker is not modified.

Authorizations:
TokenAuthJWT
path Parameters
conversation_id
required
string
Example: default

Id of the conversation

Responses

Response samples

Content type
application/json
{
  • "scores": [
    ],
  • "policy": "policy_2_TEDPolicy",
  • "confidence": 0.057,
  • "tracker": {
    }
}

Add a message to a tracker

Adds a message to a tracker. This doesn't trigger the prediction loop. It will log the message on the tracker and return, no actions will be predicted or run. This is often used together with the predict endpoint.

Authorizations:
TokenAuthJWT
path Parameters
conversation_id
required
string
Example: default

Id of the conversation

query Parameters
include_events
string
Default: "AFTER_RESTART"
Enum: "ALL" "APPLIED" "AFTER_RESTART" "NONE"
Example: include_events=AFTER_RESTART

Specify which events of the tracker the response should contain.

  • ALL - every logged event.

  • APPLIED - only events that contribute to the trackers state. This excludes reverted utterances and actions that got undone.

  • AFTER_RESTART - all events since the last restarted event. This includes utterances that got reverted and actions that got undone.

  • NONE - no events.

Request Body schema: application/json
required
text
required
string

Message text

sender
required
string
Value: "user"

Origin of the message - who sent it

object (ParseResult)

NLU parser information. If set, message will not be passed through NLU, but instead this parsing information will be used.

Responses

Request samples

Content type
application/json
{
  • "text": "Hello!",
  • "sender": "user",
  • "parse_data": {
    }
}

Response samples

Content type
application/json
{
  • "sender_id": "default",
  • "slots": [
    ],
  • "latest_message": {
    },
  • "latest_event_time": 1537645578.314389,
  • "followup_action": "string",
  • "paused": false,
  • "stack": [
    ],
  • "events": [
    ],
  • "latest_input_channel": "rest",
  • "latest_action_name": "action_listen",
  • "latest_action": {
    },
  • "active_loop": {
    }
}

Model

Train a Rasa model

Trains a new Rasa model. Depending on the data given only a dialogue model, only a NLU model, or a model combining a trained dialogue model with an NLU model will be trained. The new model is not loaded by default.

Authorizations:
TokenAuthJWT
query Parameters
save_to_default_model_directory
boolean
Default: true

If true (default) the trained model will be saved in the default model directory, if false it will be saved in a temporary directory

force_training
boolean
Default: false

Force a model training even if the data has not changed

augmentation
string
Default: 50

How much data augmentation to use during training

num_threads
string
Default: 1

Maximum amount of threads to use when training

callback_url
string
Default: "None"
Example: callback_url=https://example.com/rasa_evaluations

If specified the call will return immediately with an empty response and status code 204. The actual result or any errors will be sent to the given callback URL as the body of a post request.

Request Body schema: application/yaml
required

The training data should be in YAML format.

pipeline
Array of arrays

Pipeline list

policies
Array of arrays

Policies list

entities
Array of arrays

Entity list

slots
Array of arrays

Slots list

actions
Array of arrays

Action list

forms
Array of arrays

Forms list

e2e_actions
Array of arrays

E2E Action list

object

Bot response templates

object

Session configuration options

nlu
Array of arrays

Rasa NLU data, array of intents

rules
Array of arrays

Rule list

stories
Array of arrays

Rasa Core stories in YAML format

flows
object

Rasa Pro flows in YAML format

force
boolean
Deprecated

Force a model training even if the data has not changed

save_to_default_model_directory
boolean
Deprecated

If true (default) the trained model will be saved in the default model directory, if false it will be saved in a temporary directory

Responses

Request samples

Content type
application/yaml
pipeline: []

policies: []

intents:
  - greet
  - goodbye

entities: []

slots:
  contacts_list:
    type: text
    mappings:
      - type: custom
        action: list_contacts

actions:
  - list_contacts

forms: {}
e2e_actions: []

responses:
  utter_greet:
  - text: "Hey! How are you?"

  utter_goodbye:
  - text: "Bye"

  utter_list_contacts:
  - text: "You currently have the following contacts:\n{contacts_list}"

  utter_no_contacts:
  - text: "You have no contacts in your list."

session_config:
  session_expiration_time: 60
  carry_over_slots_to_new_session: true

nlu:
- intent: greet
  examples: |
    - hey
    - hello

- intent: goodbye
  examples: |
    - bye
    - goodbye

rules:

- rule: Say goodbye anytime the user says goodbye
  steps:
  - intent: goodbye
  - action: utter_goodbye

stories:

- story: happy path
  steps:
  - intent: greet
  - action: utter_greet
  - intent: goodbye
  - action: utter_goodbye

flows:
   list_contacts:
      name: list your contacts
      description: show your contact list
      steps:
        - action: list_contacts
          next:
          - if: "slots.contacts_list"
            then:
              - action: utter_list_contacts
                next: END
          - else:
              - action: utter_no_contacts
                next: END

Response samples

Content type
application/json
{
  • "version": "1.0.0",
  • "status": "failure",
  • "reason": "BadRequest",
  • "code": 400
}

Evaluate stories

Evaluates one or multiple stories against the currently loaded Rasa model.

Authorizations:
TokenAuthJWT
query Parameters
e2e
boolean
Default: false

Perform an end-to-end evaluation on the posted stories.

Request Body schema: text/yml
required
string (StoriesTrainingData)

Rasa Core stories in YAML format

Responses

Response samples

Content type
application/json
{
  • "actions": [
    ],
  • "is_end_to_end_evaluation": true,
  • "precision": 1,
  • "f1": 0.9333333333333333,
  • "accuracy": 0.9,
  • "in_training_data_fraction": 0.8571428571428571,
  • "report": {
    }
}

Perform an intent evaluation

Evaluates NLU model against a model or using cross-validation.

Authorizations:
TokenAuthJWT
query Parameters
model
string
Example: model=rasa-model.tar.gz

Model that should be used for evaluation. If the parameter is set, the model will be fetched with the currently loaded configuration setup. However, the currently loaded model will not be updated. The state of the server will not change. If the parameter is not set, the currently loaded model will be used for the evaluation.

callback_url
string
Default: "None"
Example: callback_url=https://example.com/rasa_evaluations

If specified the call will return immediately with an empty response and status code 204. The actual result or any errors will be sent to the given callback URL as the body of a post request.

cross_validation_folds
integer
Default: null

Number of cross validation folds. If this parameter is specified the given training data will be used for a cross-validation instead of using it as test set for the specified model. Note that this is only supported for YAML data.

Request Body schema:
required
string

NLU training data and model configuration. The model configuration is only required if cross-validation is used.

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "intent_evaluation": {
    },
  • "response_selection_evaluation": {
    },
  • "entity_evaluation": {
    }
}

Predict an action on a temporary state

Predicts the next action on the tracker state as it is posted to this endpoint. Rasa will create a temporary tracker from the provided events and will use it to predict an action. No messages will be sent and no action will be run.

Authorizations:
TokenAuthJWT
query Parameters
include_events
string
Default: "AFTER_RESTART"
Enum: "ALL" "APPLIED" "AFTER_RESTART" "NONE"
Example: include_events=AFTER_RESTART

Specify which events of the tracker the response should contain.

  • ALL - every logged event.

  • APPLIED - only events that contribute to the trackers state. This excludes reverted utterances and actions that got undone.

  • AFTER_RESTART - all events since the last restarted event. This includes utterances that got reverted and actions that got undone.

  • NONE - no events.

Request Body schema: application/json
required
Array
Any of
event
required
string
Value: "user"

Event name

timestamp
integer

Time of application

metadata
object
text
string or null

Text of user message.

input_channel
string or null
message_id
string or null
object (ParseResult)

NLU parser information. If set, message will not be passed through NLU, but instead this parsing information will be used.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "scores": [
    ],
  • "policy": "policy_2_TEDPolicy",
  • "confidence": 0.057,
  • "tracker": {
    }
}

Parse a message using the Rasa model

Predicts the intent and entities of the message posted to this endpoint. No messages will be stored to a conversation and no action will be run. This will just retrieve the NLU parse results.

Authorizations:
TokenAuthJWT
query Parameters
emulation_mode
string
Enum: "WIT" "LUIS" "DIALOGFLOW"
Example: emulation_mode=LUIS

Specify the emulation mode to use. Emulation mode transforms the response JSON to the format expected by the service specified as the emulation_mode. Requests must still be sent in the regular Rasa format.

Request Body schema: application/json
required
text
string

Message to be parsed

message_id
string

Optional ID for message to be parsed

Responses

Request samples

Content type
application/json
{
  • "text": "Hello, I am Rasa!",
  • "message_id": "b2831e73-1407-4ba0-a861-0f30a42a2a5a"
}

Response samples

Content type
application/json
{
  • "entities": [
    ],
  • "intent": {
    },
  • "text": "Hello!",
  • "commands": [
    ]
}

Replace the currently loaded model

Updates the currently loaded model. First, tries to load the model from the local (note: local to Rasa server) storage system. Secondly, tries to load the model from the provided model server configuration. Last, tries to load the model from the provided remote storage.

Authorizations:
TokenAuthJWT
Request Body schema: application/json
required
model_file
string

Path to model file

object (EndpointConfig)
remote_storage
string
Enum: "aws" "gcs" "azure"

Name of remote storage system

Responses

Request samples

Content type
application/json
{
  • "model_file": "/absolute-path-to-models-directory/models/20190512.tar.gz",
  • "model_server": {
    },
  • "remote_storage": "aws"
}

Response samples

Content type
application/json
{
  • "version": "1.0.0",
  • "status": "failure",
  • "reason": "BadRequest",
  • "code": 400
}

Unload the trained model

Unloads the currently loaded trained model from the server.

Authorizations:
TokenAuthJWT

Responses

Response samples

Content type
application/json
{
  • "version": "1.0.0",
  • "status": "failure",
  • "reason": "NotAuthenticated",
  • "message": "User is not authenticated to access resource.",
  • "code": 401
}

Flows

Retrieve the flows of the assistant

Returns the assistant was trained on.

Authorizations:
TokenAuthJWT

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Domain

Retrieve the loaded domain

Returns the domain specification the currently loaded model is using.

Authorizations:
TokenAuthJWT

Responses

Response samples

Content type
{
  • "config": {
    },
  • "intents": [
    ],
  • "entities": [
    ],
  • "slots": {
    },
  • "responses": {
    },
  • "actions": [
    ]
}

Channel Webhooks

Post user message from a REST channel

Post a message from the user and forward it to the assistant. Return the message of the assistant to the user.

Authorizations:
TokenAuthJWT
path Parameters
rest_channel
required
string
Enum: "rest" "callback"

The REST channel used for custom integrations. They provide a URL where you can post messages and either receive response messages directly, or asynchronously via a webhook.

Request Body schema: application/json
required

The user message payload

sender
string

The sender ID

message
string

The message text

Responses

Request samples

Content type
application/json
{
  • "sender": "default",
  • "message": "Hello!"
}

Response samples

Content type
application/json
[
  • {
    }
]

Post user message from a custom channel

Post a message from the user and forward it to the assistant. Return the message of the assistant to the user. This is from a custom channel.

Authorizations:
TokenAuthJWT
path Parameters
custom_channel
required
string
Example: my_custom_channel

The custom channel connector used for integration. They provide a URL where you can post and receive messages.

Request Body schema: application/json
required

The user message payload

sender
string

The sender ID

message
string

The message text

stream
boolean

Whether to use streaming response

input_channel
string

Input channel name

metadata
object

Additional metadata

Responses

Request samples

Content type
application/json
{
  • "sender": "string",
  • "message": "string",
  • "stream": true,
  • "input_channel": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "messages": [
    ],
  • "metadata": { },
  • "conversation_id": "string",
  • "tracker_state": {
    }
}
Last updated on