AI Interpretation

The GlycanAge assistant is available over the API. There are two ways to use it, and you can use both.

	Endpoint	Use it for
One-shot	`POST /ai/interpretations`	A written interpretation of a result, in a single request.
Conversation	`POST /ai/conversations` + messages	A back-and-forth about a kit, with follow-up questions.

Both draw on the same data: the kit's released result, the age, sex and ethnicity recorded with it, the health questionnaire your customer completed when registering, and a curated corpus of glycan and IgG literature.

Everything is per kit

Your customers register their own kits and are not modelled as patients, so a kit and its single result are the whole subject. There is no result history to compare against and no way to ask about a person across several tests — if a customer buys twice, that is two unrelated kits. The assistant is told this explicitly and will not invent a trend.

Who the text is written for

Responses are written to your customer, in the second person, in the same voice as the consumer report they receive. Drop it into your own product as-is; it contains no GlycanAge branding, no greeting and no sign-off, and never mentions you.

One-shot interpretation

Send a kit code, get an interpretation back:

POST /ai/interpretations
Content-Type: application/json

{
  "kit_code": "GA-AB-123456"
}

{
  "kit_code": "GA-AB-123456",
  "interpretation": "Your glycan age of 48 sits four years above your chronological age of 44...",
  "generated_on": 1769558460000,
  "cached": false,
  "sources": []
}

interpretation is Markdown, structured as an overview, a per-index section, and considerations. sources lists any scientific literature the assistant cited.

Caching

Interpretations are cached per result. The first call generates one; every later call for the same kit returns the stored text.

Cached responses have "cached": true, cost nothing, and do not count against your rate limit or monthly budget — poll as freely as you like.

To regenerate, for example after the customer updated their health questionnaire:

{ "kit_code": "GA-AB-123456", "refresh": true }

You can also fetch a cached interpretation without ever risking a generation:

GET /ai/interpretations/kit/GA-AB-123456

This returns 404 if none has been generated yet — useful if you want to show an interpretation only when one already exists.

Steering the output

An optional instructions field (up to 2000 characters) lets you shape a single interpretation, for example to cap its length or match your house style:

{
  "kit_code": "GA-AB-123456",
  "refresh": true,
  "instructions": "Keep it under 300 words and avoid section headings."
}

Conversations

A conversation is always about one kit:

POST /ai/conversations
Content-Type: application/json

{ "kit_code": "GA-AB-123456" }

{
  "id": "9f2b...",
  "kit_code": "GA-AB-123456",
  "title": "Kit GA-AB-123456",
  "created_on": 1769558460000,
  "last_activity": 1769558460000
}

The assistant is seeded with the result when the conversation opens, so you never repeat context on a message:

POST /ai/conversations/9f2b.../messages
Content-Type: application/json

{ "message": "What does my B index mean?" }

{
  "id": "c31d...",
  "conversation_id": "9f2b...",
  "role": "assistant",
  "content": "Your bisecting GlcNAc index sits at the 64th percentile...",
  "sources": [],
  "created_on": 1769558520000
}

Read the transcript back at any time with GET /ai/conversations/{id}/messages, list conversations with GET /ai/conversations (filter with ?kit_code=), and remove one with DELETE /ai/conversations/{id}.

Streaming

For a chat interface, post to /messages/stream instead. The response is application/x-ndjson — one JSON object per line:

{"type":"text","content":"Your bisecting GlcNAc index "}
{"type":"text","content":"sits at the 64th percentile..."}
{"type":"complete","message":{"id":"c31d...","content":"...full reply...","sources":[]}}

Handle three line types:

text — append content to what you are displaying.
complete — the finished, persisted message. Use this as the authoritative version.
error — generation failed after the stream opened. The stream ends here.

The turn is persisted regardless, so a dropped connection loses nothing: re-read it from GET /ai/conversations/{id}/messages.

note

Rate limit and budget rejections are evaluated before the stream opens, so they arrive as an ordinary JSON error with an HTTP status — not as an error line.

Rate limits and budget

AI endpoints are metered per reseller account.

Control	Default	Error code when exceeded
Requests per minute	10	`rate_limit_exceeded`
Requests per day	500	`daily_rate_limit_exceeded`
Spend per calendar month	100 USD	`monthly_budget_exhausted`

Spend is the token cost of every model call your account makes, summed over the calendar month (UTC) and reset on the 1st. Cached interpretations are free and are not counted.

All three return 429 with a Retry-After header and a machine-readable code.

Any of these limits can be raised for your account — contact support@glycanage.com or your account manager.

Knowing where you stand

Every AI response carries the current state in headers, so you can back off before you are rejected:

Header	Meaning
`X-RateLimit-Limit` / `X-RateLimit-Remaining`	Requests allowed / left in the current minute
`X-RateLimit-Limit-Day` / `X-RateLimit-Remaining-Day`	Requests allowed / left in the trailing day
`X-AI-Budget-Limit-USD`	Your monthly budget
`X-AI-Budget-Used-USD`	Spend so far this month
`X-AI-Budget-Remaining-USD`	What is left

GET /ai/usage returns the same figures plus a breakdown, and does not consume quota:

{
  "enabled": true,
  "limits": {
    "requests_per_minute": 10,
    "requests_per_day": 500,
    "monthly_budget_usd": 100
  },
  "current_month": {
    "spend_usd": 12.4831,
    "remaining_usd": 87.5169,
    "requests": 214,
    "interpretations": 176,
    "conversation_messages": 38,
    "input_tokens": 4192883,
    "output_tokens": 214902
  }
}

Errors

AI endpoints use the same error envelope as the rest of the API, with a stable code you can branch on.

Status	Code	Meaning
`400`	`invalid_request`	Missing or malformed field.
`403`	`ai_disabled`	AI access is not enabled for your account.
`404`	`not_found`	Kit, conversation or interpretation does not exist, or is not yours.
`409`	`result_not_ready`	The kit has no released result yet.
`409`	`no_results`	The kit's result is no longer available.
`429`	`rate_limit_exceeded`, `daily_rate_limit_exceeded`, `monthly_budget_exhausted`	See above.
`502`	`empty_response`	The model returned nothing. Retry.

Wait for result.ready before calling either endpoint — until then every request is a 409 result_not_ready.

Responsible use

Responses are generated from your customer's GlycanAge result and the literature corpus. They are general wellness information — not medical advice, not a diagnosis, and not a substitute for a qualified professional.

Review generated text before putting it in front of a customer, as you would any generated content.
Present it as an interpretation of the test, not as guidance from you.
The assistant does not prescribe, and frames uncertain mechanisms as hypotheses rather than fact.

Sandbox

The AI endpoints work in the sandbox against simulated results, so you can build and test end-to-end. Sandbox usage is metered separately from production.

Bear in mind that sandbox result values are random, so the text will be coherent but the clinical picture it describes is meaningless — test your plumbing there, not your copy.

AI Interpretation

One-shot interpretation​

Caching​

Steering the output​

Conversations​

Streaming​

Rate limits and budget​

Knowing where you stand​

Errors​

Responsible use​

Sandbox​