Skip to main content

Developers

Evidence API and MCP

GILD publishes the evidence behind gildhq.com as a read-only API and an MCP server. Each claim lists the evidence that supports or contradicts it and says plainly when none is attached. Every piece of evidence names its source, its form and where in the source it sits. No key and no sign-up.

Version 1.0. OpenAPI 3.1 at /api/v1/openapi.json

1. What it serves

Entities: products, model releases, model families, vendors, plans, API routes and harnesses. Each entity carries its GILD page, its evidence and claim counts, how many independent sources stand behind it, and, for products, the Signals numbers the page prints.

Claims: what GILD states about an entity, from buying facts and comparison cells to Signals themes and benchmark results, with the evidence ids that support, contradict or qualify each one.

Not every claim has evidence attached yet. Each claim carries evidenceCount and support: supported when at least one evidence row supports it, editorial for GILD's own judgment with no supporting evidence, unsupported for a stated fact with none. A claim with no supporting evidence reads uncertainty high. To keep only claims evidence supports, add support=supported to /claims; the index and each entity's coverage count claims by support.

Evidence: the observation itself. Its form is quotation, paraphrase, measured result, vendor assertion, practitioner opinion or editorial inference. A quotation carries the exact span from the stored copy of the page, checked by sha256.

Sources: the page, its publisher and author, the author's tie to a vendor as GILD recorded it, when the page was published and fetched, and when GILD last re-checked it against the live page (unknown until a recorded re-check; a fetch is not a re-check).

2. Endpoints

  • GET https://gildhq.com/api/v1: index, counts and every endpoint.
  • GET https://gildhq.com/api/v1/entities?kind=product&q=cursor: entities. Filters: kind, category, vendor, q, sort.
  • GET https://gildhq.com/api/v1/entities/cursor?include=claims,plans: one entity with relationships, coverage by evidence form and open unknowns.
  • GET https://gildhq.com/api/v1/claims?entity=cursor&topic=buying_fact&support=supported: claims with supporting evidence. Filters: entity, kind, validity, topic, support, updatedSince.
  • GET https://gildhq.com/api/v1/evidence?entity=cursor&form=quotation&independentOnly=true: evidence. Filters: entity, form, cohort, stance, sourceType, independentOnly, since.
  • GET https://gildhq.com/api/v1/sources/{id}: one source and everything that cites it.
  • GET https://gildhq.com/api/v1/comparisons?entity=cursor: comparisons as data, with the verdict and when each side is the call.
  • GET https://gildhq.com/api/v1/benchmarks?model=claude-opus-5-5: measured results with harness, variant, settings, evaluator and the quoted span.
  • GET https://gildhq.com/api/v1/experiments/{id}: GILD's own experiments with every run.
  • GET https://gildhq.com/api/v1/changes?since=2026-10-01: records changed since a date, oldest first.
  • GET https://gildhq.com/api/v1/openapi.json: the OpenAPI 3.1 description.
curl -s 'https://gildhq.com/api/v1/entities/cursor' | jq '.data.signals.practitionerSentiment'
curl -s 'https://gildhq.com/api/v1/claims?entity=cursor&support=supported&limit=200' | jq '.data[] | {text, supports}'

3. Ids, versions and the envelope

Ids are opaque and stable: prd_ for products, mdl_ for model releases, mfam_ for families, vnd_ for vendors, pln_ for plans, rte_ for API routes, hrn_ for harnesses, src_, evd_ and clm_ for sources, evidence and claims, cmp_ for comparisons and exp_ for experiments. A slug works wherever an id does; kind:slug picks one kind when two share a slug. A renamed slug answers 301 to the current one.

Every body carries schemaVersion (1.0), graphRevision (the content hash of the compiled evidence graph) and generatedAt, then data, page for lists, links and any warnings. Additive changes keep version 1; a breaking change ships as /api/v2 with v1 kept for at least six months.

4. Unknown values

A researched value is a Known state: known with the evidence ids behind it, estimated with its basis, unknown with what GILD tried, or not_applicable with the reason. The API never turns an unknown into 0, null or a missing field. A benchmark GILD has no result for is unknown, never zero.

5. Paging, caching and limits

Lists take limit (1 to 200, default 50) and cursor, the page.nextCursor of the previous page. When GILD publishes new data between your pages, the next call answers 409 revision_changed with a link to the first page, so no listing mixes two revisions.

Responses carry a strong ETag and Last-Modified. Send If-None-Match to get 304 when nothing changed. Lists and records cache for 5 minutes in browsers, change feeds for 1 minute.

Each IP address gets 120 requests in a burst, refilled at 60 a minute; an IPv6 /64 counts as one address. RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset report the state, and a 429 carries Retry-After. CORS allows any origin.

6. Errors

Errors are RFC 9457 problem details (application/problem+json) with type, title, status, detail and instance. invalid_parameter names the parameter and its allowed values. not_found, revision_changed and rate_limited mean what they say.

curl -s 'https://gildhq.com/api/v1/entities?kind=widget'

7. MCP

The MCP server at https://gildhq.com/api/mcp speaks Streamable HTTP without sessions and answers each request with JSON. It has eight read-only tools: search_entities, get_entity, get_decision_evidence, compare, get_benchmarks, get_source, get_evidence and changes_since, plus resources at gild://entity/{id} and gild://comparison/{slug}. The server card is at https://gildhq.com/.well-known/mcp.json.

get_decision_evidence takes the options you are weighing and your question, and returns the claims that bear on it with their supporting and contradicting evidence and the gaps GILD has not closed. Each option answers every constraint the question names, such as SSO or private deployment, and its coverage list shows which claims answer each one or that GILD holds none. It returns evidence, never a recommendation.

claude mcp add --transport http gild https://gildhq.com/api/mcp

8. Markdown and files

Product, model, comparison and research pages have a Markdown copy at the same address plus .md, with numbered citations that name each evidence id and source URL.

curl -s https://gildhq.com/products/cursor.md

https://gildhq.com/llms.txt and https://gildhq.com/llms-full.txt index every page. The source registry is at https://gildhq.com/sources.json.

9. Citing GILD

Cite GILD with the evidence id or the source URL for each claim you use, and link the record's canonicalUrl. Evidence comes with its form and its source's ties to vendors, so you can tell a vendor's own statement from an independent one.