openapi: "3.0.1" info: title: "Rasa Core - Server Endpoints" version: "0.12.0" description: >- The Rasa Core server provides endpoints to retrieve trackers of conversations as well as endpoints to modify them. servers: - url: "http://localhost:5005" description: "Local development server" x-reuse: tracker: &tracker-example sender_id: default latest_event_time: 1537645578.314389 latest_input_channel: rest paused: false slots: {} followup_action: latest_message: text: hello entities: [] intent: confidence: 0.57 name: greet intent_ranking: - confidence: 0.57 name: greet - confidence: 0.33 name: goodbye events: - event: action name: action_listen timestamp: 1537645578.274815 - event: user input_channel: rest text: hello timestamp: 1537645578.314389 parse_data: text: hello entities: [] intent: confidence: 0.57 name: greet intent_ranking: - confidence: 0.57 name: greet - confidence: 0.33 name: goodbye paths: /: get: tags: - Status summary: Say Hello to Core description: >- This URL can be used as an endpoint to run health checks against. When Core is running this will return a 200. operationId: hello x-code-samples: - lang: shell source: curl http://localhost:8000 responses: 200: description: Up and running content: text/plain: schema: type: string description: hello text example: >- hello from Rasa Core: 0.12.0 /version: get: tags: - Status summary: Meta Info description: >- Metadata about the running Core instance. operationId: version responses: 200: description: Version of Core content: application/json: schema: type: object properties: version: type: string description: >- Core version number minimum_compatible_version: type: string description: >- Minimum version this Core is able to load models from example: version: 0.12.0 minimum_compatible_version: 0.12.0 /status: get: security: - TokenAuth: [] - JWT: [] tags: - Status summary: Status description: >- Information about the currently loaded agent. operationId: status responses: 200: description: Success content: application/json: schema: type: object properties: model_fingerprint: type: string description: >- Fingerprint of the loaded model is_ready: type: boolean description: >- Is there an agent loaded and is the server ready to receive user messages. example: model_fingerprint: 4523wyfgr4q2 is_ready: true /conversations: get: security: - TokenAuth: [] - JWT: [] tags: - Conversation summary: List sender ids of all conversations description: >- Lists the sender ids of all the available conversations. The trackers of the conversations are not returned and need to be fetched individually. deprecated: true operationId: listConversations responses: 200: description: Success content: application/json: schema: type: array items: type: string description: sender id example: - "default" - "rasa" - "34235421" /conversations/{sender_id}/tracker: get: security: - TokenAuth: [] - JWT: [] tags: - Tracker summary: Retrieve a conversations tracker description: >- 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. operationId: getTracker parameters: - $ref: '#/components/parameters/senderId' - in: query name: ignore_restarts description: >- Deprecated, use `include_events`. Specify if only restarts after the most recent restart should be included. deprecated: true schema: type: string default: false - in: query name: events description: >- Deprecated, use `include_events`. Specify if the returned tracker should contain the event history. deprecated: true schema: type: boolean default: true - $ref: '#/components/parameters/includeEvents' responses: 200: $ref: '#/components/responses/200Tracker' 404: description: Invalid event verbosity format content: application/json: schema: $ref: '#/components/schemas/Error' example: version: "0.12.0" status: "failure" message: >- Invalid parameter value for 'include_events'. Should be one of ALL, AFTER_RESTART, APPLIED, NONE reason: "InvalidParameter" code: 400 403: $ref: '#/components/responses/403Permissions' 503: description: Tracker store is unavailable content: application/json: schema: $ref: '#/components/schemas/Error' example: version: "0.12.0" status: "failure" message: >- No tracker store available. reason: "NoTrackerStore" code: 503 /conversations/{sender_id}/story: get: security: - TokenAuth: [] - JWT: [] tags: - Story summary: Retrieve an end-to-end story corresponding to a conversation description: >- The story represents the whole conversation, in end-to-end format. This can be posted to the /evaluate endpoint and used as a test. operationId: getStory parameters: - $ref: '#/components/parameters/senderId' responses: 200: $ref: '#/components/responses/200Story' 403: $ref: '#/components/responses/403Permissions' 503: description: Tracker store is unavailable content: application/json: schema: $ref: '#/components/schemas/Error' example: version: "0.12.0" status: "failure" message: >- No tracker store available. reason: "NoTrackerStore" code: 503 /conversations/{sender_id}/execute: post: security: - TokenAuth: [] - JWT: [] tags: - Tracker summary: Run an action in a conversation. description: >- Runs the action, calling the action server if necessary Any responses sent by the executed action will be returned as part of the endpoints result, they will not be sent over a connected output channel. operationId: executeAction parameters: - $ref: '#/components/parameters/senderId' - $ref: '#/components/parameters/includeEvents' requestBody: required: true content: application/json: schema: type: object properties: action: description: >- Name of the action to be executed type: string required: ["action"] example: action: utter_greet responses: 200: description: Success content: application/json: schema: type: object properties: tracker: $ref: '#/components/schemas/Tracker' messages: type: array items: $ref: '#/components/schemas/BotMessage' 400: description: Invalid request format content: application/json: schema: $ref: '#/components/schemas/Error' example: version: "0.12.0" status: "failure" message: >- Invalid Request format. reason: "InvalidParameter" code: 400 403: $ref: '#/components/responses/403Permissions' 500: $ref: '#/components/responses/500Action' /conversations/{sender_id}/predict: post: security: - TokenAuth: [] - JWT: [] tags: - Tracker summary: Predict the next action description: >- Runs the conversations tracker through the models policies to predict the next action. The action is not executed, just returned. The state of the tracker is not modified. operationId: predictAction parameters: - $ref: '#/components/parameters/senderId' - $ref: '#/components/parameters/includeEvents' responses: 200: description: Success content: application/json: schema: $ref: '#/components/schemas/PredictResult' examples: PredictResult: $ref: '#/components/examples/PredictResult' 403: $ref: '#/components/responses/403Permissions' 500: $ref: '#/components/responses/500Action' /conversations/{sender_id}/respond: get: security: - TokenAuth: [] - JWT: [] tags: - Tracker summary: Send user message deprecated: true description: >- Deprecated, rather consider using the `RestInput` channel. When added to Core, it will provide you an endpoint at `/webhooks/rest/webhook` that returns the same output as this endpoint. The only difference is, that you need to send the message as `{"message": ""}`. Notify the dialogue engine that the user posted a new message, and get a list of response messages the bot should send back. operationId: respond parameters: - $ref: '#/components/parameters/senderId' - in: query name: query description: >- User message text schema: type: string example: hello responses: 200: description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/BotMessage' 400: description: No user message content: application/json: schema: type: object properties: error: description: Error message type: string example: { "error": "Invalid respond parameter specified."} 403: $ref: '#/components/responses/403Permissions' 500: $ref: '#/components/responses/500Action' /conversations/{sender_id}/tracker/events: post: security: - TokenAuth: [] - JWT: [] tags: - Tracker summary: Append an event to a tracker description: >- Append a new event to the tracker state of the conversation. Any existing events will be kept and the new events will be appended, updating the existing state. operationId: appendEvent parameters: - $ref: '#/components/parameters/senderId' - $ref: '#/components/parameters/includeEvents' requestBody: $ref: '#/components/requestBodies/Event' responses: 200: $ref: '#/components/responses/200Tracker' 403: $ref: '#/components/responses/403Permissions' put: security: - TokenAuth: [] - JWT: [] tags: - Tracker summary: Replace a trackers events description: >- Replace all of the 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. operationId: replaceEvents parameters: - $ref: '#/components/parameters/senderId' - $ref: '#/components/parameters/includeEvents' requestBody: required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/Event' examples: Events: $ref: '#/components/examples/Events' responses: 200: $ref: '#/components/responses/200Tracker' 400: $ref: '#/components/responses/400Events' 403: $ref: '#/components/responses/403Permissions' /conversations/{sender_id}/messages: post: security: - TokenAuth: [] - JWT: [] tags: - Tracker summary: Add a message to a tracker description: >- 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](https://rasa.com/docs/core/server.html#operation/predictAction). operationId: addMessage parameters: - $ref: '#/components/parameters/senderId' - $ref: '#/components/parameters/includeEvents' requestBody: required: true content: application/json: schema: type: object properties: text: type: string description: >- Message text sender: type: string description: >- Origin of the message - who sent it enum: - user parse_data: $ref: '#/components/schemas/ParseData' required: ["message", "sender"] example: sender: user message: hello parse_data: text: hello entities: [] intent: confidence: 0.57 name: greet intent_ranking: - confidence: 0.57 name: greet - confidence: 0.33 name: goodbye responses: 200: $ref: '#/components/responses/200Tracker' 403: $ref: '#/components/responses/403Permissions' 500: description: Message Exception content: application/json: schema: $ref: '#/components/schemas/Error' example: version: "0.12.0" status: "failure" message: >- An exception occurred while logging the message reason: "MessageException" code: 500 /finetune: post: security: - TokenAuth: [] - JWT: [] tags: - Model summary: Fintune ML model description: >- Continue the ML training of a model on the provided events. **Fine tuning only works, if the model has been trained in memory before. It does not work if the model was persisted and loaded again.** operationId: predictTemp requestBody: required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/Event' examples: Events: $ref: '#/components/examples/Events' responses: 204: description: Success 400: $ref: '#/components/responses/400Events' 500: $ref: '#/components/responses/500Action' /evaluate: post: security: - TokenAuth: [] - JWT: [] tags: - Model summary: Evaluate stories description: >- Evaluates one or multiple stories against the currently loaded model. operationId: evaluateStories parameters: - $ref: '#/components/parameters/e2e' requestBody: required: true content: text/markdown: schema: type: string example: >- ## story_00055028 * greet - utter_ask_howcanhelp * inform{"cuisine": "indian", "people": "two", "price": "moderate"} - utter_on_it - utter_ask_location responses: 200: description: Success content: application/json: schema: $ref: '#/components/schemas/EvaluationResult' examples: PredictResult: $ref: '#/components/examples/EvaluationResult' 400: $ref: '#/components/responses/400Evaluation' /predict: post: security: - TokenAuth: [] - JWT: [] tags: - Model summary: Predict an action on a temporary state description: >- Predicts the next action on the tracker state as it is posted to this endpoint. Core 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. operationId: predictTemp parameters: - $ref: '#/components/parameters/includeEvents' requestBody: required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/Event' example: - event: action name: action_listen - event: user parse_data: entities: [] intent: confidence: 0.57 name: greet text: hello text: hello responses: 200: description: Success content: application/json: schema: $ref: '#/components/schemas/PredictResult' examples: PredictResult: $ref: '#/components/examples/PredictResult' 403: $ref: '#/components/responses/403Permissions' 500: $ref: '#/components/responses/500Action' /domain: get: security: - TokenAuth: [] - JWT: [] tags: - Domain summary: Retrieve the loaded domain description: >- Return the domain specification the currently loaded model is using. operationId: getDomain responses: 200: description: Success content: application/json: schema: $ref: '#/components/schemas/Domain' application/yaml: schema: $ref: '#/components/schemas/Domain' /model: post: security: - TokenAuth: [] - JWT: [] tags: - Model summary: Upload a trained model description: >- Upload a trained model to the Core server. The server will unzip the uploaded file and try to load the model this will replace the previously loaded model. operationId: uploadModel requestBody: content: multipart/form-data: schema: properties: model: description: Zipped model file type: string format: binary responses: 204: description: Success 400: description: No Model content: application/json: schema: $ref: '#/components/schemas/Error' example: version: "0.12.0" status: "failure" message: >- No agent loaded. reason: "NoAgent" code: 400 components: securitySchemes: TokenAuth: type: apiKey in: query name: token JWT: type: http scheme: bearer bearerFormat: JWT parameters: senderId: in: path name: sender_id example: default description: Id of the conversation schema: type: string required: true includeEvents: in: query name: include_events description: >- Specify which events of the tracker the response should contain. schema: type: string default: AFTER_RESTART enum: - ALL - APPLIED - AFTER_RESTART - NONE e2e: in: path name: e2e description: Perform an end-to-end evaluation on the posted stories schema: type: boolean default: false required: false requestBodies: Event: required: true content: application/json: schema: $ref: '#/components/schemas/Event' examples: action: $ref: '#/components/examples/ActionExecuted' agent: $ref: '#/components/examples/AgentUttered' bot: $ref: '#/components/examples/BotUttered' export: $ref: '#/components/examples/StoryExported' followup: $ref: '#/components/examples/FollowupAction' pause: $ref: '#/components/examples/ConversationPaused' reminder: $ref: '#/components/examples/ReminderScheduled' reset_slots: $ref: '#/components/examples/AllSlotsReset' restart: $ref: '#/components/examples/Restarted' resume: $ref: '#/components/examples/ConversationResumed' rewind: $ref: '#/components/examples/UserUtteranceReverted' slot: $ref: '#/components/examples/SlotSet' undo: $ref: '#/components/examples/ActionReverted' user: $ref: '#/components/examples/UserUttered' examples: Tracker: value: <<: *tracker-example Events: value: - event: action name: action_listen - event: user text: hello parse_data: entities: [] intent: confidence: 0.57 name: greet text: hello ActionExecuted: value: event: action name: utter_greet ActionReverted: value: event: undo AgentUttered: value: event: agent text: Hello AllSlotsReset: value: event: rewind BotUttered: value: event: bot text: Hello there ConversationPaused: value: event: pause ConversationResumed: value: event: resume FollowupAction: value: event: followup name: utter_greet ReminderScheduled: value: event: reminder action: utter_greet date_time: "2018-09-22T20:57:39.835946" name: my_reminder kill_on_user_msg: true Restarted: value: event: restart SlotSet: value: event: slot name: cuisine value: italian StoryExported: value: event: export UserUtteranceReverted: value: event: rewind UserUttered: value: event: user text: I like mexican food parse_data: text: I like mexican food intent: name: restaurant_search confidence: 0.85 entities: - start: 7 end: 14 value: mexican entity: cuisine PredictResult: value: scores: - action: utter_greet score: 0.85 - action: action_listen score: 0.15 policy: "policy_2_KerasPolicy" tracker: <<: *tracker-example EvaluationResult: value: accuracy: 0.9 f1: 0.9333333333333333 in_training_data_fraction: 0.8571428571428571 precision: 1.0 is_end_to_end_evaluation: true actions: - action: utter_ask_howcanhelp confidence: 1.0 policy: policy_0_MemoizationPolicy predicted: utter_ask_howcanhelp - action: action_listen confidence: 0.7885686478768559 policy: policy_1_RestaurantPolicy predicted: utter_ask_numpeople report: >- # classification report precision recall f1-score support action_listen 1.00 1.00 1.00 3 greet 1.00 1.00 1.00 1 inform 1.00 1.00 1.00 2 utter_ask_howcanhelp 1.00 1.00 1.00 1 utter_ask_location 1.00 1.00 1.00 1 utter_ask_numpeople 0.00 0.00 0.00 0 utter_on_it 1.00 0.50 0.67 2 avg / total 1.00 0.90 0.93 10 responses: 200Tracker: description: Success content: application/json: schema: $ref: '#/components/schemas/Tracker' examples: Tracker: $ref: '#/components/examples/Tracker' 200Story: description: Success content: text/markdown: example: >- ## story_00055028 * greet: hello - utter_ask_howcanhelp * inform: I'm looking for a [moderately priced](price:moderate) [Indian](cuisine) restaurant for [two](people) people - utter_on_it - utter_ask_location 500Action: description: Action Exception content: application/json: schema: $ref: '#/components/schemas/Error' example: version: "0.12.0" status: "failure" message: >- An exception occurred while running the action reason: "ActionException" code: 500 400Events: description: Invalid Events content: application/json: schema: $ref: '#/components/schemas/Error' example: version: "0.12.0" status: "failure" message: >- Supplied events are not valid. reason: "InvalidParameter" code: 400 400Evaluation: description: Failed Evaluation content: application/json: schema: $ref: '#/components/schemas/Error' example: version: "0.12.0" status: "failure" message: >- Evaluation could not be created. reason: "FailedEvaluation" code: 400 403Permissions: description: User has insufficient permission. content: application/json: schema: $ref: '#/components/schemas/Error' example: version: "0.12.0" status: "failure" message: >- User has insufficient permission to access resource. code: 403 schemas: Entity: type: object description: Entities within a message properties: start: type: integer description: Char offset of the start end: type: integer description: Char offset of the end value: type: string description: Found value for entity entity: type: string description: Type of the entity confidence: type: number required: ["start", "end", "value", "entity"] Intent: type: object description: Intent of the text properties: confidence: type: number description: Confidence of the intent name: type: string description: Intent name required: ["confidence", "name"] ParseData: type: object properties: entites: type: array description: Parsed entities items: $ref: '#/components/schemas/Entity' intent: $ref: '#/components/schemas/Intent' intent_ranking: type: array description: Scores of all intents items: $ref: '#/components/schemas/Intent' text: type: string description: Text of the message description: >- NLU parser information. If set, message will not be passed through NLU, but instead this parsing information will be used. required: ["text"] action: allOf: - $ref: '#/components/schemas/Event' - type: object properties: name: type: string description: Action name policy: type: string description: Policy that predicted the action confidence: type: number description: Confidence of the prediction required: ["event", "name"] agent: allOf: - $ref: '#/components/schemas/Event' - type: object properties: text: type: string description: Message data: type: object description: Additional data required: ["event", "text"] bot: allOf: - $ref: '#/components/schemas/Event' - type: object properties: data: type: object nullable: true description: Additional data text: type: string description: Message required: ["event", "text"] export: allOf: - $ref: '#/components/schemas/Event' followup: allOf: - $ref: '#/components/schemas/Event' - type: object properties: name: type: string description: Action to be triggered required: ["event", "name"] pause: allOf: - $ref: '#/components/schemas/Event' reminder: allOf: - $ref: '#/components/schemas/Event' - type: object properties: action: type: string description: Action to be triggered date_time: type: string description: Trigger date name: type: string description: Name of the reminder kill_on_user_msg: default: true type: boolean description: Cancel the reminder if there is a user message required: ["event", "action", "date_time"] reset_slots: allOf: - $ref: '#/components/schemas/Event' restart: allOf: - $ref: '#/components/schemas/Event' resume: allOf: - $ref: '#/components/schemas/Event' rewind: allOf: - $ref: '#/components/schemas/Event' slot: allOf: - $ref: '#/components/schemas/Event' - type: object properties: name: type: string description: Name of slot value: type: string description: Value of slot undo: allOf: - $ref: '#/components/schemas/Event' user: description: A message from a user allOf: - $ref: '#/components/schemas/Event' - type: object properties: parse_data: $ref: '#/components/schemas/ParseData' text: type: string required: ["event", "text"] Event: type: object properties: event: type: string description: Event name timestamp: type: integer description: Time of application required: ["event"] discriminator: propertyName: event Domain: type: object properties: config: type: object description: Addional option properties: store_entities_as_slots: type: boolean description: Store all entites as slot when found intents: type: array description: All intent names and properties items: type: object entities: type: array description: All entity names items: type: string slots: description: Slot names and configuration type: object templates: description: Bot response templates type: object actions: description: Available action names type: array items: type: string BotMessage: type: object properties: recipient_id: type: string description: Id of the message receiver text: type: string description: Message image: type: string description: Image URL buttons: type: array description: Quick reply buttons items: type: object properties: title: type: string description: Button caption payload: type: string description: Payload to be sent if button is clicked attachement: type: array description: Additional information items: type: object properties: title: type: string description: Attachement caption payload: type: string description: Attachement payload Tracker: type: object description: A conversations state properties: sender_id: type: string description: Id of the conversation slots: type: array description: Slot values items: type: object latest_message: $ref: '#/components/schemas/ParseData' latest_event_time: type: number description: Most recent event time followup_action: type: string description: Deterministic scheduled next action paused: type: boolean description: Bot is pasued events: type: array description: Event history items: $ref: '#/components/schemas/Event' latest_input_channel: type: string description: Communication channel Error: type: object properties: version: type: string description: Core version status: type: string enum: ["failure"] description: Status of the requested action message: type: string description: Error message reason: type: string description: Error category details: type: object description: Additional error information help: type: string description: Optional URL to additonal material code: type: number description: HTTP status code PredictResult: type: object properties: scores: type: array description: Prediction results items: type: object properties: action: type: string description: Action name score: type: number description: Assigned score policy: type: string description: >- Policy which predicted the most likely action tracker: $ref: '#/components/schemas/Tracker' EvaluationResult: type: object properties: actions: type: array items: type: object properties: action: type: string description: Name of the actual action predicted: type: string description: Name of the predicted action policy: type: string description: Machine-learning policy used in the prediction confidence: type: string description: Confidence score of the prediction description: >- Accuracy of the classification, http://scikit-learn.org/stable/modules/generated/sklearn.metrics.accuracy_score.html is_end_to_end_evaluation: type: bool description: True if evaluation is end-to-end, false otherwise precision: type: number description: >- Precision of the classification, see http://scikit-learn.org/stable/modules/generated/sklearn.metrics.precision_score.html f1: type: number description: >- F1 score of the classification, http://scikit-learn.org/stable/modules/generated/sklearn.metrics.precision_score.html accuracy: type: number description: >- Accuracy of the classification, http://scikit-learn.org/stable/modules/generated/sklearn.metrics.accuracy_score.html in_training_data_fraction: type: number description: >- Fraction of stories that are present in the training data of the model loaded at evaluation time. report: type: string description: >- Sklearn classifcation report, see http://scikit-learn.org/stable/modules/generated/sklearn.metrics.classification_report.html