swagger: "2.0"
info:
  description: "This is the Furhat client, use it to generate a server. Or generate a client. Find out more at https://furhatrobotics.com , https://furhat.io or https://docs.furhat.io"
  version: "1.0.0"
  title: "Furhat client"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "support@furhatrobotics.com"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "localhost:54321"
tags:
  - name: "furhat"
    description: "Control your favorite social robot"
    externalDocs:
      description: "Find out more"
      url: "http://docs.furhat.io"
schemes:
  - "http"
paths:
  /furhat:
    get:
      description: "Used to verify if the server is running, return \"hello world\" upon success"
      summary: "Test connection"
      tags:
        - "furhat"
      responses:
        200:
          description: "Status update"
  /furhat/gestures:
    get:
      description: "Returns a JSON array with all gestures on the system (names + duration)."
      summary: "Get all gestures"
      produces:
        - "application/json"
      tags:
        - "furhat"
      responses:
        200:
          description: "A list of possible gestures"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Gesture"
  /furhat/voice:
    post:
      summary: "Set the voice of the robot"
      description: "Sets the voice of the robot using the name of the voice, can be requested by doing a GET request on this endpoint."
      tags:
        - "actions"
      parameters:
        - in: "query"
          name: "voicename"
          description: "The name of the voice"
          type: "string"
          required: true
      responses:
        200:
          description: "Successfull operation"
          schema:
            $ref: "#/definitions/Status"
    get:
      summary: "Get all the voices on the robot"
      description: "Returns a JSON array with voice names + languages."
      tags:
        - "furhat"
      responses:
        200:
          description: "Success"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Voice"
  /furhat/users:
    get:
      tags:
        - "furhat"
      summary: "Get current users"
      description: "Get all current users (max: 2). Returns a JSON array containg Users (Rotation, Location, id)."
      produces:
        - "application/json"
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/User"
            example:
              id: "virtual-user-2"
              rotation: {
                x: 0.1,
                y: 5.2,
                z: 0.2
              }
              location: {
                x: -25.1,
                y: -5.2,
                z: 7.2
              }
  /furhat/actions/say:
    post:
      summary: "Make the robot speak"
      description: "Makes the robot speak by either using text, or a URL (linking to a.wav file). If generatelipsync=true, it uses a .pho file hosted on the same url, or generates phonemes by itself."
      tags:
        - "actions"
      produces:
        - "application/json"
      parameters:
        - in: "query"
          description: "A string depicting a utterance the robot should say."
          name: "utterance"
          type: "string"
        - in: "query"
          description: "A url link to a audio file (.wav)"
          name: "url"
          type: "string"
        - in: "query"
          description: "If a URL is provided, indicate if lipsync files should be generated/looked for."
          name: "generatelipsync"
          type: "boolean"
        - in: "query"
          description: "Stops the current speech of the robot."
          name: "abortcurrentspeech"
          type: "boolean"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Status"
  /furhat/actions/attend:
    post:
      summary: "Attend a user/location"
      description: "Provides 3 modes of attention.
      \n 1. Attend user based on enum (closest, other, random)
      \n 2. Attend user based on it's id (can be retrieved by using /furhat/users)
      \n 3. Attend location based on coordinates (x,y,z)"
      tags:
        - "actions"
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "what"
          description: "Make furhat attend a user"
          type: "array"
          items:
            enum:
              - "CLOSEST_USER"
              - "OTHER_USER"
              - "RANDOM_USER"
        - in: "query"
          name: "who"
          description: "Make furhat attend specified user"
          type: "string"
        - in: "query"
          name: "where"
          description: "Make furhat attend location, usage: x,y,z. Example -20.0,-5.0,23.0"
          type: "string"
      responses:
        200:
          description: "Successfull operation"
          schema:
            $ref: "#/definitions/Status"
  /furhat/actions/face:
    post:
      summary: "Change the texture and/or model"
      description: "Changes the texture or model, based on the model/texture name. Case sensitive.
      Names can be retrieved from the web interface"
      tags:
        - "actions"
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "model"
          description: "Change the model of the robot"
          type: "string"
        - in: "query"
          name: "texture"
          description: "Change the texture of the robot"
          type: "string"
      responses:
        200:
          description: "Successfull operation"
          schema:
            $ref: "#/definitions/Status"
  /furhat/actions/gesture:
    post:
      summary: "Perform a gesture"
      description: "Performs a gesture based on
      \n 1. Gesture name (retrieve by GET request to /furhat/gestures)
      \n 2. Gesture definition, see example"
      tags:
        - "actions"
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "name"
          description: "The gesture to do"
          type: "string"
        - in: "body"
          name: "gesturedefinition"
          schema:
            $ref: "#/definitions/GestureDefinition"
      responses:
        200:
          description: "Successfull operation"
          schema:
            $ref: "#/definitions/Status"
        400:
          description: "Parameters are wrong"
          schema:
            $ref: "#/definitions/Status"
  /furhat/actions/listen:
    get:
      summary: "Make the robot listen, and get speech results"
      description: "Blocking call to get user speech input, language defaults to english_US. Language parameter can be used to provide a different language. Return values can be found in the Status object as message and can be:
      \n - User speech
      \n - SILENCE
      \n - INTERRUPTED
      \n - FAILED
      "
      tags:
        - "actions"
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: "language"
          description: "The language to listen for, defaults to en-US"
          type: "string"
      responses:
        200:
          description: "Successfull operation"
          schema:
            $ref: "#/definitions/Status"
  /furhat/actions/listen/stop:
    post:
      summary: "Make the robot stop listening"
      description: "Aborts the listen"
      tags:
        - "actions"
      responses:
        200:
          description: "Successfull operation"
          schema:
            $ref: "#/definitions/Status"
  /furhat/actions/led:
    post:
      summary: "Change the colour of the LED strip"
      description: "Changes the LED strip of the robot, colours can be between 0-255 (above 255 is changed to 255). Any parameter not provided defaults to 0."
      tags:
        - "actions"
      parameters:
        - in: "query"
          name: "red"
          description: "The amount of red"
          type: "integer"
        - in: "query"
          name: "green"
          description: "The amount of green"
          type: "integer"
        - in: "query"
          name: "blue"
          description: "The amount of blue"
          type: "integer"
      responses:
        200:
          description: "Successfull operation"
          schema:
            $ref: "#/definitions/Status"
  /furhat/actions/say/stop:
    post:
      summary: "Make the robot stop talking"
      description: "Stops the current speech."
      tags:
        - "actions"
      responses:
        200:
          description: "Successfull operation"
          schema:
            $ref: "#/definitions/Status"
definitions:
  Status:
    type: "object"
    properties:
      success:
        type: "boolean"
      message:
        type: "string"
  Gesture:
    type: "object"
    properties:
      name:
        type: "string"
      duration:
        type: "integer"
        format: "double"
  User:
    type: "object"
    properties:
      id:
        type: "string"
      rotation:
        $ref: "#/definitions/Rotation"
      location:
        $ref: "#/definitions/Location"
  Location:
    type: "object"
    properties:
      x:
        type: "number"
        format: "double"
      y:
        type: "number"
        format: "double"
      z:
        type: "number"
        format: "double"
  Voice:
    type: "object"
    properties:
      name:
        type: "string"
      language:
        type: "string"
  Rotation:
    type: "object"
    properties:
      x:
        type: "number"
        format: "double"
      y:
        type: "number"
        format: "double"
      z:
        type: "number"
        format: "double"
  GestureDefinition:
    type: "object"
    description: "The class name needs to be there, and be furhatos.gestures.Gesture otherwise it won't be parsed as a gesture."
    properties:
      name:
        type: "string"
      frames:
        type: "array"
        items:
          $ref: "#/definitions/Frame"
      class:
        type: "string"
        example: "furhatos.gestures.Gesture"
  Frame:
    description: "A list of times can be provided, at those times the params will be executed."
    type: "object"
    properties:
      time:
        type: "array"
        items:
          type: "number"
          format: "double"
      params:
        $ref: "#/definitions/BasicParam"
  BasicParam:
    description: "All supported parameters can be found at https://docs.furhat.io ."
    type: "object"
    additionalProperties: true
    example:
      EXPR_ANGER: 0.95
      reset: true
externalDocs:
  description: "Find out more about Furhat"
  url: "http://furhatrobotics.com"
