API reference

post/api/chat

Ask a question

Searches the docs, and answers from the passages found, citing them as [1], [2] and so on.

Order of work: rate limit, retrieval, the confidence gate (below the threshold no model is called and the answer is the standard decline), the daily token budget, then the model.

The response is a stream in the Vercel AI SDK UI message format (server-sent events). It carries the answer as text deltas and two data parts: data-meta (a ChatMeta, sent first with the retrieval confidence and again at the end with the outcome) and data-citations (the numbered passages the model was shown, a Citation per passage).

A visitor cookie (ll_vid, HttpOnly) is set on the first call so a conversation can continue. Ask follow-ups by sending the returned conversationId back.

Request body (JSON)

messagestringrequired

1 to 500 charactersThe question. Whitespace at either end is trimmed before the length is checked.

conversationIdstring (uuid)

Continue a conversation. Omit to start one; the id comes back in ChatMeta.

surface"site" | "widget"

default "site"Where the question was asked. The widget's visitor cookie is partitioned for use in an iframe.

Example

curl -N 'https://help.phoenixcodes.org/api/chat' \
  -H 'Content-Type: application/json' \
  -d '{"message":"How do I verify a webhook signature?","surface":"site"}'

Responses

• 200The answer, streamed.text/event-stream · string
• 400The request is not valid. message says which field and why.application/json · Error
• 429Too many requests from this client. Wait retryAfterSeconds.application/json · Error
• 503A dependency (search, the model, or the database) is unavailable, or on /api/chat the daily token budget is used up (budget_exhausted, with resetsAt). escalate is true when a person should take over.application/json · Error

post/api/tickets

Talk to a human

Opens a support ticket for the admin queue. No email is sent anywhere: the ticket is a row a person reads in /admin. At most 5 per hour per client.

Request body (JSON)

namestringrequired

1 to 80 characters

emailstring (email)required

up to 200 characters

summarystringrequired

10 to 2000 characters

conversationIdstring (uuid)

The conversation the ticket is about.

Example

curl 'https://help.phoenixcodes.org/api/tickets' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","email":"ada@example.com","summary":"I asked about crypto payouts and the docs have no answer. Can a person help?","conversationId":"6f1c1f2e-8a0e-4c58-9a57-3a2f4a8b7c10"}'

Responses

• 201The ticket was created.application/json · Ticket
• 400The request is not valid. message says which field and why.application/json · Error
• 429Too many requests from this client. Wait retryAfterSeconds.application/json · Error
• 503A dependency (search, the model, or the database) is unavailable, or on /api/chat the daily token budget is used up (budget_exhausted, with resetsAt). escalate is true when a person should take over.application/json · Error

post/api/feedback

Rate an answer

A thumbs up (1) or down (-1) on an assistant answer, with an optional comment. One rating per answer: a second one replaces the first. messageId is the one in the ChatMeta of that answer. At most 30 per 10 minutes per client.

Request body (JSON)

messageIdstring (uuid)required

rating1 | -1required

1 is a thumbs up, -1 a thumbs down.

commentstring

up to 1000 characters

Example

curl 'https://help.phoenixcodes.org/api/feedback' \
  -H 'Content-Type: application/json' \
  -d '{"messageId":"0b9d2c1a-5e44-4e0f-b6d2-13f1d6a6f5ee","rating":-1,"comment":"The answer skipped the retry limit."}'

Responses

• 200The rating was saved.application/json · object
• 400The request is not valid. message says which field and why.application/json · Error
• 404There is no answer with that id.application/json · Error
• 429Too many requests from this client. Wait retryAfterSeconds.application/json · Error
• 503A dependency (search, the model, or the database) is unavailable, or on /api/chat the daily token budget is used up (budget_exhausted, with resetsAt). escalate is true when a person should take over.application/json · Error

get/api/eval/runs

Evaluation runs

The runs of pnpm eval, newest first: retrieval, declining, answer quality, speed, tokens and cost. These are the numbers on the "How well it works" page, /eval. Responses are cached for a minute at the edge. At most 60 per 10 minutes per client.

Query parameters

limitinteger

1 to 30 · default 10How many runs to return, newest first.

resultsboolean

default falseInclude the per-question results (each question, its answer and the judge's note). Large: leave it off for a history chart.

Example

curl 'https://help.phoenixcodes.org/api/eval/runs?limit=5'

Responses

• 200The runs. Empty before the first run has been recorded.application/json · object
• 400The request is not valid. message says which field and why.application/json · Error
• 429Too many requests from this client. Wait retryAfterSeconds.application/json · Error
• 503A dependency (search, the model, or the database) is unavailable, or on /api/chat the daily token budget is used up (budget_exhausted, with resetsAt). escalate is true when a person should take over.application/json · Error