Tools

Audience: Developers

Tools API Contract

Overview

Endpoints for managing API and MCP tool configurations. All endpoints require authentication via X-API-Key header.

---

Authentication

All requests must include:

X-API-Key: <your-api-key>

---

Interaction with Research Tasks (Runtime Overrides)

While this API allows you to persistently store API and MCP tool configurations in the database, you can also inject these tool configurations dynamically at runtime per-request, without persisting them.

When creating a Task (POST /v1/tasks) or Taskgroup (POST /v1/taskgroups), you can pass api_config and mcp_config dictionaries to override authentication tokens or full configurations for the current research run exclusively. See the Tasks and Taskgroups API contracts for exact schemas.

---

Common Schemas

AuthenticationConfig

Field	Type	Required	Description
type	string	Yes	Auth type: api-key, bearer-token, basic, custom-header, none
key	string	No	Header name for api-key auth
value	string	No	Header value for api-key auth
token	string	No	Token for bearer-token auth
username	string	No	Username for basic auth
password	string	No	Password for basic auth
headers	object	No	Custom headers map for custom-header auth

ParameterConfig

Field	Type	Required	Description
name	string	Yes	Parameter name
type	string	No	One of: string, integer, number, boolean, object, array. Default: string
required	boolean	No	Whether this parameter is required. Default: false
description	string	No	Optional hint for the LLM

---

API Config Endpoints

Create API Tool (POST /v1/tools/api)

Create a new API tool configuration.

Request Body

Field	Type	Required	Description
name	string	Yes	Name of the API tool (max 255 chars)
url	string	Yes	Full URL for the API endpoint (http/https)
method	string	No	HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. Default: GET
description	string	No	Description of the API tool
parameters	ParameterConfig[]	No	List of parameter definitions. Default: []
authentication	AuthenticationConfig	No	Authentication configuration
extract_fields	string[]	No	Dot-notation paths to extract from response (e.g. ["data.items"])
timeout	float	No	Request timeout in seconds. Default: 30.0
max_response_size	integer	No	Max response size in characters. Default: 50000
request_body	object	No	Fixed body template for POST/PUT/PATCH. Use {{param_name}} placeholders for dynamic values

Example JSON Request:

{
  "name": "query_for_internal_information",
  "method": "POST",
  "url": "https://api.example.com/retrieval/run",
  "description": "Run the retrieval pipeline.",
  "authentication": {
    "type": "api-key",
    "key": "x-api-key",
    "value": "your-api-key"
  },
  "parameters": [
    { "name": "standalone_query", "type": "string", "required": true }
  ],
  "request_body": {
    "inputs": {
      "standalone_query": "{{standalone_query}}"
    },
    "config": {}
  },
  "extract_fields": ["chunks"],
  "timeout": 30.0,
  "max_response_size": 50000
}

Example Response (201 Created):

{
  "id": "c280ab14-8c7e-40bf-8afc-5c17ddc86597",
  "name": "query_for_internal_information",
  "description": "Run the retrieval pipeline.",
  "url": "https://api.example.com/retrieval/run",
  "method": "POST",
  "parameters": [
    { "name": "standalone_query", "type": "string", "required": true, "description": null }
  ],
  "authentication": {
    "type": "api-key",
    "key": "x-api-key",
    "value": "your-api-key",
    "token": null,
    "username": null,
    "password": null,
    "headers": null
  },
  "extract_fields": ["chunks"],
  "timeout": 30.0,
  "max_response_size": 50000,
  "request_body": {
    "inputs": { "standalone_query": "{{standalone_query}}" },
    "config": {}
  },
  "created_at": "2026-03-12T03:01:23.020825Z",
  "updated_at": "2026-03-12T03:01:23.020825Z"
}

---

Get API Tools List (GET /v1/tools/api)

List all API tool configurations for the authenticated account.

Query Parameters

Parameter	Type	Required	Description
skip	integer	No	Number of records to skip. Default: 0
limit	integer	No	Max records to return. Default: 100

Example cURL:

curl -X GET "http://localhost:8000/v1/tools/api?skip=0&limit=10" \
  -H "X-API-Key: your-secure-master-key-here"

Example Response (200 OK):

[
  {
    "id": "c280ab14-8c7e-40bf-8afc-5c17ddc86597",
    "name": "query_for_internal_information",
    "description": "Run the retrieval pipeline.",
    "url": "https://api.example.com/retrieval/run",
    "method": "POST",
    "parameters": [
      { "name": "standalone_query", "type": "string", "required": true, "description": null }
    ],
    "authentication": {
      "type": "api-key",
      "key": "x-api-key",
      "value": "your-api-key",
      "token": null,
      "username": null,
      "password": null,
      "headers": null
    },
    "extract_fields": ["chunks"],
    "timeout": 30.0,
    "max_response_size": 50000,
    "request_body": {
      "inputs": { "standalone_query": "{{standalone_query}}" },
      "config": {}
    },
    "created_at": "2026-03-12T03:01:23.020825Z",
    "updated_at": "2026-03-12T03:01:23.020825Z"
  }
]

---

Get API Tool (GET /v1/tools/api/{config_id})

Get a specific API tool configuration by ID.

Path Parameters

Parameter	Type	Required	Description
config_id	UUID	Yes	The API config ID

Example cURL:

curl -X GET "http://localhost:8000/v1/tools/api/c280ab14-8c7e-40bf-8afc-5c17ddc86597" \
  -H "X-API-Key: your-secure-master-key-here"

Example Response (200 OK):

{
  "id": "c280ab14-8c7e-40bf-8afc-5c17ddc86597",
  "name": "query_for_internal_information",
  "description": "Run the retrieval pipeline.",
  "url": "https://api.example.com/retrieval/run",
  "method": "POST",
  "parameters": [
    { "name": "standalone_query", "type": "string", "required": true, "description": null }
  ],
  "authentication": {
    "type": "api-key",
    "key": "x-api-key",
    "value": "your-api-key",
    "token": null,
    "username": null,
    "password": null,
    "headers": null
  },
  "extract_fields": ["chunks"],
  "timeout": 30.0,
  "max_response_size": 50000,
  "request_body": {
    "inputs": { "standalone_query": "{{standalone_query}}" },
    "config": {}
  },
  "created_at": "2026-03-12T03:01:23.020825Z",
  "updated_at": "2026-03-12T03:01:23.020825Z"
}

Example Error Response (404 Not Found):

{
  "detail": "API config not found"
}

---

Update API Tool (PUT /v1/tools/api/{config_id})

Update an existing API tool configuration. All fields are optional (partial update supported).

Path Parameters

Parameter	Type	Required	Description
config_id	UUID	Yes	The API config ID

Request Body (all fields optional)

Field	Type	Description
name	string	Name of the API tool (max 255 chars)
url	string	Full URL for the API endpoint
method	string	HTTP method
description	string	Description of the API tool
parameters	ParameterConfig[]	List of parameter definitions
authentication	AuthenticationConfig	Authentication configuration
extract_fields	string[]	Dot-notation paths to extract from response
timeout	float	Request timeout in seconds
max_response_size	integer	Max response size in characters
request_body	object	Fixed body template with {{param_name}} placeholders

Example JSON Request:

{
  "url": "https://api.example.com/retrieval/v2/run",
  "authentication": {
    "type": "api-key",
    "key": "x-api-key",
    "value": "new-api-key"
  }
}

Example Response (200 OK):

Example Error Response (404 Not Found):

{
  "detail": "API config not found"
}

---

Delete API Tool (DELETE /v1/tools/api/{config_id})

Soft delete an API tool configuration.

Path Parameters

Parameter	Type	Required	Description
config_id	UUID	Yes	The API config ID

Example cURL:

curl -X DELETE "http://localhost:8000/v1/tools/api/c280ab14-8c7e-40bf-8afc-5c17ddc86597" \
  -H "X-API-Key: your-secure-master-key-here"

Example Response (204 No Content):

Example Error Response (404 Not Found):

{
  "detail": "API config not found"
}

---

MCP Config Endpoints

Create MCP Tool (POST /v1/tools/mcp)

Create a new MCP tool configuration.

Request Body

Field	Type	Required	Description
name	string	Yes	Name of the MCP tool server (max 255 chars)
config	object	Yes	MCP server configuration (e.g. url, allowed_tools)
transport	string	Yes	Transport type: sse, stdio (max 50 chars)
description	string	No	Description of the MCP tool server
authentication	AuthenticationConfig	No	Authentication configuration
mcp_type	string	No	Type of MCP: custom, native. Default: custom

Example JSON Request:

{
  "name": "google-calendar",
  "description": "Google Calendar MCP server",
  "config": {
    "url": "https://example.com/google_calendar/mcp",
    "allowed_tools": ["google_calendar_events_list"]
  },
  "transport": "sse",
  "authentication": {
    "type": "bearer-token",
    "token": "your-bearer-token"
  },
  "mcp_type": "custom"
}

Example Response (201 Created):

{
  "id": "4fd028ba-952e-4fbe-8c29-4ac718d92210",
  "name": "google-calendar",
  "description": "Google Calendar MCP server",
  "config": {
    "url": "https://example.com/google_calendar/mcp",
    "allowed_tools": ["google_calendar_events_list"]
  },
  "transport": "sse",
  "authentication": {
    "type": "bearer-token",
    "token": "your-bearer-token",
    "key": null,
    "value": null,
    "username": null,
    "password": null,
    "headers": null
  },
  "mcp_type": "custom",
  "created_at": "2026-03-12T03:01:23.020825Z",
  "updated_at": "2026-03-12T03:01:23.020825Z"
}

---

Get MCP Tools List (GET /v1/tools/mcp)

List all MCP tool configurations for the authenticated account.

Query Parameters

Parameter	Type	Required	Description
skip	integer	No	Number of records to skip. Default: 0
limit	integer	No	Max records to return. Default: 100

Example cURL:

curl -X GET "http://localhost:8000/v1/tools/mcp?skip=0&limit=10" \
  -H "X-API-Key: your-secure-master-key-here"

Example Response (200 OK):

[
  {
    "id": "4fd028ba-952e-4fbe-8c29-4ac718d92210",
    "name": "google-calendar",
    "description": "Google Calendar MCP server",
    "config": {
      "url": "https://example.com/google_calendar/mcp",
      "allowed_tools": ["google_calendar_events_list"]
    },
    "transport": "sse",
    "authentication": {
      "type": "bearer-token",
      "token": "your-bearer-token",
      "key": null,
      "value": null,
      "username": null,
      "password": null,
      "headers": null
    },
    "mcp_type": "custom",
    "created_at": "2026-03-12T03:01:23.020825Z",
    "updated_at": "2026-03-12T03:01:23.020825Z"
  }
]

---

Get MCP Tool (GET /v1/tools/mcp/{config_id})

Get a specific MCP tool configuration by ID.

Path Parameters

Parameter	Type	Required	Description
config_id	UUID	Yes	The MCP config ID

Example cURL:

curl -X GET "http://localhost:8000/v1/tools/mcp/4fd028ba-952e-4fbe-8c29-4ac718d92210" \
  -H "X-API-Key: your-secure-master-key-here"

Example Response (200 OK):

Example Error Response (404 Not Found):

{
  "detail": "MCP config not found"
}

---

Update MCP Tool (PUT /v1/tools/mcp/{config_id})

Update an existing MCP tool configuration. All fields are optional (partial update supported).

Path Parameters

Parameter	Type	Required	Description
config_id	UUID	Yes	The MCP config ID

Request Body (all fields optional)

Field	Type	Description
name	string	Name of the MCP tool server
description	string	Description of the MCP tool server
config	object	MCP server configuration
transport	string	Transport type
authentication	AuthenticationConfig	Authentication configuration
mcp_type	string	Type of MCP

Example JSON Request:

{
  "config": {
    "url": "https://example.com/google_calendar/v2/mcp",
    "allowed_tools": ["google_calendar_events_list", "google_calendar_events_create"]
  }
}

Example Response (200 OK):

Example Error Response (404 Not Found):

{
  "detail": "MCP config not found"
}

---

Delete MCP Tool (DELETE /v1/tools/mcp/{config_id})

Soft delete an MCP tool configuration.

Path Parameters

Parameter	Type	Required	Description
config_id	UUID	Yes	The MCP config ID

Example cURL:

curl -X DELETE "http://localhost:8000/v1/tools/mcp/4fd028ba-952e-4fbe-8c29-4ac718d92210" \
  -H "X-API-Key: your-secure-master-key-here"

Example Response (204 No Content):

Example Error Response (404 Not Found):

{
  "detail": "MCP config not found"
}

---

Notes

• All endpoints use soft delete — deleted configs are not permanently removed from the database

• Configs are scoped per account — each API key only sees configs created under the same account

• authentication fields are encrypted at rest in the database and decrypted on read

• request_body templates support {{param_name}} placeholders — only exact matches are replaced (e.g. "{{query}}" is replaced, but "prefix-{{query}}" is not)