Introduction

AskEngine interviews your users at scale and turns what they say into a belief layer — a living, queryable model of what your users need and how confident you can be about it. Instead of a pile of transcripts, you get structured beliefs, each one traceable back to the exact moments that justify it.

This API is how you read that belief layer out of AskEngine and into wherever your team already works: an MCP server for your coding agent, an internal dashboard, a Slack digest, a weekly report.

The mental model

Almost everything in the API is one of a few connected objects:

• Interviews — the raw conversations. You mostly meet these through studies rather than directly.
• Studies — a piece of research. A study gathers interviews around a question you care about.
• Evidence — the specific quotes and moments pulled from interviews. Every claim traces back to evidence, and you can search it directly.
• Signals — patterns worth paying attention to, distilled across studies. A signal has a stage (emerging → established → actionable) and a trajectory (rising, stable, declining, new) so you can tell what's heating up.
• Uncertainties — the gaps in what AskEngine knows, surfaced as open questions rather than hidden.
• Recommendations — concrete next steps derived from signals. You can read them and record what you did: accept, dismiss, or mark one shipped or validated.

Read it as a chain: interviews feed studies, studies produce evidence, evidence supports signals, signals drive recommendations — while uncertainties track what you don't know yet. Most endpoints are just a view onto one link in that chain.

Using the API

The base URL is https://tame-dove-965.convex.site. Authenticate with a bearer API key from your team settings — one key maps to one team, and AskEngine resolves the team from the key, so you never pass a team id in a path or body.

curl "https://tame-dove-965.convex.site/v1/signals" \  -H "Authorization: Bearer $ASKENGINE_API_KEY"

Three conventions hold across every endpoint:

• Envelope — a single item comes back as { data }; a list as { data, cursor }. Unwrap data.
• Pagination — pass limit (1–50, default 20) and feed a response's cursor back for the next page. A null cursor means you've reached the end.
• Errors — failures return { error: { code, message } }; branch on the stable code. Two are worth knowing beyond the usual HTTP statuses: invalid_transition (409 — a lifecycle action the object's current state doesn't allow, like deciding an already-decided recommendation) and rate_limited (429, carrying a retryAfterMs).