rest_api.md 5.8 KB

Rest API

Kalliope provides the REST API to manage the synapses. For configuring the API refer to the settings documentation.

Synapse API

Curl examples

Note: --user is only needed if password_protected is True

Get Kalliope's version

Normal response codes: 200 Error response codes: unauthorized(401) Curl command:

curl -i --user admin:secret -X GET  http://localhost:5000/

Output example:

{
  "Kalliope version": "0.4.2"
}

List synapses

Normal response codes: 200 Error response codes: unauthorized(401), itemNotFound(404) Curl command:

curl -i --user admin:secret -X GET  http://localhost:5000/synapses

Output example:

{
  "synapses": [
    [
      {
        "name": "stop-kalliope",
        "neurons": [
          {
            "say": {
              "message": "Good bye"
            }
          },
          "kill_switch"
        ],
        "signals": [
          {
            "order": "close"
          }
        ]
      }
    ],
    [
      {
        "name": "say-hello",
        "neurons": [
          {
            "say": {
              "message": [
                "Bonjour monsieur"
              ]
            }
          }
        ],
        "signals": [
          {
            "order": "bonjour"
          }
        ]
      }
    ]
  ]
}

Show synapse details

Normal response codes: 200 Error response codes: unauthorized(401), itemNotFound(404) Curl command:

curl -i --user admin:secret -X GET  http://localhost:5000/synapses/say-hello

Output example:

{
  "synapses": {
    "name": "say-hello",
    "neurons": [
      {
        "say": {
          "message": [
            "Bonjour monsieur"
          ]
        }
      }
    ],
    "signals": [
      {
        "order": "bonjour"
      }
    ]
  }
}

Run a synapse by its name

Normal response codes: 201 Error response codes: unauthorized(401), itemNotFound(404) Curl command:

curl -i --user admin:secret -X POST  http://localhost:5000/synapses/start/id/say-hello

Output example:

{
  "matched_synapses": [
    {
      "matched_order": null,
      "neuron_module_list": [
        {
          "generated_message": "Bonjour monsieur",
          "neuron_name": "Say"
        }
      ],
      "synapse_name": "say-hello-fr"
    }
  ],
  "status": "complete",
  "user_order": null
}

Run a synapse from an order

Normal response codes: 201 Error response codes: unauthorized(401), itemNotFound(404)

Curl command:

curl -i --user admin:secret -H "Content-Type: application/json" -X POST -d '{"order":"my order"}' http://localhost:5000/synapses/start/order

If the order contains accent or quotes, use a file for testing with curl

cat post.json 
{"order":"j'aime"}

Then

curl -i --user admin:secret -H "Content-Type: application/json" -X POST --data @post.json http://localhost:5000/synapses/start/order

Output example if the order have matched and so launched synapses:

{
  "matched_synapses": [
    {
      "matched_order": "Bonjour",
      "neuron_module_list": [
        {
          "generated_message": "Bonjour monsieur",
          "neuron_name": "Say"
        }
      ],
      "synapse_name": "say-hello-fr"
    }
  ],
  "status": "complete",
  "user_order": "bonjour"
}

If the order haven't match any synapses it will try to run the default synapse if it exists in your settings:

{
  "matched_synapses": [
    {
      "matched_order": null,
      "neuron_module_list": [
        {
          "generated_message": "Je n'ai pas compris votre ordre",
          "neuron_name": "Say"
        }
      ],
      "synapse_name": "default-synapse"
    }
  ],
  "status": "complete",
  "user_order": "not existing order"
}

Or return an empty list of matched synapse

{
  "matched_synapses": [],
  "status": null,
  "user_order": "not existing order"
}

Run a synapse from an audio file

Normal response codes: 201 Error response codes: unauthorized(401), itemNotFound(404)

The audio file must use WAV or MP3 extension.

Curl command:

curl -i --user admin:secret -X POST  http://localhost:5000/synapses/start/audio -F "file=@/home/nico/Desktop/input.wav"

Output example if the order inside the audio have matched and so launched synapses:

{
  "matched_synapses": [
    {
      "matched_order": "Bonjour",
      "neuron_module_list": [
        {
          "generated_message": "Bonjour monsieur",
          "neuron_name": "Say"
        }
      ],
      "synapse_name": "say-hello-fr"
    }
  ],
  "status": "complete",
  "user_order": "bonjour"
}

If the order haven't match any synapses it will try to run the default synapse if it exists in your settings:

{
  "matched_synapses": [
    {
      "matched_order": null,
      "neuron_module_list": [
        {
          "generated_message": "Je n'ai pas compris votre ordre",
          "neuron_name": "Say"
        }
      ],
      "synapse_name": "default-synapse"
    }
  ],
  "status": "complete",
  "user_order": "not existing order"
}

Or return an empty list of matched synapse

{
  "matched_synapses": [],
  "status": null,
  "user_order": "not existing order"
}
Method URL Action
GET / Get kaliope version
GET /synapses List synapses
GET /synapses/ Get synapse details by name
POST /synapses/start/id/ Run a synapse by its name
POST /synapses/start/order Run a synapse from a text order
POST /synapses/start/audio Run a synapse from an audio sample