Misar.io Documentation

Retrieve tool schemas available to the agent and proxy web fetch requests through the backend.

Overview

The Tools API exposes two capabilities: fetching the schemas for all tools the agent can invoke, and a server-side web fetch proxy that converts raw HTML into clean readable text.

Tool Schemas

v1 — Schema List

GET /tools
Authorization: Bearer YOUR_API_KEY

Returns the JSON Schema definitions for all built-in tools available to the agent.

{
  "tools": [
    {
      "name": "read_file",
      "description": "Read the contents of a file at the given path.",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": { "type": "string", "description": "Relative path to the file" }
        },
        "required": ["path"]
      }
    }
  ],
  "count": 31
}

v2 — Schema List with Validation

GET /tools/v2
Authorization: Bearer YOUR_API_KEY

Identical to v1 but each schema includes an additional validation block with constraints the agent must respect (e.g. path restrictions, size limits, permission requirements).

{
  "tools": [
    {
      "name": "write_file",
      "description": "Write content to a file.",
      "input_schema": { ... },
      "validation": {
        "requires_permission": true,
        "max_bytes": 524288,
        "blocked_paths": [".env", ".misar/hooks/"]
      }
    }
  ],
  "count": 31,
  "schema_version": "2"
}

Use v2 when building custom agent integrations that need to enforce permission gates or size limits before sending tool results back to the backend.

Web Fetch Proxy

Fetch a URL server-side and receive clean, readable text. The proxy strips navigation, ads, and boilerplate, returning only the main content — suitable for injecting into an agent's context.

POST /tools/web-fetch
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request

{
  "url": "https://docs.example.com/api/authentication",
  "max_bytes": 10240
}

| Field | Type | Default | Description | |-------|------|---------|-------------| | url | string | — | URL to fetch. Must be HTTPS | | max_bytes | number | 10240 | Maximum response size in bytes (max: 10 KB) |

Response

{
  "url": "https://docs.example.com/api/authentication",
  "title": "Authentication — Example Docs",
  "content": "## Authentication\n\nAll requests require a Bearer token...",
  "content_bytes": 3412,
  "fetched_at": "2026-03-21T15:00:00Z"
}

| Field | Description | |-------|-------------| | url | The URL that was fetched (may differ from input if redirected) | | title | Page title extracted from the HTML | | content | Main page content converted to readable plain text | | content_bytes | Size of the returned content in bytes | | fetched_at | ISO 8601 timestamp of when the fetch occurred |

Only HTTPS URLs are accepted. HTTP URLs and private network addresses (localhost, RFC 1918 ranges) are rejected with a 400 error.

Error Responses

| Status | Meaning | |--------|---------| | 400 | Invalid URL, HTTP URL, or private network address | | 422 | URL is reachable but returned non-HTML content | | 502 | Upstream fetch failed or timed out | | 429 | Rate limit exceeded |