Skip to main content

Assistant APIs

Assistant APIs allow you to securely connect your assistants to external systems and services without exposing sensitive credentials in your prompts. When you configure an API in Deepdesk, the assistant can use the call_api tool to access it while keeping authentication details secure.

How Assistant APIs Work​

  1. You configure the API connection once in the Deepdesk admin interface
  2. The connection details (including authentication credentials) are stored securely
  3. Assistants reference the API by its code when using the call_api tool
  4. Authentication is handled automatically in the background

This approach has several key advantages:

  • Sensitive credentials never appear in prompts or LLM context
  • API configurations can be updated without changing assistant instructions
  • Multiple assistants can use the same API connections
  • Authentication tokens can be refreshed centrally

Authentication Methods​

Deepdesk supports three authentication methods for Assistant APIs:

No Auth​

Use this option when connecting to APIs that:

  • Are publicly accessible
  • Don't require authentication
  • Handle authentication through other means (e.g., IP whitelisting)

Configuration requires:

  • API Code (unique identifier)
  • Base URL

OAuth2​

Use this option for APIs that implement OAuth 2.0 authentication, which is common for many modern web services. OAuth2 allows secure access without storing permanent credentials.

Configuration requires:

  • API Code
  • Base URL
  • Client ID
  • Client Secret
  • Token URL
  • Scopes (optional)

Auth Headers​

Use this option for APIs that authenticate via HTTP headers, such as:

  • Bearer token authentication
  • API key authentication
  • Basic authentication

Configuration requires:

  • API Code
  • Base URL
  • Headers (JSON object containing authentication headers)

Example Headers:

{
"Authorization": "Bearer YOUR_TOKEN_HERE",
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json"
}

Creating an Assistant API​

To configure a new API connection:

  1. Navigate to the Assistants section of your Deepdesk admin interface
  2. Select "Assistant API" from the sidebar navigation
  3. Click "Add Assistant API"
  4. Choose the appropriate authentication method
  5. Enter a unique API code (this will be referenced in the call_api tool)
  6. Provide the base URL for the API (path will be provided when using call_api)
  7. Enter authentication details according to the chosen method
  8. Save the configuration

Using APIs in Assistants​

Once configured, you can use the API in your assistant instructions with the call_api tool:

When a customer asks about their order status:
1. Extract the order number from their message
2. Use call_api with these specific parameters:
- api_code: "order-system" (this references your configured API)
- path: "/orders/{order_number}"
- method: "GET"
3. Format the response to show relevant order information

You need to add the call_api as an assigned tool to that assistant.

API Request Parameters​

When using the call_api tool, you can specify:

  • api_code (required): The unique identifier of your configured API
  • path (required): The endpoint path (will be appended to the base URL)
  • method (required): HTTP method (GET, POST, PUT, DELETE)
  • headers (optional): Additional headers to send with the request
  • payload (optional): Request body data for POST/PUT requests
  • skip_evaluation (optional): If true, skips the evaluation of this tool call

Example: Checking Order Status​

To check an order status:
Use call_api with:
- api_code: "customer-orders"
- path: "/v1/orders/123456"
- method: "GET"
The API will return order details that you can then format for the customer.

Example: Creating a Support Ticket​

To create a support ticket:
Use call_api with:
- api_code: "helpdesk"
- path: "/tickets"
- method: "POST"
- payload: {
"customer_email": "customer@example.com",
"subject": "Product question",
"description": "Customer is asking about product warranties"
}
The API will create a ticket and return a confirmation with the ticket number.