Provider Management

List All Providers

Retrieve all API provider configurations registered in HandsAI.

Request

curl -X GET "http://localhost:8080/admin/providers" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

Returns an array of ApiProviderResponse objects:

Long

Unique identifier for the provider

name

string

Display name of the provider

code

string

Unique code identifier for the provider

baseUrl

string

Base URL for all API requests to this provider

authenticationType

AuthenticationTypeEnum

Type of authentication used. Possible values:

NONE - No authentication required
API_KEY - API key authentication
BEARER_TOKEN - Bearer token authentication
BASIC_AUTH - Basic HTTP authentication

apiKeyLocation

ApiKeyLocationEnum

Where to include the API key/token. Possible values:

NONE - Not applicable
HEADER - Include in request headers
QUERY_PARAMETER - Include as query parameter
IN_BODY - Include in request body

apiKeyName

string

Name of the header, query parameter, or body field for the API key

isExportable

boolean

Whether this provider can be exported to external systems

customHeaders

object

Map of custom headers to include in all requests (values are obscured as “generic_text” in responses)

isDynamicAuth

boolean

Whether this provider uses dynamic authentication (token refresh)

dynamicAuthUrl

string

URL endpoint for obtaining authentication tokens

dynamicAuthMethod

DynamicAuthMethodEnum

HTTP method for dynamic auth requests. Possible values:

GET
POST

dynamicAuthPayload

string

Payload for dynamic auth requests (values obscured in responses)

dynamicAuthPayloadType

DynamicAuthPayloadTypeEnum

Format of the dynamic auth payload. Possible values:

JSON
FORM_DATA

dynamicAuthPayloadLocation

DynamicAuthPayloadLocationEnum

Where to send the dynamic auth payload. Possible values:

BODY
QUERY_PARAMETERS
HEADERS

dynamicAuthTokenExtractionPath

string

JSON path to extract the token from the auth response (e.g., “$.access_token”)

dynamicAuthInvalidationKeywords

string

Keywords that indicate token expiration (e.g., “expired,unauthorized”)

Example Response

[
  {
    "id": 1,
    "name": "GitHub API",
    "code": "github",
    "baseUrl": "https://api.github.com",
    "authenticationType": "BEARER_TOKEN",
    "apiKeyLocation": "HEADER",
    "apiKeyName": "Authorization",
    "isExportable": true,
    "customHeaders": {
      "Accept": "application/vnd.github.v3+json",
      "User-Agent": "HandsAI"
    },
    "isDynamicAuth": false,
    "dynamicAuthUrl": null,
    "dynamicAuthMethod": null,
    "dynamicAuthPayload": null,
    "dynamicAuthPayloadType": null,
    "dynamicAuthPayloadLocation": null,
    "dynamicAuthTokenExtractionPath": null,
    "dynamicAuthInvalidationKeywords": null
  },
  {
    "id": 2,
    "name": "Slack API",
    "code": "slack",
    "baseUrl": "https://slack.com/api",
    "authenticationType": "BEARER_TOKEN",
    "apiKeyLocation": "HEADER",
    "apiKeyName": "Authorization",
    "isExportable": true,
    "customHeaders": {},
    "isDynamicAuth": true,
    "dynamicAuthUrl": "https://slack.com/api/auth.test",
    "dynamicAuthMethod": "POST",
    "dynamicAuthPayload": "{\"token\":\"generic_text\"}",
    "dynamicAuthPayloadType": "JSON",
    "dynamicAuthPayloadLocation": "BODY",
    "dynamicAuthTokenExtractionPath": "$.access_token",
    "dynamicAuthInvalidationKeywords": "invalid_auth,token_revoked"
  }
]

Get Provider by ID

Retrieve a specific provider by its unique identifier.

Request

curl -X GET "http://localhost:8080/admin/providers/1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

Long

required

Unique identifier of the provider to retrieve

Response

Returns a single ApiProviderResponse object with all fields described in the List All Providers section.

Create Provider

Create a new API provider configuration.

Request - Static API Key

curl -X POST "http://localhost:8080/admin/providers" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub API",
    "code": "github",
    "baseUrl": "https://api.github.com",
    "authenticationType": "BEARER_TOKEN",
    "apiKeyLocation": "HEADER",
    "apiKeyName": "Authorization",
    "apiKeyValue": "ghp_xxxxxxxxxxxxxxxxxxxx",
    "isExportable": true,
    "customHeaders": {
      "Accept": "application/vnd.github.v3+json",
      "User-Agent": "HandsAI"
    },
    "isDynamicAuth": false
  }'

Request - Dynamic Authentication (OAuth)

curl -X POST "http://localhost:8080/admin/providers" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom OAuth API",
    "code": "custom_oauth",
    "baseUrl": "https://api.example.com",
    "authenticationType": "BEARER_TOKEN",
    "apiKeyLocation": "HEADER",
    "apiKeyName": "Authorization",
    "isExportable": false,
    "isDynamicAuth": true,
    "dynamicAuthUrl": "https://auth.example.com/oauth/token",
    "dynamicAuthMethod": "POST",
    "dynamicAuthPayload": "{\"grant_type\":\"client_credentials\",\"client_id\":\"YOUR_CLIENT_ID\",\"client_secret\":\"YOUR_CLIENT_SECRET\"}",
    "dynamicAuthPayloadType": "JSON",
    "dynamicAuthPayloadLocation": "BODY",
    "dynamicAuthTokenExtractionPath": "$.access_token",
    "dynamicAuthInvalidationKeywords": "expired,invalid_token,unauthorized"
  }'

Request Body

name

string

required

Display name of the provider

code

string

required

Unique code identifier for the provider

baseUrl

string

required

Base URL for all API requests (e.g., “https://api.github.com”)

authenticationType

AuthenticationTypeEnum

required

Type of authentication: NONE, API_KEY, BEARER_TOKEN, or BASIC_AUTH

apiKeyLocation

ApiKeyLocationEnum

Where to include the API key: NONE, HEADER, QUERY_PARAMETER, or IN_BODY

apiKeyName

string

Name of the header, query parameter, or body field for the API key

apiKeyValue

string

The actual API key or token value (not returned in responses)

isExportable

boolean

Whether this provider can be exported to external systems

customHeaders

object

Map of custom headers to include in all requests (e.g., User-Agent, Accept)

isDynamicAuth

boolean

Enable dynamic authentication (token refresh mechanism)

dynamicAuthUrl

string

URL endpoint for obtaining authentication tokens (required if isDynamicAuth is true)

dynamicAuthMethod

DynamicAuthMethodEnum

HTTP method for auth requests: GET or POST

dynamicAuthPayload

string

Payload for dynamic auth requests (JSON string or form data)

dynamicAuthPayloadType

DynamicAuthPayloadTypeEnum

Format of the payload: JSON or FORM_DATA

dynamicAuthPayloadLocation

DynamicAuthPayloadLocationEnum

Where to send the payload: BODY, QUERY_PARAMETERS, or HEADERS

dynamicAuthTokenExtractionPath

string

JSON path to extract the token from auth response (e.g., “

.access_token" or "

.data.token”)

dynamicAuthInvalidationKeywords

string

Comma-separated keywords indicating token expiration (e.g., “expired,unauthorized,invalid_token”)

Response

Returns the created ApiProviderResponse object with HTTP 201 Created status.

Long

Unique identifier of the newly created provider

Sensitive fields like apiKeyValue and actual customHeaders values are obscured in the response for security.

Update Provider

Update an existing API provider configuration.

Request

curl -X PUT "http://localhost:8080/admin/providers/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub API (Updated)",
    "code": "github",
    "baseUrl": "https://api.github.com",
    "authenticationType": "BEARER_TOKEN",
    "apiKeyLocation": "HEADER",
    "apiKeyName": "Authorization",
    "apiKeyValue": "ghp_new_token_xxxxxxxxxxxx",
    "isExportable": true,
    "customHeaders": {
      "Accept": "application/vnd.github.v3+json",
      "User-Agent": "HandsAI/2.0"
    },
    "isDynamicAuth": false
  }'

Path Parameters

Long

required

Unique identifier of the provider to update

Request Body

Same as Create Provider request body.

All fields from the create request are available. Only provide fields you want to update.

Response

Returns the updated ApiProviderResponse object.

Delete Provider

Delete an API provider configuration.

Request

curl -X DELETE "http://localhost:8080/admin/providers/1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

Long

required

Unique identifier of the provider to delete

Response

Returns HTTP 204 No Content on successful deletion.

Deleting a provider will affect all tools that depend on it. Ensure no active tools reference this provider before deletion.

Authentication Configuration Examples

API Key in Header

{
  "authenticationType": "API_KEY",
  "apiKeyLocation": "HEADER",
  "apiKeyName": "X-API-Key",
  "apiKeyValue": "your-api-key-here"
}

Bearer Token

{
  "authenticationType": "BEARER_TOKEN",
  "apiKeyLocation": "HEADER",
  "apiKeyName": "Authorization",
  "apiKeyValue": "your-bearer-token"
}

API Key in Query Parameter

{
  "authenticationType": "API_KEY",
  "apiKeyLocation": "QUERY_PARAMETER",
  "apiKeyName": "api_key",
  "apiKeyValue": "your-api-key-here"
}

OAuth 2.0 with Dynamic Authentication

{
  "authenticationType": "BEARER_TOKEN",
  "apiKeyLocation": "HEADER",
  "apiKeyName": "Authorization",
  "isDynamicAuth": true,
  "dynamicAuthUrl": "https://auth.example.com/oauth/token",
  "dynamicAuthMethod": "POST",
  "dynamicAuthPayload": "{\"grant_type\":\"client_credentials\",\"client_id\":\"xxx\",\"client_secret\":\"yyy\"}",
  "dynamicAuthPayloadType": "JSON",
  "dynamicAuthPayloadLocation": "BODY",
  "dynamicAuthTokenExtractionPath": "$.access_token",
  "dynamicAuthInvalidationKeywords": "expired,invalid_token"
}

Basic Authentication

{
  "authenticationType": "BASIC_AUTH",
  "apiKeyLocation": "HEADER",
  "apiKeyName": "Authorization",
  "apiKeyValue": "username:password"
}

For Basic Auth, the apiKeyValue should be the base64-encoded “username:password” string, or provide the plain text and HandsAI will handle encoding.

MCP Endpoints

Admin API

Task Memory API

Import/Export API

Provider Management

List All Providers

Request

Response

Example Response

Get Provider by ID

Request

Path Parameters

Response

Create Provider

Request - Static API Key

Request - Dynamic Authentication (OAuth)

Request Body

Response

Update Provider

Request

Path Parameters

Request Body

Response

Delete Provider

Request

Path Parameters

Response

Authentication Configuration Examples

API Key in Header

Bearer Token

API Key in Query Parameter

OAuth 2.0 with Dynamic Authentication

Basic Authentication

Build docs developers (and LLMs) love

MCP Endpoints

Admin API

Task Memory API

Import/Export API

​List All Providers

​Request

​Response

​Example Response

​Get Provider by ID

​Request

​Path Parameters

​Response

​Create Provider

​Request - Static API Key

​Request - Dynamic Authentication (OAuth)

​Request Body

​Response

​Update Provider

​Request

​Path Parameters

​Request Body

​Response

​Delete Provider

​Request

​Path Parameters

​Response

​Authentication Configuration Examples

​API Key in Header

​Bearer Token

​API Key in Query Parameter

​OAuth 2.0 with Dynamic Authentication

​Basic Authentication

Build docs developers (and LLMs) love

List All Providers

Request

Response

Example Response

Get Provider by ID

Request

Path Parameters

Response

Create Provider

Request - Static API Key

Request - Dynamic Authentication (OAuth)

Request Body

Response

Update Provider

Request

Path Parameters

Request Body

Response

Delete Provider

Request

Path Parameters

Response

Authentication Configuration Examples

API Key in Header

Bearer Token

API Key in Query Parameter

OAuth 2.0 with Dynamic Authentication

Basic Authentication