API Documentation

Query Parameters

Param	Type	Description
q	string	Required. Search query.
limit	integer	Max results (1-20, default 10).

Example Request

curl 'http://localhost:3000/search?q=bedrock+data+protection&limit=5' \
  -H 'X-API-Key: srch_...'

Response

{
  "source": "local",
  "results": [
    {
      "result_id": "uuid",
      "link": "https://example.com/page",
      "title": "Page Title",
      "snippet": "Matched chunk content...",
      "summary": "Display summary",
      "verified": true,
      "confidence": 0.82
    }
  ],
  "meta": {
    "query": "bedrock data protection",
    "took_ms": 42,
    "top_confidence": 0.82
  }
}

Request Body (JSON)

Field	Type	Description
query	string	Required. Search query.
limit	integer	Max results (1-20, default 5).
feedback	array	Optional. Feedback on previous results: [{"result_id":"...","vote":1}]. Vote is 1 (useful) or -1 (not useful).

Example Request

curl -X POST 'http://localhost:3000/v1/tools/web_search' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: srch_...' \
  -d '{"query":"aws lambda pricing","feedback":[{"result_id":"prev-uuid","vote":1}]}'

Response

{
  "results": [
    {
      "result_id": "uuid",
      "title": "AWS Lambda Pricing",
      "url": "https://aws.amazon.com/lambda/pricing/",
      "snippet": "With AWS Lambda, you pay only for what you use..."
    }
  ]
}

Each result includes a result_id you can pass back in the feedback array on your next search to improve future ranking.

OpenAI Function Definition

Register this as a tool so the LLM can call it directly:

{
  "type": "function",
  "function": {
    "name": "web_search",
    "description": "Search the web using TomsIndex",
    "parameters": {
      "type": "object",
      "properties": {
        "query": { "type": "string" },
        "limit": { "type": "number" }
      },
      "required": ["query"]
    }
  }
}

LiteLLM / OpenRouter

Point the tool handler at your TomsIndex instance:

import requests

def web_search(query, limit=5):
    r = requests.post(
        "https://your-instance.com/v1/tools/web_search",
        headers={"X-API-Key": "srch_...", "Content-Type": "application/json"},
        json={"query": query, "limit": limit},
    )
    return r.json()["results"]

Claude Desktop

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tomsindex": {
      "command": "node",
      "args": ["/path/to/mcp/tomsindex-mcp.js"],
      "env": {
        "TOMSINDEX_URL": "https://your-instance.com",
        "TOMSINDEX_API_KEY": "srch_..."
      }
    }
  }
}

Cursor / Windsurf

Add to .cursor/mcp.json or .windsurf/mcp.json:

{
  "mcpServers": {
    "tomsindex": {
      "command": "node",
      "args": ["./mcp/tomsindex-mcp.js"],
      "env": {
        "TOMSINDEX_URL": "https://your-instance.com",
        "TOMSINDEX_API_KEY": "srch_..."
      }
    }
  }
}

Test Locally

TOMSINDEX_URL=http://localhost:3000 node mcp/tomsindex-mcp.js

The MCP server exposes a single web_search tool. The LLM calls it automatically when it needs to search the web.

Request Body (JSON)

Field	Type	Description
url	string	Required. Page URL to index.
summary	string	Required. Short description of the page.

Example Request

curl -X POST 'http://localhost:3000/submit' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: srch_...' \
  -d '{"url":"https://example.com","summary":"Example page."}'

Response

{
  "submission_id": "uuid",
  "result_id": "uuid",
  "job_id": "uuid",
  "url": "https://example.com/",
  "status": "queued"
}

Limits

• 20 submissions per day per account
• 3 unverified submissions per URL per account

Request Body (JSON)

Field	Type	Description
result_id	string	Required. The result UUID from search.
query	string	Required. The original search query.
vote	integer	Required. 1 (upvote) or -1 (downvote).

Example Request

curl -X POST 'http://localhost:3000/feedback' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: srch_...' \
  -d '{"result_id":"uuid","query":"example","vote":1}'

Request Body (JSON)

Field	Type	Description
url_id	string	Required. UUID of the URL to comment on.
rating	integer	Required. Star rating, 1-5.
body	string	Required. Comment text, 1-2000 characters.

Example

curl -X POST 'http://localhost:3000/comments' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: srch_...' \
  -d '{"url_id":"uuid","rating":4,"body":"Great resource for learning async/await."}'

Notes

• One comment per account per URL (posting again updates your existing comment)
• 5 requests/second burst limit
• 20 comments per day per account

Query Parameters

Param	Type	Description
limit	integer	Max comments (1-50, default 10).
offset	integer	Pagination offset (default 0).
sort	string	best (default) or newest.

Public endpoint — no API key required.

Request Body (JSON)

Field	Type	Description
vote	integer	Required. 1 (upvote) or -1 (downvote).

Notes

• One vote per account per comment (voting again changes your vote)
• Cannot vote on your own comment
• 5 requests/second burst limit
• 20 votes per hour per account

Request Body (JSON)

Field	Type	Description
platform	string	Required. One of: linkedin, reddit, facebook, twitter, x, other.
post_url	string	Required. URL of your social media post.

How it works

1. Post about TomsIndex on LinkedIn, Reddit, Facebook, or Twitter/X
2. Copy the post URL
3. Submit it via this endpoint
4. An admin will verify and upgrade your account