Rasa X/Enterprise Documentation

Rasa Enterprise HTTP API (1.1.3)

Download OpenAPI specification: Download

This is the documentation for the Rasa Enterprise HTTP APIs.

Authentication

bearerAuth

Authentication via a JWT token, included in the HTTP Authorization header. Applicable only on certain endpoints.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

apiToken

Authentication via a per-user secret API token, included in the api_token query string argument. Applicable only on certain endpoints.

Security Scheme Type API Key
Query parameter name: api_token

rasaXToken

Authentication via a configurable per-server secret token, included in the token query string argument. Applicable only on certain endpoints.

Security Scheme Type API Key
Query parameter name: token

Authentication Endpoints

Perform authentication using a username and password.

Authorizations:
Request Body schema: application/json
username
required		 string
password
required		 string

Responses

200 Success status

401 Authentication required to access this resource.

post/auth

Local Server

https://api/auth

Request Samples

{"username": "string",
"password": "string"}

Response Samples

{"access_token": "string"}

Git

Information about connected Git repositories

Store credentials for a Git repository

Authorizations:
Request Body schema: application/json

Credentials for the repository
id integer
ID of the repository
name string
Name of the repository
repository_url string
URL to clone repository
ssh_key string
SSH key which should be used to access a private repository
username string
Username used to access the repository when HTTPS is used. This field is only used in Rasa Enterprise deployments.
password string
Password used to access the repository when HTTPS is used. Note: this property is only present in request payloads, and is never part of API responses. Additionally, passwords are never stored by Rasa Enterprise, they are only cached temporarily in memory using Git's 'cache' credential store. This field is only used in Rasa Enterprise deployments.
git_service string
Name of the Git service which is used
git_service_access_token string
Access token which might be used to access the API of the Git service (e.g. to create pull requests)
target_branch string
Name of the branch which should be pulled
use_generated_ssh_keys boolean
If True used the private SSH key generated by Rasa Enterprise.
is_target_branch_protected boolean
True if changes cannot be pushed directly to the target branch.
is_target_branch_compatible boolean
False if current branch contains incompatible data
first_annotator_id string
Name of the user who made the the first annotation since Integrated Version Control was in a clean state.
first_annotated_at number
Time of the first annotation since Integrated Version Control was in a clean state as unix timestamp.

Responses

201 Created Git repository

400 The checked out repository does not contain a valid Rasa project.

401 Authentication required to access this resource.

403 Not enough permissions to access this resource.

409 Repository creation failed due to having specified an HTTPS URL when Rasa Enterprise is not installed.

422 Branch could not be found in the the checked out repository.

post/git-repositories

Local Server

https://api/git-repositories

Request Samples

{"id": 0,
"name": "string",
"repository_url": "string",
"ssh_key": "string",
"username": "string",
"password": "string",
"git_service": "github",
"git_service_access_token": "string",
"target_branch": "string",
"use_generated_ssh_keys": true,
"is_target_branch_protected": true,
"is_target_branch_compatible": true,
"first_annotator_id": "string",
"first_annotated_at": 0}

Response Samples

{"id": 0,
"name": "string",
"repository_url": "string",
"ssh_key": "string",
"username": "string",
"password": "string",
"git_service": "github",
"git_service_access_token": "string",
"target_branch": "string",
"use_generated_ssh_keys": true,
"is_target_branch_protected": true,
"is_target_branch_compatible": true,
"first_annotator_id": "string",
"first_annotated_at": 0}

Licensing

Rasa Enterprise license management

Activate Rasa Enterprise using a license

Authorizations:
Request Body schema: application/json
license
required		 string
Rasa Enterprise license string

Responses

200 Rasa Enterprise successfully activated

400 Error while trying to validate Rasa Enterprise license

401 Authentication required to access this resource.

403 Not enough permissions to access this resource.

post/license

Local Server

https://api/license

Request Samples

{"license": "string"}

Response Samples

{"jti": "string",
"iat": 0,
"nbf": 0,
"exp": 0,
"version": 0,
"email": "string"}

Get information about a stored Rasa Enterprise license

Authorizations:

Responses

200 Information about a stored Rasa Enterprise license in the database

401 Authentication required to access this resource.

403 Not enough permissions to access this resource.

404 No stored Rasa Enterprise license was found

get/license

Local Server

https://api/license

Response Samples

{"encoded": "string",
"decoded": {
"jti": "string",
"iat": 0,
"nbf": 0,
"exp": 0,
"version": 0,
"email": "string"
},
"valid": true}

Delete a stored Rasa Enterprise license

Authorizations:

Responses

204 Rasa Enterprise license was successfully deleted

401 Authentication required to access this resource.

403 Not enough permissions to access this resource.

404 No stored Rasa Enterprise license was found

delete/license

Local Server

https://api/license

Response Samples

{"exception": "string",
"reasons": "string"}

Status

API status information

Fetch status of Rasa services

Authorizations:

Responses

200 Status of services

get/health

Local Server

https://api/health

Response Samples

{"production": {
"version": "string",
"minimum_compatible_version": "string",
"status": 0
},
"worker": {
"version": "string",
"minimum_compatible_version": "string",
"status": 0
},
"database_migration": {
"status": "string",
"current_revision": ["string"],
"target_revision": ["string"],
"progress_in_percent": 0
}}

Fetch versions of services.

Fetch versions of services. If an update is available, the response will also contain an optional "updates" section.

Authorizations:
Query Parameters
skip_external boolean
Default: false
When true, skip interactions with external services (Rasa Open Source nodes and DockerHub).

Responses

200 Versions of services

get/version

Local Server

https://api/version

Response Samples

{"rasa": {
"production": "string",
"worker": "string"
},
"rasa-x": "string",
"enterprise": true,
"local_mode": true,
"development_mode": true,
"updates": {
"rasa-x": {
"version": "string",
"changelog_url": "string"
}}
}
}

Telemetry

Access the current telemetry configuration.

Authorizations:
Query Parameters
include_user_groups boolean
Default: false
When true, include user groups in response

Responses

200 Current telemetry configuration

401 Authentication required to access this resource.

403 Not enough permissions to access this resource.

get/telemetry

Local Server

https://api/telemetry

Response Samples

{"telemetry_enabled": true,
"user_groups": ["string"],
"user_id": "string"}

Disable telemetry in server mode.

Disable telemetry if Rasa Enterprise is running in server mode. After calling this endpoint, the Rasa Enterprise server must be restarted in order for the changes to take effect.

Authorizations:

Responses

200 Telemetry configuration was updated, or was already disabled

400 If Rasa Enterprise is running in local mode.

401 Authentication required to access this resource.

403 Not enough permissions to access this resource.

delete/telemetry

Local Server

https://api/telemetry

Response Samples

{"exception": "string",
"reasons": "string"}

Conversations

Conversations between your assistant and end users

Return data tags assigned to the conversation ID

Path Parameters
conversation_id
required		 string
Example: conversation_id
Sender ID

Responses

200 Data tags were successfully retrieved (including empty result)

404 Conversation was not found

get/conversations/{conversation_id}/data-tags

Local Server

https://api/conversations/{conversation_id}/data-tags

Response Samples

[
{"id": 0,
"value": "string",
"color": "string"}
]

Assign data tags to a conversation

Assign all data tags from the body of the request to the conversation. If data tags don’t exist yet, they will be created.

Authorizations:
Path Parameters
conversation_id
required		 string
Example: conversation_id
Sender ID
Request Body schema: application/json

Array ()
id integer
ID of an already existing data tag. If this property is present, then all other properties will be ignored, and this ID will be the one assigned to the conversation or message
value string
Name of the data tag (new or already existing one). If a data tag with this name already exists, the existing data tag will be assigned to the conversation or message. If this property is present, then "color" is also required
color string
Hex value of the data tag's color (without "#"). If this property is present, then "value" is also required

Responses

200 All tags were successfully assigned to a conversation

400 An error happened while assigning the tags

post/conversations/{conversation_id}/data-tags

Local Server

https://api/conversations/{conversation_id}/data-tags

Request Samples

[
{"id": 0,
"value": "string",
"color": "string"}
]

Remove tag from a conversation

Remove a tag from a conversation.

Path Parameters
conversation_id
required		 string
Example: conversation_id
Sender ID
data_tag_id
required		 number
Example: data_tag_id
Data tag ID

Responses

204 Tag was successfully removed from a conversation

404 Conversation or tag were not found

delete/conversations/{conversation_id}/data-tags/{data_tag_id}

Local Server

https://api/conversations/{conversation_id}/data-tags/{data_tag_id}

Models

Your combined NLU and Core models

Upload a zipped Rasa model

Path Parameters
project_id
required		 string
Example: default
Project ID
Request Body schema: multipart/form-data

Responses

201 The created model.

400 Model could not be saved.

409 A model with that name already exists.

post/projects/{project_id}/models

Local Server

https://api/projects/{project_id}/models

Response Samples

{"project": "string",
"model": "string",
"path": "string",
"hash": "string",
"tags": ["string"],
"trained_at": 0,
"version": "string",
"type": "string"}

Get a Rasa model with tag

Authorizations:
Path Parameters
tag
required		 string
Model tag

Responses

200 Zipped Rasa model

401 Authentication required to access this resource.

403 Not enough permissions to access this resource.

404 No model found for tag

get/models/tags/{tag}

Local Server

https://api/models/tags/{tag}

Response Samples

{"exception": "string",
"reasons": "string"}

Tag a Rasa model

This endpoint can be used to assign a tag to a Rasa model. The tag will be removed from any other model that might have it.

Path Parameters
project_id
required		 string
Example: default
Project ID
model
required		 string
Model name
tag
required		 string
Model tag

Responses

204 Tag created on model

404 Model was not found or is not compatible.

put/projects/{project_id}/models/{model}/tags/{tag}

Local Server

https://api/projects/{project_id}/models/{model}/tags/{tag}

Insights

Intent insights endpoints

Gets NLU insight reports

Authorizations:
Query Parameters
limit number
Default: null
offset number
Default: 0
status string Nullable
Default: null
Enum:"in_progress" "success" "failure" null
Filter by the report status

Responses

200 List of NLU insight reports

401 Authentication required to access this resource.

403 Not enough permissions to access this resource.

get/insights/nlu

Local Server

https://api/insights/nlu

Response Samples

[
{"id": 0,
"started_at": 0,
"finished_at": 0,
"status": "in_progress"}
]

Retrieves the Rasa Open Source cross-validation results for this report

Authorizations:
Path Parameters
insight_report_id
required		 number
ID of an insight report

Responses

200 Rasa Open Source cross-validation result

202 NLU insight calculation is in progress and not yet finished.

401 Authentication required to access this resource.

403 Not enough permissions to access this resource.

404 The NLU insight for the specified ID could not be found

get/insights/nlu/{insight_report_id}/evaluation

Local Server

https://api/insights/nlu/{insight_report_id}/evaluation

Response Samples

{"intent_evaluation": {
"report": {
"greet": {
"precision": 0.123,
"recall": 0.456,
"f1-score": 0.12,
"support": 100,
"confused_with": {
"chitchat": 3,
"nlu_fallback": 5
}},
"micro avg": {
"precision": 0.123,
"recall": 0.456,
"f1-score": 0.12,
"support": 100
},
"macro avg": {
"precision": 0.123,
"recall": 0.456,
"f1-score": 0.12,
"support": 100
},
"weighted avg": {
"precision": 0.123,
"recall": 0.456,
"f1-score": 0.12,
"support": 100
}},
"accuracy": 0.19047619047619047,
"f1_score": 0.06095238095238095,
"precision": 0.036281179138321996,
"predictions": [{
"intent": "greet",
"predicted": "greet",
"text": "hey",
"confidence": 0.9973567}],
"errors": [{
"text": "are you alright?",
"intent_response_key_target": "string",
"intent_response_key_prediction": {
"confidence": 0.6323,
"name": "greet"}}]
},
"response_selection_evaluation": {...},
"entity_evaluation": {...}
}

Updates the intent insights configuration

Authorizations:
Request Body schema: application/json
schedule string
Optional Crontab schedule for calculation insights. If null the scheduled background runs are disabled.
cross_validation_folds number
The number of folds to use when running the cross validation.
calculator_configuration object
The config for each insight linter. Map of linter names to list of parameters.

Responses

200 Updated the config

401 Authentication required to access this resource.

403 Not enough permissions to access this resource.

put/insights/config

Local Server

https://api/insights/config

Request Samples

{"schedule": "5 1 * * *",
"cross_validation_folds": 0,
"calculator_configuration": "{\n  \"MinimumExampleInsightCalculator\": {\n    \"required_number_of_examples_per_intent\": 100\n  },\n  \"rasax.community.services.insights.insight_calculator.ConfusionInsightCalculator\": {\n    \"top_x_percent_threshold\": 1\n  },\n}\n"
}

Response Samples

{"schedule": "5 1 * * *",
"cross_validation_folds": 0,
"calculator_configuration": "{\n  \"MinimumExampleInsightCalculator\": {\n    \"required_number_of_examples_per_intent\": 100\n  },\n  \"rasax.community.services.insights.insight_calculator.ConfusionInsightCalculator\": {\n    \"top_x_percent_threshold\": 1\n  },\n}\n"
}

Messages

Individual user messages with NLU predictions

Assign data tags to a message

Assign all data tags from the body of the request to the message. If data tags don’t exist yet, they will be created.

Path Parameters
project_id
required		 string
Example: default
Project ID
log_id
required		 string
Example: 1
Message ID
Request Body schema: application/json

Array ()

Responses

200 All tags were successfully assigned to a message

400 An error happened while assigning the tags

post/project/{project_id}/logs/{log_id}/data-tags

Local Server

https://api/project/{project_id}/logs/{log_id}/data-tags

Request Samples

[
{"id": 0,
"value": "string",
"color": "string"}
]

Remove tag from a message

Remove a tag from a message.

Path Parameters
project_id
required		 string
Example: default
Project ID
log_id
required		 string
Example: 1
Message ID
data_tag_id
required		 number
Example: data_tag_id
Data tag ID

Responses

204 Tag was successfully removed from a message

404 Message or tag were not found

delete/project/{project_id}/logs/{log_id}/data-tags/{data_tag_id}

Local Server

https://api/project/{project_id}/logs/{log_id}/data-tags/{data_tag_id}