# Rasa Enterprise HTTP API (1.1.3)

Download OpenAPI specification: [Download](https://legacy-docs-enterprise.rasa.com/docs/rasa-enterprise/spec/rasa-x-public.yml)

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<br>required | string |
| password<br>required | string |

### Responses

**200**
Success status

**401**
Authentication required to access this resource.

`post/auth`

Local Server

`https://api/auth`

### Request Samples
- Payload
Content type
application/json
```json
{"username": "string",
"password": "string"}
```

### Response Samples
- 200
- 401
Content type
application/json
```json
{"access_token": "string"}
```

## Git

Information about connected Git repositories

### Store credentials for a Git repository

##### Authorizations:

- [bearerAuth](https://legacy-docs-enterprise.rasa.com/docs/rasa-enterprise/pages/http-api/#section/Authentication/bearerAuth)
- [apiToken](https://legacy-docs-enterprise.rasa.com/docs/rasa-enterprise/pages/http-api/#section/Authentication/apiToken)

##### Request Body schema: application/json

Credentials for the repository

|     |     |
| --- | --- |
| id | integer<br>ID of the repository |
| name | string<br>Name of the repository |
| repository_url | string<br>URL to clone repository |
| ssh_key | string<br>SSH key which should be used to access a private repository |
| username | string<br>Username used to access the repository when HTTPS is used. This field is only used in Rasa Enterprise deployments. |
| password | string<br>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<br>Name of the Git service which is used |
| git_service_access_token | string<br>Access token which might be used to access the API of the Git service (e.g. to create pull requests) |
| target_branch | string<br>Name of the branch which should be pulled |
| use_generated_ssh_keys | boolean<br>If `True` used the private SSH key generated by Rasa Enterprise. |
| is_target_branch_protected | boolean<br>`True` if changes cannot be pushed directly to the target branch. |
| is_target_branch_compatible | boolean<br>`False` if current branch contains incompatible data |
| first_annotator_id | string<br>Name of the user who made the the first annotation since Integrated Version Control was in a clean state. |
| first_annotated_at | number<br>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
- Payload
Content type
application/json
```json
{"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
- 201
- 400
- 401
- 403
- 422
Content type
application/json
```json
{"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<br>required | string<br>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
- Payload
Content type
application/json
```json
{"license": "string"}
```

### Response Samples
- 200
- 401
- 403
Content type
application/json
```json
{"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
- 200
- 401
- 403
Content type
application/json
```json
{"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
- 401
- 403
Content type
application/json
```json
{"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
- 200
Content type
application/json
```json
{"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<br>Default: false<br>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
- 200
Content type
application/json
```json
{"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<br>Default: false<br>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
- 200
- 401
- 403
Content type
application/json
```json
{"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
- 401
- 403
Content type
application/json
```json
{"exception": "string",
"reasons": "string"}
```

## Conversations

Conversations between your assistant and end users

### Return data tags assigned to the conversation ID

##### Path Parameters

|     |     |
| --- | --- |
| conversation_id<br>required | string<br>Example: conversation_id<br>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
- 200
Content type
application/json
```json
[
{"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<br>required | string<br>Example: conversation_id<br>Sender ID |

##### Request Body schema: application/json

Array ()

|     |     |
| --- | --- |
| id | integer<br>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<br>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<br>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
- Payload
Content type
application/json
```json
[
{"id": 0,
"value": "string",
"color": "string"}
]
```

### Remove tag from a conversation

Remove a tag from a conversation.

##### Path Parameters

|     |     |
| --- | --- |
| conversation_id<br>required | string<br>Example: conversation_id<br>Sender ID |
| data_tag_id<br>required | number<br>Example: data_tag_id<br>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<br>required | string<br>Example: default<br>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
- 201
Content type
application/json
```json
{"project": "string",
"model": "string",
"path": "string",
"hash": "string",
"tags": ["string"],
"trained_at": 0,
"version": "string",
"type": "string"}
```

### Get a Rasa model with tag

##### Authorizations:

- [bearerAuth](https://legacy-docs-enterprise.rasa.com/docs/rasa-enterprise/pages/http-api/#section/Authentication/bearerAuth)
- [apiToken](https://legacy-docs-enterprise.rasa.com/docs/rasa-enterprise/pages/http-api/#section/Authentication/apiToken)
- [rasaXToken](https://legacy-docs-enterprise.rasa.com/docs/rasa-enterprise/pages/http-api/#section/Authentication/rasaXToken)

##### Path Parameters

|     |     |
| --- | --- |
| tag<br>required | string<br>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
- 401
- 403
Content type
application/json
```json
{"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<br>required | string<br>Example: default<br>Project ID |
| model<br>required | string<br>Model name |
| tag<br>required | string<br>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:

- [bearerAuth](https://legacy-docs-enterprise.rasa.com/docs/rasa-enterprise/pages/http-api/#section/Authentication/bearerAuth)

##### Query Parameters

|     |     |
| --- | --- |
| limit | number<br>Default: null |
| offset | number<br>Default: 0 |
| status | string Nullable <br>Default: null<br>Enum:"in_progress" "success" "failure" null<br>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
- 200
- 401
- 403
Content type
application/json
```json
[
{"id": 0,
"started_at": 0,
"finished_at": 0,
"status": "in_progress"}
]
```

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

##### Authorizations:

- [bearerAuth](https://legacy-docs-enterprise.rasa.com/docs/rasa-enterprise/pages/http-api/#section/Authentication/bearerAuth)

##### Path Parameters

|     |     |
| --- | --- |
| insight_report_id<br>required | number<br>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
- 200
- 202
- 401
- 403
Content type
application/json
```json
{"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:

- [bearerAuth](https://legacy-docs-enterprise.rasa.com/docs/rasa-enterprise/pages/http-api/#section/Authentication/bearerAuth)

##### Request Body schema: application/json

|     |     |
| --- | --- |
| schedule | string<br>Optional Crontab schedule for calculation insights. If null the scheduled background runs are disabled. |
| cross_validation_folds | number<br>The number of folds to use when running the cross validation. |
| calculator_configuration | object<br>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
- Payload
Content type
application/json
```json
{"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
- 200
- 401
- 403
Content type
application/json
```json
{"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<br>required | string<br>Example: default<br>Project ID |
| log_id<br>required | string<br>Example: 1<br>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
- Payload
Content type
application/json
```json
[
{"id": 0,
"value": "string",
"color": "string"}
]
```

### Remove tag from a message

Remove a tag from a message.

##### Path Parameters

|     |     |
| --- | --- |
| project_id<br>required | string<br>Example: default<br>Project ID |
| log_id<br>required | string<br>Example: 1<br>Message ID |
| data_tag_id<br>required | number<br>Example: data_tag_id<br>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}`