# Waypoint Reference

> Schemas, query recipes, and deterministic fixtures for a fictional relay API.

Version: 2026.10.3. All stations, transfers, and events are synthetic examples. Resource documents are complete, read-only fixtures; there is no live transfer service. Cite the resource title, version, and URL.

## Docs
- [Your first resource query](https://waypointreference.com/resources/docs/quickstart.md?src=llms-full): Fetch a fixture, filter available stations, and check the result against a known answer.
- [API conventions](https://waypointreference.com/resources/docs/waypoint-api.md?src=llms-full): Resource envelopes, identifiers, field types, versioning, and the read-only REST and MCP surfaces.
- [Query recipes](https://waypointreference.com/resources/docs/querying-fixtures.md?src=llms-full): Join station names to transfers, aggregate capacity, and avoid double-counting lifecycle events.
- [Schemas and validation](https://waypointreference.com/resources/docs/schemas.md?src=llms-full): Validate primitive types, enums, timestamps, and relationships with explicit positive and negative examples.
- [Lifecycle and ordering](https://waypointreference.com/resources/docs/relay-lifecycle.md?src=llms-full): Reconstruct queued, in-transit, and delivered states from ordered events without assuming arrival order.
- [HTTP status codes](https://waypointreference.com/resources/docs/http-status-codes.md?src=llms-full): A selected guide to response classes, common codes, redirects, retries, and the headers that change what a client should do.
- [HTTP headers](https://waypointreference.com/resources/docs/http-headers.md?src=llms-full): A selected guide to request and response fields that describe content, caching, authentication, redirects, and retries.
- [Assistant API](https://waypointreference.com/resources/docs/assistant-api.md?src=llms-full): Ask the scripted resource assistant about schemas and examples through a token-scoped JSON conversation.

## API
- [OpenAPI description](https://waypointreference.com/openapi.json?src=llms-full): Existing stateless REST catalog, search, validation, and dataset fetch operations.
- [Machine catalog](https://waypointreference.com/api/v1/catalog?src=llms-full): Resource identifiers, versions, operations, and limits.
- [API conventions and MCP first query](https://waypointreference.com/resources/docs/waypoint-api.md?src=llms-full): Search and row-schema validation through JSON HTTP and MCP, with a complete client example.
- [Assistant API](https://waypointreference.com/resources/docs/assistant-api.md?src=llms-full): Conversation tokens, request formats, and practical limits.
- REST search: POST https://waypointreference.com/api/v1/reference/search with Content-Type: application/json and {"query":"Waypoint directory","limit":5}; results include the waypoints dataset.
- MCP endpoint: https://waypointreference.com/mcp (Streamable HTTP; search_reference, get_resource, validate_records, ask_support). No model calls or account required.

## Datasets
- [Waypoint directory](https://waypointreference.com/resources/datasets/waypoints.md?src=llms-full): Twelve sample stations across three regions, with typed states and capacity values. 12 records; includes fields, a row schema, and the synthetic records. [JSON](https://waypointreference.com/resources/datasets/waypoints.json?src=llms-full)
- [Relay batches](https://waypointreference.com/resources/datasets/relay-batches.md?src=llms-full): Twelve sample transfers with source and destination references, lifecycle states, and payload units. 12 records; includes fields, a row schema, and the synthetic records. [JSON](https://waypointreference.com/resources/datasets/relay-batches.json?src=llms-full)
- [Relay lifecycle events](https://waypointreference.com/resources/datasets/relay-events.md?src=llms-full): Thirty-one ordered sample events for reconstructing batch state and joining station details. 31 records; includes fields, a row schema, and the synthetic records. [JSON](https://waypointreference.com/resources/datasets/relay-events.json?src=llms-full)

## Optional
- [Resource assistant](https://waypointreference.com/chat?src=llms-full): Ask about the schemas, examples, and fixture results.
- [Privacy and terms](https://waypointreference.com/privacy?src=llms-full): Who runs this research site, what is recorded about requests and conversations, and the terms of use. Do not submit secrets or private information.

Read the records array in each dataset document. Require matching versions before joining documents. Use IDs as exact join keys; sequence orders events only within one batch. A source link value is a navigation hint, not a client identity.

# Your first resource query

Fetch a fixture, filter available stations, and check the result against a known answer.

Waypoint Reference · Version 2026.10.3

All network records are synthetic examples.

## A reference you can run

Waypoint Reference is a developer reference for a fictional relay API. It pairs concise guides with deterministic JSON fixtures so you can practice parsers, joins, validation, and summaries against known results.

Every station, transfer, and event is synthetic. This site serves read-only resource documents; it does not operate a relay network or accept transfer submissions. All guides and tables work without JavaScript.

## Fetch the station directory

Request the resource document, then read its records array. The envelope also contains its version, field descriptions, and a JSON Schema for an individual row. Replace YOUR_HOST with this site's origin.

```text
curl --fail --silent \
  https://YOUR_HOST/resources/datasets/waypoints.json

# In a browser on this site:
const response = await fetch('/resources/datasets/waypoints.json');
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const directory = await response.json();
console.log(directory.version, directory.records.length);
// 2026.10.3, 12
```

## Make a small, testable query

Filter on the exact ready state, then sum capacity. Version 2026.10.3 contains seven ready stations with a combined capacity of 900 units. Standby and maintenance stations are excluded.

```text
const ready = directory.records.filter(row => row.status === 'ready');
const capacity = ready.reduce((sum, row) => sum + row.capacity, 0);
console.log(ready.length, capacity);
// 7, 900
```

## Search the reference

Use the existing JSON search operation to find the station fixture. Replace YOUR_HOST with this site's origin. The response contains a dataset result with slug waypoints and a URL for the same complete fixture you just inspected. Search returns resource descriptions, not matching station rows.

```text
curl --fail-with-body --silent --show-error \
  -X POST https://YOUR_HOST/api/v1/reference/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"Waypoint directory","limit":5}'

# Look for: "kind":"dataset", "slug":"waypoints"
# Its URL is /resources/datasets/waypoints.json
```

## Choose the next step

Read API conventions for the envelope and type rules, Query recipes for joins and aggregations, or Lifecycle and ordering to reconstruct a batch from its events.

The scripted assistant can point to the reference and explain common fixture questions. Consult /privacy before sending a message, and keep credentials or confidential material out of your questions.


# API conventions

Resource envelopes, identifiers, field types, versioning, and the read-only REST and MCP surfaces.

Waypoint Reference · Version 2026.10.3

All network records are synthetic examples.

## 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.

```text
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.

```text
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.

```text
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.');
}
```


# Query recipes

Join station names to transfers, aggregate capacity, and avoid double-counting lifecycle events.

Waypoint Reference · Version 2026.10.3

All network records are synthetic examples.

## Fetch related documents together

Load the directory and batches, verify that their versions agree, and build an ID index. The fixtures are small, but this pattern also avoids repeatedly scanning the directory.

```text
const paths = ['waypoints', 'relay-batches'];
const [directory, batches] = await Promise.all(paths.map(async slug => {
  const response = await fetch(`/resources/datasets/${slug}.json`);
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}));
if (directory.version !== batches.version) throw new Error('Version mismatch');
const byId = new Map(directory.records.map(row => [row.id, row]));
```

## Join a batch to its endpoints

Resolve source_id and destination_id through the directory's id field. A missing reference is an integrity error; do not silently replace it with a station that happens to share a name. Batch batch-001 travels from Alder Station to Morrow Field and carries 42 units.

```text
const batch = batches.records.find(row => row.id === 'batch-001');
if (!batch) throw new Error('Batch not found');
const source = byId.get(batch.source_id);
const destination = byId.get(batch.destination_id);
if (!source || !destination) throw new Error('Unresolved station reference');
console.log(`${source.name} → ${destination.name}: ${batch.units}`);
// Alder Station → Morrow Field: 42
```

## Aggregate once per entity

The catalog contains 12 batches totaling 500 units. Eight delivered batches total 355 units; three in-transit batches total 97; one queued batch contains 48. These are stable expected answers for this version.

An event repeats its batch's units at each lifecycle stage. Summing all event units would count the same payload more than once. Aggregate batches for throughput, or restrict events to delivered before summing completed payload.

```text
const delivered = batches.records.filter(row => row.state === 'delivered');
const total = delivered.reduce((sum, row) => sum + row.units, 0);
console.log(delivered.length, total);
// 8, 355
```

## Group capacity by region

Across all station states, the north has 340 capacity units, central has 400, and south has 520. The combined total is 1,260. Include the state filter explicitly if you only want ready capacity.

```text
const capacityByRegion = directory.records.reduce((groups, row) => {
  groups[row.region] = (groups[row.region] ?? 0) + row.capacity;
  return groups;
}, {});
// { north: 340, central: 400, south: 520 }
```


# Schemas and validation

Validate primitive types, enums, timestamps, and relationships with explicit positive and negative examples.

Waypoint Reference · Version 2026.10.3

All network records are synthetic examples.

## Validate rows, then relationships

Each dataset's schema property is a JSON Schema 2020-12 document for one record, not the enclosing resource document. It declares required properties, allowed values, numeric bounds, and additionalProperties: false.

Enable date-time format validation in your validator. POST /api/v1/fixtures/validate checks rows against these fixed schemas and returns at most ten errors without echoing supplied values. Records are processed transiently, not stored. Schema validation alone cannot resolve foreign keys or enforce lifecycle order; perform those checks after every row passes.

## A valid station

This row satisfies the waypoint schema. synthetic must be the boolean true, and capacity must be a non-negative integer.

```text
{
  "id": "wp-001",
  "name": "Alder Station",
  "region": "north",
  "status": "ready",
  "capacity": 120,
  "timezone": "UTC",
  "synthetic": true
}
```

## Useful negative cases

Starting from that valid row, replacing capacity with the string "120" must fail. A capacity of -1 must fail. Replacing status with "online" must fail. Removing id or adding an undeclared credential field must fail.

Likewise, a syntactically valid wp-999 reference in a batch can pass a row schema but fail catalog integrity because no station with that ID exists. Keep syntax and relationship failures separate in your test output.

## Catalog integrity checklist

Require unique IDs within each dataset and matching versions across documents. Every batch source_id and destination_id must resolve to a different station. Every event batch_id must resolve to a batch, and its waypoint_id must match the correct endpoint for that stage.

Per batch, sequence starts at 1 and has no gaps or duplicates. Timestamps increase, event units match batch units, and the final event agrees with the batch's state. These deterministic fixtures contain examples of queued, in-transit, and completed lifecycles.


# Lifecycle and ordering

Reconstruct queued, in-transit, and delivered states from ordered events without assuming arrival order.

Waypoint Reference · Version 2026.10.3

All network records are synthetic examples.

## Three events, three states

A queued event creates a batch at its source station. A dispatched event moves the state to in_transit and still references the source. A delivered event changes the state to delivered and references the destination.

The fixture snapshot contains eight three-event delivered lifecycles, three two-event in-transit lifecycles, and one single-event queued lifecycle: 31 events in total. Missing later stages in this snapshot are deliberate, not malformed records.

```text
queued      → state: queued      · source station
dispatched  → state: in_transit  · source station
delivered   → state: delivered   · destination station
```

## Order within a batch

Group by batch_id, deduplicate by id, and sort by sequence within each group. sequence is local to one batch, so it must never be used as a global cursor. Check timestamps as a consistency constraint, not as an identity key.

If two events reuse a sequence with different IDs or content, report a conflict. If an event is absent in the middle of a sequence, report a gap rather than inventing it.

## Replay a known example

Batch batch-001 queues at 08:00 UTC, dispatches at 08:02, and delivers at 08:10 on October 1, 2026. It carries 42 units from wp-001 to wp-003. The authored end-to-end duration is 10 minutes.

```text
const response = await fetch('/resources/datasets/relay-events.json');
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const fixture = await response.json();
const events = fixture.records
  .filter(row => row.batch_id === 'batch-001')
  .sort((a, b) => a.sequence - b.sequence);
// queued, dispatched, delivered
const elapsedMs = Date.parse(events.at(-1).timestamp)
  - Date.parse(events[0].timestamp);
console.log(elapsedMs / 60_000);
// 10
```

## Treat the snapshot as a fixture

All timestamps and IDs are stable within a catalog version. There is no scheduler advancing these batches, no webhook endpoint, and no polling stream. Re-fetching does not turn a queued sample into a delivered one.

Use the fixture to test deterministic reconstruction and error handling. It does not model network delays, delivery guarantees, or the complete behavior of a production event system.


# HTTP status codes

A selected guide to response classes, common codes, redirects, retries, and the headers that change what a client should do.

Waypoint Reference · Version 2026.10.3

All network records are synthetic examples.

## Start with the class

HTTP status codes are protocol standards; the relay fixtures elsewhere on this site are synthetic. Each status code has three digits. The first digit gives the broad result; the remaining digits identify a more specific condition. A 1xx response is interim and can be followed by a final response. The other classes describe the final response.

This is a selected working guide, not the complete set of assigned codes. Use the IANA registry for the current assignment list and the cited specifications for exact behavior.

```text
1xx  Informational — request progress before a final response
2xx  Successful — request received and accepted
3xx  Redirection — further action is needed to complete the request
4xx  Client error — the request cannot be fulfilled as sent
5xx  Server error — the server could not fulfill an apparently valid request
```

## Successful responses

200 OK means the request succeeded; the response content depends on the request method. 201 Created identifies a newly created resource. 202 Accepted means processing has been accepted but is not complete. 204 No Content succeeds without response content. 206 Partial Content carries the requested range of a representation.

Do not parse a body merely because a status is 2xx. A 204 response has no content, while a 202 response does not promise the requested work is finished.

```text
200 OK                Request succeeded
201 Created           New resource created
202 Accepted          Processing accepted, not completed
204 No Content        Success with no response content
206 Partial Content   A requested representation range
```

## Redirects and conditional requests

301 and 308 indicate a permanent new URI; 302 and 307 indicate a temporary one. For an automatic redirect, 307 and 308 preserve the request method. Historical behavior allows a client to change POST to GET after 301 or 302. A 303 response directs a client to retrieve another resource, normally with GET.

304 Not Modified is in the 3xx class but is not an instruction to fetch a new URI. It answers a conditional GET or HEAD when the client's stored representation can be reused. Read the response headers before deciding what to fetch or cache.

```text
301 / 308  Permanent new URI
302 / 307  Temporary new URI
303        See another resource
304        Conditional response; reuse a stored representation
```

## Request and access problems

400 indicates a problem with the request. 401 requires an authentication challenge; 403 means the server refuses the request. 404 means no current representation was found or its existence is not disclosed; 410 is preferable when the server knows the absence is likely permanent. 405 means the method is unsupported for that resource and the response must include Allow.

409 reports a conflict with the resource's current state. 413 means request content is too large; 415 means its media type is unsupported. 429 means too many requests in a period; a Retry-After header may suggest when to try again. Do not treat every 4xx as a missing URL.

```text
400 Bad Request       Request problem
401 Unauthorized      Authentication challenge
403 Forbidden         Request refused
404 Not Found         No current representation disclosed
405 Method Not Allowed  Method unsupported; inspect Allow
409 Conflict          State conflict
410 Gone              Likely permanent absence
413 Content Too Large Request content exceeds a limit
415 Unsupported Media Type  Content format not accepted
429 Too Many Requests Rate limit; inspect Retry-After if present
```

## Server and gateway problems

500 indicates an unexpected server failure. 502 and 504 describe gateway or proxy problems with an upstream server: an invalid response and a timeout, respectively. 503 indicates temporary unavailability, such as overload or maintenance, and may include Retry-After.

For Waypoint's resource API, a 503 means the fetch failed; it is not an empty fixture. Check the response status before parsing content. Before retrying any request, consider whether repeating its method and body could repeat an effect.

```text
500 Internal Server Error  Unexpected server failure
502 Bad Gateway            Invalid upstream response
503 Service Unavailable    Temporary inability to serve
504 Gateway Timeout        Upstream response timed out
```

## Related

- [HTTP headers](/resources/docs/http-headers.md)

## Sources

- [IANA HTTP Status Code Registry](https://www.iana.org/assignments/http-status-codes)
- [RFC 9110, HTTP Semantics, Section 15](https://www.rfc-editor.org/rfc/rfc9110.html#section-15)
- [RFC 6585, Section 4: 429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585.html#section-4)


# HTTP headers

A selected guide to request and response fields that describe content, caching, authentication, redirects, and retries.

Waypoint Reference · Version 2026.10.3

All network records are synthetic examples.

## Read a field in its message

HTTP header fields appear before message content. Their names are case-insensitive, but the meaning of a field depends on whether it is in a request or response and on the status and method. This is a selected guide, not a complete field registry; consult IANA for current field assignments.

Header values can contain credentials or personal data. Do not copy Authorization or Cookie values into logs, bug reports, or example URLs.

```text
Request:  Accept: application/json
Response: Content-Type: application/json
```

## Content and negotiation

Accept in a request expresses which response media types the client prefers. Content-Type describes the media type of the content in the message carrying it, whether that message is a request or a response. Content-Encoding identifies content codings applied to the representation; decode those codings before interpreting the media type.

A successful status alone does not identify the content format. Inspect Content-Type before parsing a response, and check Content-Encoding when handling encoded content.

```text
Accept: application/json
Content-Type: application/json
Content-Encoding: gzip
```

## Validators and cache control

A response ETag is a representation validator. A later conditional GET can send If-None-Match with that value; a matching condition can produce 304 Not Modified so the client can reuse a stored response. A validator is not, by itself, permission to store a response.

Cache-Control: no-store tells caches not to store the response. Cache-Control: no-cache allows storage but requires successful validation before reuse. Vary names request fields that affect which stored response can be reused, such as Accept-Encoding. Apply the directives and Vary together when deciding whether a cached response fits a new request.

```text
ETag: "example-v1"
If-None-Match: "example-v1"
Cache-Control: no-cache
Vary: Accept-Encoding
```

## Redirects and access

Location identifies the target URI for a redirect response. On 201 Created, it can identify the newly created resource. A 401 response carries WWW-Authenticate with at least one challenge; a client can send Authorization credentials for a protected resource. Never treat a redirect target as permission to forward credentials to another origin.

A 405 Method Not Allowed response includes Allow to list methods currently supported by the target resource. Read it before choosing another method.

```text
Location: /new-resource
WWW-Authenticate: Bearer realm="example"
Authorization: Bearer <redacted>
Allow: GET, HEAD
```

## Retry guidance

Retry-After can appear with 503 Service Unavailable to suggest how long a service is expected to be unavailable, and with a redirect to suggest a delay before following it. A 429 Too Many Requests response may include Retry-After to suggest when to try again. The value is either a non-negative number of seconds or an HTTP date.

The header is advice about timing, not a guarantee that a retry will succeed. Before repeating a request, consider whether repeating its method and body can repeat an effect.

```text
Retry-After: 120
Retry-After: Wed, 21 Oct 2015 07:28:00 GMT
```

## Sources

- [IANA HTTP Field Name Registry](https://www.iana.org/assignments/http-fields)
- [RFC 9110, HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html)
- [RFC 9111, HTTP Caching](https://www.rfc-editor.org/rfc/rfc9111.html)
- [RFC 6585, Section 4: 429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585.html#section-4)


# Assistant API

Ask the scripted resource assistant about schemas and examples through a token-scoped JSON conversation.

Waypoint Reference · Version 2026.10.3

All network records are synthetic examples.

## Ask about the reference

The Waypoint assistant currently selects from fixed answers about the schemas, sample records, and query recipes on this site. It makes no AI call, cannot browse the web, run your code, or perform transfers. MCP clients can call ask_support with a question of up to 4,096 UTF-8 bytes.

Consult /privacy before use. Requests and conversations are recorded. Do not include passwords, API keys, personal data, or confidential source material. Fixed answers are general guidance; check them against the versioned fixtures.

## Create a conversation

POST /api/v1/encounters creates a conversation and returns id, token, expiresAt, and links. Keep the token in your client; it authorizes reads and submissions for exactly that conversation. Never put it in a URL. Conversations expire after 24 hours.

```text
curl -X POST https://YOUR_HOST/api/v1/encounters \
  -H 'Content-Type: application/json' -d '{}'
```

## Submit a question

Send plain text, no more than 4,096 UTF-8 bytes, with a new UUID clientMessageId. Reuse that UUID only when retrying the identical question. There are at most eight replies per conversation, including service-pause responses.

```text
POST /api/v1/encounters/{id}/messages
Authorization: Bearer {token}
Content-Type: application/json

{
  "message": "Why should I aggregate batches instead of lifecycle events?",
  "clientMessageId": "7776d4b3-3121-4b28-881c-aac17c25c7f1"
}
```

## Read responses and handle limits

A successful submission returns message, status, repliesUsed, and links. status is scripted for a fixed answer, paused for an unavailable service response, or generated if AI replies are separately enabled later. Pausing does not prevent reading the public resources.

GET /api/v1/encounters/{id}, with the same Authorization header, returns the transcript and remaining conversation context. Invalid credentials return 401; expired access returns 410; a pending submission can return 409; exhausted limits can return 429. Preserve your draft and check the response before retrying.

# Waypoint directory

Twelve sample stations across three regions, with typed states and capacity values.

Waypoint Reference · Version 2026.10.3

All network records are synthetic examples.

## Fields

- id (string): Stable station identifier; matches ^wp-[0-9]{3}$.
- name (string): Display name of the fictional station.
- region (string): One of north, central, or south.
- status (string): One of ready, standby, or maintenance.
- capacity (integer): Non-negative illustrative capacity; arbitrary units, not a live limit.
- timezone (string): UTC for every station in this fixture version.
- synthetic (boolean): Always true: this is an authored example.

## Row schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "name",
    "region",
    "status",
    "capacity",
    "timezone",
    "synthetic"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^wp-[0-9]{3}$"
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "region": {
      "enum": [
        "north",
        "central",
        "south"
      ]
    },
    "status": {
      "enum": [
        "ready",
        "standby",
        "maintenance"
      ]
    },
    "capacity": {
      "type": "integer",
      "minimum": 0
    },
    "timezone": {
      "const": "UTC"
    },
    "synthetic": {
      "const": true
    }
  }
}
```

## Records

```json
[
  {
    "id": "wp-001",
    "name": "Alder Station",
    "region": "north",
    "status": "ready",
    "capacity": 120,
    "timezone": "UTC",
    "synthetic": true
  },
  {
    "id": "wp-002",
    "name": "Flint Crossing",
    "region": "north",
    "status": "standby",
    "capacity": 80,
    "timezone": "UTC",
    "synthetic": true
  },
  {
    "id": "wp-003",
    "name": "Morrow Field",
    "region": "central",
    "status": "ready",
    "capacity": 160,
    "timezone": "UTC",
    "synthetic": true
  },
  {
    "id": "wp-004",
    "name": "Hollow Creek",
    "region": "central",
    "status": "maintenance",
    "capacity": 60,
    "timezone": "UTC",
    "synthetic": true
  },
  {
    "id": "wp-005",
    "name": "Juniper Reach",
    "region": "south",
    "status": "ready",
    "capacity": 140,
    "timezone": "UTC",
    "synthetic": true
  },
  {
    "id": "wp-006",
    "name": "Slate Landing",
    "region": "south",
    "status": "standby",
    "capacity": 100,
    "timezone": "UTC",
    "synthetic": true
  },
  {
    "id": "wp-007",
    "name": "Cedar Knoll",
    "region": "north",
    "status": "ready",
    "capacity": 90,
    "timezone": "UTC",
    "synthetic": true
  },
  {
    "id": "wp-008",
    "name": "Birch Gate",
    "region": "north",
    "status": "maintenance",
    "capacity": 50,
    "timezone": "UTC",
    "synthetic": true
  },
  {
    "id": "wp-009",
    "name": "Quarry Run",
    "region": "central",
    "status": "ready",
    "capacity": 110,
    "timezone": "UTC",
    "synthetic": true
  },
  {
    "id": "wp-010",
    "name": "Moss Junction",
    "region": "central",
    "status": "standby",
    "capacity": 70,
    "timezone": "UTC",
    "synthetic": true
  },
  {
    "id": "wp-011",
    "name": "Willow Bend",
    "region": "south",
    "status": "ready",
    "capacity": 130,
    "timezone": "UTC",
    "synthetic": true
  },
  {
    "id": "wp-012",
    "name": "Pine Hollow",
    "region": "south",
    "status": "ready",
    "capacity": 150,
    "timezone": "UTC",
    "synthetic": true
  }
]
```


# Relay batches

Twelve sample transfers with source and destination references, lifecycle states, and payload units.

Waypoint Reference · Version 2026.10.3

All network records are synthetic examples.

## Fields

- id (string): Stable batch identifier; matches ^batch-[0-9]{3}$.
- source_id (string): Foreign key to the originating waypoint's id.
- destination_id (string): Foreign key to a different destination waypoint's id.
- units (integer): Positive illustrative payload size. Count once per batch, not once per event.
- state (string): One of queued, in_transit, or delivered; derived from the last lifecycle event.
- created_at (string): Fixed ISO 8601 UTC timestamp, equal to the queued event timestamp.
- synthetic (boolean): Always true: this transfer did not occur in a real network.

## Row schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "source_id",
    "destination_id",
    "units",
    "state",
    "created_at",
    "synthetic"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^batch-[0-9]{3}$"
    },
    "source_id": {
      "type": "string",
      "pattern": "^wp-[0-9]{3}$"
    },
    "destination_id": {
      "type": "string",
      "pattern": "^wp-[0-9]{3}$"
    },
    "units": {
      "type": "integer",
      "minimum": 1
    },
    "state": {
      "enum": [
        "queued",
        "in_transit",
        "delivered"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "synthetic": {
      "const": true
    }
  }
}
```

## Records

```json
[
  {
    "id": "batch-001",
    "source_id": "wp-001",
    "destination_id": "wp-003",
    "units": 42,
    "state": "delivered",
    "created_at": "2026-10-01T08:00:00.000Z",
    "synthetic": true
  },
  {
    "id": "batch-002",
    "source_id": "wp-003",
    "destination_id": "wp-005",
    "units": 36,
    "state": "delivered",
    "created_at": "2026-10-01T08:15:00.000Z",
    "synthetic": true
  },
  {
    "id": "batch-003",
    "source_id": "wp-005",
    "destination_id": "wp-011",
    "units": 28,
    "state": "delivered",
    "created_at": "2026-10-01T08:30:00.000Z",
    "synthetic": true
  },
  {
    "id": "batch-004",
    "source_id": "wp-007",
    "destination_id": "wp-001",
    "units": 54,
    "state": "delivered",
    "created_at": "2026-10-01T08:45:00.000Z",
    "synthetic": true
  },
  {
    "id": "batch-005",
    "source_id": "wp-009",
    "destination_id": "wp-003",
    "units": 65,
    "state": "delivered",
    "created_at": "2026-10-01T09:00:00.000Z",
    "synthetic": true
  },
  {
    "id": "batch-006",
    "source_id": "wp-011",
    "destination_id": "wp-012",
    "units": 40,
    "state": "delivered",
    "created_at": "2026-10-01T09:15:00.000Z",
    "synthetic": true
  },
  {
    "id": "batch-007",
    "source_id": "wp-012",
    "destination_id": "wp-005",
    "units": 72,
    "state": "delivered",
    "created_at": "2026-10-01T09:30:00.000Z",
    "synthetic": true
  },
  {
    "id": "batch-008",
    "source_id": "wp-001",
    "destination_id": "wp-009",
    "units": 18,
    "state": "delivered",
    "created_at": "2026-10-01T09:45:00.000Z",
    "synthetic": true
  },
  {
    "id": "batch-009",
    "source_id": "wp-003",
    "destination_id": "wp-011",
    "units": 45,
    "state": "in_transit",
    "created_at": "2026-10-01T10:00:00.000Z",
    "synthetic": true
  },
  {
    "id": "batch-010",
    "source_id": "wp-007",
    "destination_id": "wp-012",
    "units": 30,
    "state": "in_transit",
    "created_at": "2026-10-01T10:15:00.000Z",
    "synthetic": true
  },
  {
    "id": "batch-011",
    "source_id": "wp-005",
    "destination_id": "wp-009",
    "units": 22,
    "state": "in_transit",
    "created_at": "2026-10-01T10:30:00.000Z",
    "synthetic": true
  },
  {
    "id": "batch-012",
    "source_id": "wp-009",
    "destination_id": "wp-001",
    "units": 48,
    "state": "queued",
    "created_at": "2026-10-01T10:45:00.000Z",
    "synthetic": true
  }
]
```


# Relay lifecycle events

Thirty-one ordered sample events for reconstructing batch state and joining station details.

Waypoint Reference · Version 2026.10.3

All network records are synthetic examples.

## Fields

- id (string): Stable event identifier; unique across this dataset.
- batch_id (string): Foreign key to the batch that owns this event.
- waypoint_id (string): Source station for queued/dispatched events; destination for delivered events.
- event (string): One of queued, dispatched, or delivered.
- timestamp (string): Fixed ISO 8601 UTC timestamp; increasing within each batch.
- sequence (integer): Contiguous ordering within one batch, starting at 1; never a global event offset.
- units (integer): The owning batch's units, repeated for event context; do not sum across all lifecycle stages.
- synthetic (boolean): Always true: this is a deterministic example event.

## Row schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "batch_id",
    "waypoint_id",
    "event",
    "timestamp",
    "sequence",
    "units",
    "synthetic"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^evt-[0-9]{3}-[1-3]$"
    },
    "batch_id": {
      "type": "string",
      "pattern": "^batch-[0-9]{3}$"
    },
    "waypoint_id": {
      "type": "string",
      "pattern": "^wp-[0-9]{3}$"
    },
    "event": {
      "enum": [
        "queued",
        "dispatched",
        "delivered"
      ]
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"
    },
    "sequence": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3
    },
    "units": {
      "type": "integer",
      "minimum": 1
    },
    "synthetic": {
      "const": true
    }
  }
}
```

## Records

```json
[
  {
    "id": "evt-001-1",
    "batch_id": "batch-001",
    "waypoint_id": "wp-001",
    "event": "queued",
    "timestamp": "2026-10-01T08:00:00.000Z",
    "sequence": 1,
    "units": 42,
    "synthetic": true
  },
  {
    "id": "evt-001-2",
    "batch_id": "batch-001",
    "waypoint_id": "wp-001",
    "event": "dispatched",
    "timestamp": "2026-10-01T08:02:00.000Z",
    "sequence": 2,
    "units": 42,
    "synthetic": true
  },
  {
    "id": "evt-001-3",
    "batch_id": "batch-001",
    "waypoint_id": "wp-003",
    "event": "delivered",
    "timestamp": "2026-10-01T08:10:00.000Z",
    "sequence": 3,
    "units": 42,
    "synthetic": true
  },
  {
    "id": "evt-002-1",
    "batch_id": "batch-002",
    "waypoint_id": "wp-003",
    "event": "queued",
    "timestamp": "2026-10-01T08:15:00.000Z",
    "sequence": 1,
    "units": 36,
    "synthetic": true
  },
  {
    "id": "evt-002-2",
    "batch_id": "batch-002",
    "waypoint_id": "wp-003",
    "event": "dispatched",
    "timestamp": "2026-10-01T08:17:00.000Z",
    "sequence": 2,
    "units": 36,
    "synthetic": true
  },
  {
    "id": "evt-002-3",
    "batch_id": "batch-002",
    "waypoint_id": "wp-005",
    "event": "delivered",
    "timestamp": "2026-10-01T08:25:00.000Z",
    "sequence": 3,
    "units": 36,
    "synthetic": true
  },
  {
    "id": "evt-003-1",
    "batch_id": "batch-003",
    "waypoint_id": "wp-005",
    "event": "queued",
    "timestamp": "2026-10-01T08:30:00.000Z",
    "sequence": 1,
    "units": 28,
    "synthetic": true
  },
  {
    "id": "evt-003-2",
    "batch_id": "batch-003",
    "waypoint_id": "wp-005",
    "event": "dispatched",
    "timestamp": "2026-10-01T08:32:00.000Z",
    "sequence": 2,
    "units": 28,
    "synthetic": true
  },
  {
    "id": "evt-003-3",
    "batch_id": "batch-003",
    "waypoint_id": "wp-011",
    "event": "delivered",
    "timestamp": "2026-10-01T08:40:00.000Z",
    "sequence": 3,
    "units": 28,
    "synthetic": true
  },
  {
    "id": "evt-004-1",
    "batch_id": "batch-004",
    "waypoint_id": "wp-007",
    "event": "queued",
    "timestamp": "2026-10-01T08:45:00.000Z",
    "sequence": 1,
    "units": 54,
    "synthetic": true
  },
  {
    "id": "evt-004-2",
    "batch_id": "batch-004",
    "waypoint_id": "wp-007",
    "event": "dispatched",
    "timestamp": "2026-10-01T08:47:00.000Z",
    "sequence": 2,
    "units": 54,
    "synthetic": true
  },
  {
    "id": "evt-004-3",
    "batch_id": "batch-004",
    "waypoint_id": "wp-001",
    "event": "delivered",
    "timestamp": "2026-10-01T08:55:00.000Z",
    "sequence": 3,
    "units": 54,
    "synthetic": true
  },
  {
    "id": "evt-005-1",
    "batch_id": "batch-005",
    "waypoint_id": "wp-009",
    "event": "queued",
    "timestamp": "2026-10-01T09:00:00.000Z",
    "sequence": 1,
    "units": 65,
    "synthetic": true
  },
  {
    "id": "evt-005-2",
    "batch_id": "batch-005",
    "waypoint_id": "wp-009",
    "event": "dispatched",
    "timestamp": "2026-10-01T09:02:00.000Z",
    "sequence": 2,
    "units": 65,
    "synthetic": true
  },
  {
    "id": "evt-005-3",
    "batch_id": "batch-005",
    "waypoint_id": "wp-003",
    "event": "delivered",
    "timestamp": "2026-10-01T09:10:00.000Z",
    "sequence": 3,
    "units": 65,
    "synthetic": true
  },
  {
    "id": "evt-006-1",
    "batch_id": "batch-006",
    "waypoint_id": "wp-011",
    "event": "queued",
    "timestamp": "2026-10-01T09:15:00.000Z",
    "sequence": 1,
    "units": 40,
    "synthetic": true
  },
  {
    "id": "evt-006-2",
    "batch_id": "batch-006",
    "waypoint_id": "wp-011",
    "event": "dispatched",
    "timestamp": "2026-10-01T09:17:00.000Z",
    "sequence": 2,
    "units": 40,
    "synthetic": true
  },
  {
    "id": "evt-006-3",
    "batch_id": "batch-006",
    "waypoint_id": "wp-012",
    "event": "delivered",
    "timestamp": "2026-10-01T09:25:00.000Z",
    "sequence": 3,
    "units": 40,
    "synthetic": true
  },
  {
    "id": "evt-007-1",
    "batch_id": "batch-007",
    "waypoint_id": "wp-012",
    "event": "queued",
    "timestamp": "2026-10-01T09:30:00.000Z",
    "sequence": 1,
    "units": 72,
    "synthetic": true
  },
  {
    "id": "evt-007-2",
    "batch_id": "batch-007",
    "waypoint_id": "wp-012",
    "event": "dispatched",
    "timestamp": "2026-10-01T09:32:00.000Z",
    "sequence": 2,
    "units": 72,
    "synthetic": true
  },
  {
    "id": "evt-007-3",
    "batch_id": "batch-007",
    "waypoint_id": "wp-005",
    "event": "delivered",
    "timestamp": "2026-10-01T09:40:00.000Z",
    "sequence": 3,
    "units": 72,
    "synthetic": true
  },
  {
    "id": "evt-008-1",
    "batch_id": "batch-008",
    "waypoint_id": "wp-001",
    "event": "queued",
    "timestamp": "2026-10-01T09:45:00.000Z",
    "sequence": 1,
    "units": 18,
    "synthetic": true
  },
  {
    "id": "evt-008-2",
    "batch_id": "batch-008",
    "waypoint_id": "wp-001",
    "event": "dispatched",
    "timestamp": "2026-10-01T09:47:00.000Z",
    "sequence": 2,
    "units": 18,
    "synthetic": true
  },
  {
    "id": "evt-008-3",
    "batch_id": "batch-008",
    "waypoint_id": "wp-009",
    "event": "delivered",
    "timestamp": "2026-10-01T09:55:00.000Z",
    "sequence": 3,
    "units": 18,
    "synthetic": true
  },
  {
    "id": "evt-009-1",
    "batch_id": "batch-009",
    "waypoint_id": "wp-003",
    "event": "queued",
    "timestamp": "2026-10-01T10:00:00.000Z",
    "sequence": 1,
    "units": 45,
    "synthetic": true
  },
  {
    "id": "evt-009-2",
    "batch_id": "batch-009",
    "waypoint_id": "wp-003",
    "event": "dispatched",
    "timestamp": "2026-10-01T10:02:00.000Z",
    "sequence": 2,
    "units": 45,
    "synthetic": true
  },
  {
    "id": "evt-010-1",
    "batch_id": "batch-010",
    "waypoint_id": "wp-007",
    "event": "queued",
    "timestamp": "2026-10-01T10:15:00.000Z",
    "sequence": 1,
    "units": 30,
    "synthetic": true
  },
  {
    "id": "evt-010-2",
    "batch_id": "batch-010",
    "waypoint_id": "wp-007",
    "event": "dispatched",
    "timestamp": "2026-10-01T10:17:00.000Z",
    "sequence": 2,
    "units": 30,
    "synthetic": true
  },
  {
    "id": "evt-011-1",
    "batch_id": "batch-011",
    "waypoint_id": "wp-005",
    "event": "queued",
    "timestamp": "2026-10-01T10:30:00.000Z",
    "sequence": 1,
    "units": 22,
    "synthetic": true
  },
  {
    "id": "evt-011-2",
    "batch_id": "batch-011",
    "waypoint_id": "wp-005",
    "event": "dispatched",
    "timestamp": "2026-10-01T10:32:00.000Z",
    "sequence": 2,
    "units": 22,
    "synthetic": true
  },
  {
    "id": "evt-012-1",
    "batch_id": "batch-012",
    "waypoint_id": "wp-009",
    "event": "queued",
    "timestamp": "2026-10-01T10:45:00.000Z",
    "sequence": 1,
    "units": 48,
    "synthetic": true
  }
]
```