Tool schemas

GET /v1/tools returns the Lineage tools as function definitions for Grok, OpenRouter models, OpenAI-compatible clients and the Anthropic API.

All docs as plain text OpenAPI spec

The tools are the same ones the MCP server lists. Each has a name, a description written for a model, and a JSON Schema for its arguments with every field described. No key is needed to read them. Your code runs a tool call by sending the matching request in the endpoints map, with your key.

curl "https://api.lineage.rexstjohn.com/v1/tools?format=openai"

format	Shape
`openai`	{ type: function, function: { name, description, parameters } }, the default
`anthropic`	{ name, description, input_schema }
`mcp`	{ name, description, inputSchema, annotations }

With an OpenAI-compatible client

Pass the tools to chat completions on xAI (Grok), OpenRouter or any OpenAI-compatible endpoint. When the model returns a tool call, run it with runTool from @lineage/sdk, which maps the name and arguments onto the endpoint, waits for searches, and returns API errors as data the model can read. The grok-tools-example template in the repo does this end to end.

import { LineageClient, openAiTools, runTool } from "@lineage/sdk";

const lineage = new LineageClient(); // reads LINEAGE_API_KEY
const tools = openAiTools();
// ... model returns message.tool_calls
for (const call of message.tool_calls) {
  const result = await runTool(lineage, call.function.name, JSON.parse(call.function.arguments));
  messages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(result.ok ? result.data : result.error) });
}

Tools

Tool	Endpoint	Charges credits
`search_records`	POST /v1/searches	Yes, see the description
`get_search`	GET /v1/searches/{id}	No
`get_record`	GET /v1/records/{id}	No
`resolve_subject`	POST /v1/subjects:resolve	Yes, see the description
`get_subject`	GET /v1/subjects/{id}	No
`select_candidate`	POST /v1/subjects/{id}:select	No
`check_vital_status`	POST /v1/subjects/{id}/vital-status	Yes, see the description
`run_research`	POST /v1/runs	Yes, see the description
`get_run`	GET /v1/runs/{id}	No
`export_gedcom`	GET /v1/searches/{id}/export	No
`list_sources`	GET /v1/sources	No
`get_source`	GET /v1/sources/{slug}	No
`list_models`	GET /v1/models	No
`draft_contact_request`	POST /v1/contact-requests	No
`list_archives`	GET /v1/archives	No
`get_key`	GET /v1/key	No

Good to know

Searches about anyone who may be alive return living_person_blocked and cost 0 credits. Lineage researches someone only when a death date is on record, or a birth more than 110 years ago. A relative who may be alive comes back as { relation, living: true } with no name, dates or places.
wait_seconds and idempotency_key are tool arguments, not API fields: runTool sends the key as the Idempotency-Key header and polls for up to wait_seconds.
Every record in a result has citation.url. Have the model quote the source and locator rather than paraphrase.