---
title: "Execute a server-side tool"
method: POST
path: "/api/ai/v1/tools"
tags: ["AI"]
---

# Execute a server-side tool

`POST /api/ai/v1/tools`

## Request

- Base URL: `https://your-deployment.example.com`
- URL: `https://your-deployment.example.com/api/ai/v1/tools`
- Auth: HTTP bearer

Runs one of the built-in server-side tools (`weather_info`, `web_search`, `web_fetch`) and returns its result as JSON. Authenticate with a JWT access token only - API keys are NOT accepted on this endpoint. Rate-limited to 100 requests/hour per user, counted separately from other endpoints. `request_id` echoes the X-Request-ID response header.

## Request body

- ExecuteToolRequest
  - `toolName` 'weather_info' | 'web_search' | 'web_fetch', required
  - `input` object, required

## Response `200`

Tool executed successfully (`success` is always true here).

- ExecuteToolResponse200
  - `success` boolean, required
  - `result` unknown
  - `error` string
  - `errorType` string
  - `executionTimeMs` number
  - `request_id` string, required

## Other responses

- `400`: Malformed JSON body.
- `401`: Missing or invalid JWT (an API key is rejected here).
- `403`: Valid JWT, but the account is suspended or has a dispute pending.
- `405`: The path does not serve this HTTP method.
- `422`: Request failed validation.
- `429`: Rate limit exceeded (100 requests/hour per user for this endpoint).
- `500`: Tool execution failed (`success: false` with `error`) or an unexpected server error.

---

[API](https://skmtc.dev/bike4mind/apis/bike4mind-api.md) · [All operations](https://skmtc.dev/bike4mind/apis/bike4mind-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bike4mind/apis/bike4mind-api/revisions/db47495b892f?raw)