API conventions

The resource envelope

GET /resources/datasets/{slug}.json returns one complete resource document. Available slugs are waypoints, relay-batches, and relay-events. Documentation has a separate Markdown surface at /resources/docs/{slug}.md.

The envelope contains kind, slug, title, summary, version, fields, schema, and records. fields is an ordered description list; schema validates one row; records contains the complete fixture for that version. Array order is convenient presentation, not a substitute for a declared ordering key.

type ResourceDocument<T> = {
  kind: 'dataset';
  slug: string;
  title: string;
  summary: string;
  version: string;
  fields: { name: string; type: string; description: string }[];
  schema: object;
  records: T[];
};

Identifiers and values

Station IDs use wp-NNN and batch IDs use batch-NNN. IDs are opaque references: join them for equality, without extracting region, status, or business meaning from the numeric suffix.

Timestamps are ISO 8601 strings in UTC. Capacity and units are integers in illustrative units. All fields are required in this fixture version; missing values, null, and numeric strings are not interchangeable. State strings are lowercase and case-sensitive.

Version a complete result

The catalog version is 2026.10.3. Check every document's version before joining records. If versions differ, fetch the documents again and refuse the join if the mismatch remains. This site does not expose historical versions at versioned URLs.

GET /api/v1/catalog lists the resources. POST /api/v1/reference/search accepts query and an optional limit of 1–5. POST /api/v1/fixtures/validate accepts a dataset slug and 1–20 example records for row-schema validation. Fetch the complete bounded fixture and filter locally; there is no transfer-write API. The machine-readable REST description is at /openapi.json. Public resources and tools require no account; assistant conversations use a separate token-scoped interface.

Use a deterministic tool

POST /mcp exposes search_reference, get_resource, validate_records, and ask_support over Streamable HTTP. Each operation uses the same authored catalog as the HTTP API and makes no model calls. The server accepts current 2026-07-28 and stateless 2025-era clients. Configure the exact HTTPS /mcp endpoint in your client; no account, API key, or session is required.

Requests are limited to 16 KiB, eight JSON nesting levels, and 256 aggregate members/elements. Search queries are limited to 256 UTF-8 bytes and five results. Validation accepts 1–20 rows; ask_support accepts a question up to 4,096 UTF-8 bytes and selects a fixed answer without storing the question; responses are limited to 32 KiB. See /privacy before using the service and send only synthetic examples.

Run a first MCP query

In a Node.js project, run npm install @modelcontextprotocol/client@2.3.1. Save this example as waypoint-mcp.mjs, replace YOUR_HOST with this site's hostname, then run node waypoint-mcp.mjs. The client completes the MCP handshake, searches the reference, and fetches the matching synthetic fixture. It should print 2026.10.3 waypoints 12. No account or model call is needed.

Read /privacy before connecting. The request and tool operations are recorded for research; use only the synthetic query shown here and do not send secrets or private material.

import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';

const client = new Client({ name: 'waypoint-first-query', version: '1.0.0' });
try {
  await client.connect(new StreamableHTTPClientTransport(new URL('https://YOUR_HOST/mcp')));
  const search = await client.callTool({
    name: 'search_reference',
    arguments: { query: 'Waypoint directory', limit: 5 },
  });
  const results = search.structuredContent?.results;
  const match = Array.isArray(results) && results.find(item => item.kind === 'dataset' && item.slug === 'waypoints');
  if (search.isError || !match) throw new Error('Station fixture not found');
  const resource = await client.callTool({
    name: 'get_resource',
    arguments: { kind: 'dataset', slug: match.slug },
  });
  const fixture = resource.structuredContent;
  if (resource.isError || !Array.isArray(fixture?.records)) throw new Error('Fixture fetch failed');
  console.log(fixture.version, fixture.slug, fixture.records.length);
} finally {
  await client.close();
}

Handle HTTP outcomes

A known resource returns 200. An unknown resource returns 404. Temporary service unavailability returns 503; treat that as a failed fetch rather than an empty result. Check response.ok before interpreting JSON.

Dataset records and schema are fixture content. They do not represent current availability, live transfers, or operational limits of a real service.

const response = await fetch('/resources/datasets/relay-batches.json');
if (!response.ok) {
  throw new Error(`Resource unavailable: ${response.status}`);
}
const document = await response.json();
if (document.version !== '2026.10.3') {
  throw new Error('Review examples for the current catalog version.');
}