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