In order to use the tools that Superface offers in your own Agent you don't have to use lots of different endpoints. In fact, using Superface significantly cut down the amount of code you need to write to communicate with external APIs.

/fd

GET <https://pod.superface.ai/api/hub/fd>

Returns a list of the functions currently available for use by users. The API token that is used to authenticate this endpoint will be used to determine which Superface account is used.

Example

curl -H "Authorization: Bearer <auth_token>" <https://pod.superface.ai/api/hub/fd>

Response

The response will be an array of function objects similar to this example for retrieving the current weather from Wttr.in.

[
  {
    "type": "function",
    "function": {
      "name": "weather__current-weather__CurrentWeather",
      "description": "Retrieve current weather information for a specified location.\\n",
      "parameters": {
        "type": "object",
        "required": ["city"],
        "properties": {
          "city": {
            "type": "string",
            "nullable": false,
            "description": "Name of the city including state and country, e.g.: \\"Prague, Czech Republic\\" or \\"New York City, NY, USA\\"",
            "title": "city"
          },
          "units": {
            "enum": ["C", "F", "K"],
            "description": "Units used to represent temperature - Fahrenheit, Celsius, Kelvin\\nCelsius by default",
            "title": "units"
          }
        },
        "nullable": true
      }
    }
  }
]

/session

POST <https://pod.superface.ai/api/hub/session>

Users need to configure their own access credentials for the tools that you offer. In order to do this, we provide a temporary URL that you can use to prompt your users to set up their access.

This URL will expire 15 minutes after generation.

In order to ensure that users can configure, edit or remove access at any time. You need to assign them an ID and use it when calling /session. We recommend that your user IDs are formatted as follows: your_agent_name|unique_user_id and that you store this for your users so they can access their configuration in future.

Example

curl -X POST \\
    -H "Content-Type: application/json" \\
    -H "Authorization: Bearer <auth_token>" \\
    -H "x-superface-user-id: <your_agent_name|unique_user_id>" \\
    <https://pod.superface.ai/api/hub/session>

Response

{
  "status": "success",
  "configuration_url": "<https://pod.superface.ai/api/hub/session/psxis99ux9>",
  "assistant_hint": "Tell user to go to URL at 'configuration_url' to configure to open configuration. Always show the whole URL to the user. The 'configuration_url' expires in 15 minutes."
}

/perform

POST <https://pod.superface.ai/api/hub/perform/><tool_and_function_name>