Groundlink API reference

curl -X POST https://9ea69cec60fa01f65bbb647a092bcbb4.ctonew.app/api/v1/ground \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer glk_YOUR_API_KEY" \
  -d '{"query": "James Webb Space Telescope", "max_results": 3}'

{
  "query": "James Webb Space Telescope",
  "results": [
    {
      "title": "James Webb Space Telescope",
      "url": "https://en.wikipedia.org/wiki/James_Webb_Space_Telescope",
      "snippet": "The James Webb Space Telescope (JWST) is a space
telescope designed to conduct infrared astronomy. It is the
largest telescope in space…",
      "source": "wikipedia"
    },
    {
      "title": "James Webb Space Telescope Category",
      "url": "https://duckduckgo.com/c/James_Webb_Space_Telescope",
      "snippet": "James Webb Space Telescope Category",
      "source": "duckduckgo"
    },
    {
      "title": "Timeline of the James Webb Space Telescope",
      "url": "https://en.wikipedia.org/wiki/Timeline_of_the_James_Webb_Space_Telescope",
      "snippet": "The James Webb Space Telescope (JWST) is an international
21st-century space observatory that was launched on 25 December 2021…",
      "source": "wikipedia"
    }
  ],
  "meta": {
    "request_id": "7b36dfd4-3ca3-408c-9791-96c1bf2e4603",
    "result_count": 3,
    "processing_ms": 500
  }
}

curl https://9ea69cec60fa01f65bbb647a092bcbb4.ctonew.app/api/v1/usage \
  -H "Authorization: Bearer glk_YOUR_API_KEY"

{
  "key": "glk_1b1a4fda0eee05d8796eb8ed0fde9859",
  "calls": 42,
  "last_call_at": "2026-08-18T22:12:17.520Z"
}

// 1. Advertise the tool to the model (standard OpenAI function calling)
const tools = [{
  type: "function",
  function: {
    name: "ground_search",
    description: "Search Groundlink for verified, citable web results.",
    parameters: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "The natural-language query to ground."
        },
        max_results: {
          type: "integer", minimum: 1, maximum: 10,
          description: "Number of results to return (default 5)."
        }
      },
      required: ["query"]
    }
  }
}];

// 2. When the model emits a tool_call for ground_search, call the API
async function groundSearch(query, maxResults = 5) {
  const res = await fetch("https://9ea69cec60fa01f65bbb647a092bcbb4.ctonew.app/api/v1/ground", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer glk_YOUR_API_KEY"
    },
    body: JSON.stringify({ query, max_results: maxResults })
  });
  return res.json(); // { query, results: [{title,url,snippet,source}], meta }
}

// 3. Return the result to the model in a "tool" role message.
//    The model then answers using results[].url as citations.
const toolResult = await groundSearch("James Webb Space Telescope");
messages.push({
  role: "tool",
  tool_call_id: toolCall.id,
  content: JSON.stringify(toolResult)
});

// Anthropic tool use (Claude) — same idea, tool-use shape
const tools = [{
  name: "ground_search",
  description: "Search Groundlink for verified, citable web results.",
  input_schema: {
    type: "object",
    properties: {
      query: {
        type: "string",
        description: "The natural-language query to ground."
      },
      max_results: { type: "integer", minimum: 1, maximum: 10 }
    },
    required: ["query"]
  }
}];

// When the response has stop_reason === "tool_use", find the block:
const toolUse = message.content.find((b) => b.type === "tool_use");

const res = await fetch("https://9ea69cec60fa01f65bbb647a092bcbb4.ctonew.app/api/v1/ground", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer glk_YOUR_API_KEY"
  },
  body: JSON.stringify({
    query: toolUse.input.query,
    max_results: toolUse.input.max_results ?? 5
  })
});
const json = await res.json();

// Reply with the tool_result so Claude can cite the URLs:
messages.push({
  role: "user",
  content: [{
    type: "tool_result",
    tool_use_id: toolUse.id,
    content: JSON.stringify(json)
  }]
});

// Illustrative MCP server — Groundlink has no official SDK or MCP package
// yet. The API is plain HTTPS + JSON, so any MCP transport can wrap it:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "groundlink", version: "0.1.0" });

server.tool(
  "ground_search",
  {
    query: z.string().describe("The natural-language query to ground."),
    max_results: z.number().int().min(1).max(10).optional()
  },
  async ({ query, max_results }) => {
    const res = await fetch("https://9ea69cec60fa01f65bbb647a092bcbb4.ctonew.app/api/v1/ground", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": "Bearer glk_YOUR_API_KEY"
      },
      body: JSON.stringify({ query, max_results })
    });
    const data = await res.json();
    return { content: [{ type: "text", text: JSON.stringify(data) }] };
  }
);