Tools API

The Melious Tools API provides access to AI-powered utilities including web search, document processing, and custom tools. Tools can be listed, inspected, and executed via REST API.

Quick Start

import httpx

API_KEY = "sk-mel-your-api-key-here"
BASE_URL = "https://api.melious.ai"

async def execute_web_search():
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{BASE_URL}/v1/tools/web-search/execute",
            headers={"Authorization": f"Bearer {API_KEY}"},
            json={
                "parameters": {
                    "query": "latest AI news",
                    "max_results": 5
                }
            }
        )
        result = response.json()
        print(result["result"])

const API_KEY = 'sk-mel-your-api-key-here';
const BASE_URL = 'https://api.melious.ai';

async function executeWebSearch() {
  const response = await fetch(`${BASE_URL}/v1/tools/web-search/execute`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      parameters: {
        query: 'latest AI news',
        max_results: 5
      }
    })
  });

  const result = await response.json();
  console.log(result.result);
}

curl https://api.melious.ai/v1/tools/web-search/execute \
  -H "Authorization: Bearer sk-mel-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "query": "latest AI news",
      "max_results": 5
    }
  }'

Available Endpoints

Endpoint	Method	Description
`/v1/tools`	GET	List available tools
`/v1/tools/openai`	GET	Get tools in OpenAI format for chat completions
`/v1/tools/{slug}`	GET	Get tool details
`/v1/tools/{slug}/execute`	POST	Execute a tool
`/v1/tools/{slug}/schema`	GET	Get tool parameters schema
`/v1/tools/{slug}/rate-limit`	GET	Check rate limit status

Authentication

All tools endpoints require an API key with kit.tools scope:

Authorization: Bearer sk-mel-your-api-key-here

List Tools

GET /v1/tools

Retrieve a paginated list of available tools.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`page_size`	integer	50	Items per page (max 100)
`source`	string	null	Filter: `native`, `managed`, `remote`
`tool_type`	string	null	Filter: `handler`, `mcp`, `api`
`category`	string	null	Filter by category
`search`	string	null	Search query

Response

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Web Search",
      "slug": "web-search",
      "source": "native",
      "tool_type": "handler",
      "display_name": "Web Search",
      "description": "Search the web for current information",
      "category": "search",
      "icon": "search",
      "parameters_schema": {
        "type": "object",
        "properties": {
          "query": {"type": "string", "description": "Search query"},
          "max_results": {"type": "integer", "default": 10}
        },
        "required": ["query"]
      },
      "supports_streaming": false,
      "cost_per_call": "0.01"
    }
  ],
  "total": 25,
  "page": 1,
  "page_size": 50,
  "total_pages": 1
}

OpenAI Format Export

GET /v1/tools/openai

Get your tools formatted for direct use in chat completions. Returns tools with their slugs for reference.

Response

{
  "object": "list",
  "data": [
    {
      "slug": "web-search",
      "type": "function",
      "function": {
        "name": "web_search",
        "description": "Search the web for current information",
        "parameters": {
          "type": "object",
          "properties": {
            "query": {"type": "string", "description": "Search query"}
          },
          "required": ["query"]
        }
      }
    }
  ],
  "usage_hint": "Pass tool slugs in the 'tools' array of /v1/chat/completions"
}

Usage with Chat Completions

Use the slug values directly in /v1/chat/completions:

{
  "model": "auto",
  "messages": [{"role": "user", "content": "Search for AI news"}],
  "tools": ["web-search", "scrape-url"]
}

Tools must be in your collection first. Add them via POST /v1/user/tools/{slug}.

Get Tool Details

GET /v1/tools/{slug}

Get detailed information about a specific tool.

Path Parameters

Parameter	Type	Description
`slug`	string	Tool slug (e.g., `web-search`)

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Web Search",
  "slug": "web-search",
  "source": "native",
  "tool_type": "handler",
  "display_name": "Web Search",
  "description": "Search the web for current information",
  "category": "search",
  "icon": "search",
  "parameters_schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query"
      },
      "max_results": {
        "type": "integer",
        "default": 10,
        "minimum": 1,
        "maximum": 50
      }
    },
    "required": ["query"]
  },
  "supports_streaming": false,
  "cost_per_call": "0.01"
}

Execute Tool

POST /v1/tools/{slug}/execute

Execute a tool with provided parameters.

Path Parameters

Parameter	Type	Description
`slug`	string	Tool slug (e.g., `web-search`)

Request Body

{
  "parameters": {
    "query": "latest AI developments",
    "max_results": 5
  }
}

Response

{
  "success": true,
  "status": "completed",
  "result": {
    "results": [
      {
        "title": "OpenAI Announces GPT-5",
        "url": "https://example.com/article",
        "snippet": "OpenAI has announced..."
      }
    ]
  },
  "error": null,
  "execution_time_ms": 1250
}

Response Fields

Field	Type	Description
`success`	boolean	Whether execution succeeded
`status`	string	`completed`, `failed`, `timeout`
`result`	object	Tool-specific result data
`error`	string	Error message if failed
`execution_time_ms`	integer	Execution time in milliseconds

Get Tool Schema

GET /v1/tools/{slug}/schema

Get the JSON Schema for a tool's parameters.

Response

{
  "tool_slug": "web-search",
  "tool_name": "Web Search",
  "display_name": "Web Search",
  "description": "Search the web for current information",
  "parameters_schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query"
      },
      "max_results": {
        "type": "integer",
        "default": 10,
        "minimum": 1,
        "maximum": 50
      }
    },
    "required": ["query"]
  }
}

Rate Limit Status

GET /v1/tools/{slug}/rate-limit

Check your rate limit status for a specific tool.

Response

{
  "tool_slug": "web-search",
  "limit_per_minute": 60,
  "remaining_per_minute": 45,
  "limit_per_day": 1000,
  "remaining_per_day": 850,
  "reset_at": "2025-01-15T15:00:00Z"
}

Available Tools

Tool	Slug	Category	Description
Web Search	`web-search`	Search	Search the web for current information
URL Scraper	`scrape-url`	Data	Extract content from URLs as markdown
Context7 MCP	`context7-mcp`	MCP	Access library documentation via Context7
Microsoft Learn MCP	`microsoft-learn-mcp`	MCP	Search Microsoft Learn documentation
Svelte MCP	`svelte-mcp`	MCP	Access Svelte framework documentation

Tool Categories

Category	Description	Example Tools
`search`	Web and data search	Web Search
`data`	Data extraction	URL Scraper
`mcp`	MCP integrations	Context7, Microsoft Learn, Svelte

Tool Types

Type	Description
`handler`	Native Python handlers
`mcp`	Model Context Protocol tools
`api`	External API integrations

Tool Sources

Source	Description
`native`	Built-in Melious tools
`managed`	Melious-managed integrations
`remote`	User-configured external tools

Error Handling

Error Response

{
  "success": false,
  "status": "failed",
  "result": null,
  "error": "Invalid parameter: max_results must be between 1 and 50",
  "execution_time_ms": 5
}

Error Codes

Code	Description
`KIT_TOOL_NOT_FOUND`	Tool doesn't exist
`VALIDATION_INVALID_VALUE`	Invalid parameter value
`KIT_EXECUTION_FAILED`	Tool execution failed
`KIT_RATE_LIMIT_EXCEEDED`	Rate limit exceeded
`BILLING_INSUFFICIENT_ENERGY`	Insufficient balance

Best Practices

Check schema first - Use /schema to understand required parameters
Handle errors - Always check success field in response
Monitor rate limits - Check /rate-limit before heavy usage
Use pagination - Set appropriate page_size when listing tools
Cache tool info - Tool metadata doesn't change frequently

Tools API

Tools API

Quick Start

Available Endpoints

Authentication

List Tools

Query Parameters

Response

OpenAI Format Export

Response

Usage with Chat Completions

Get Tool Details

Path Parameters

Response

Execute Tool

Path Parameters

Request Body

Response

Response Fields

Get Tool Schema

Response

Rate Limit Status

Response

Available Tools

Tool Categories

Tool Types

Tool Sources

Error Handling

Error Response

Error Codes

Best Practices

See Also

On this page