For AI agents: the complete documentation index for the Restless API is available at https://build.restless.ai/llms.txt. This page is also available as Markdown at https://build.restless.ai/usecases/explain-why-a-user-got-stuck-then-close-the-gap.md (or send an Accept: text/markdown request header).

Explain why a user got stuck, then close the gap

Find out why someone got stuck by reading their own traffic, then fix the cause.

Someone says they could not get your API working. Their traffic is already recorded, so you can see exactly what happened: what they were trying to do, which request failed, and whether they found a way through or gave up.

Reach for this when a customer or a teammate reports being stuck. It reads their calls in order. That is what tells you whether they made a mistake, or your API never gave them a way to get it right. If it was the second, fix it where someone will read it before the next call, not just in the error that comes back after it.

A curated task for the Restless API: the calls to make, in order, as the API's owner wrote them. Humans run this as a guided conversation at the same URL; the steps below are that same recipe.

Steps

1. Confirm the identity and access behind the API key with `GET /api/v1/me`.
2. Pick the target project. If you only have an example slug, verify it with `GET /api/v1/projects/{slug}`, or browse options via `GET /api/v1/projects`.
3. Get the reporter's email address. Ask the user for it if you were not given one. You cannot do this from a name alone.
4. Pull that person's traffic with `GET /api/v1/projects/{slug}/logs`, passing the address as `groupEmail` and `limit=50`. Add `since` and `until` only if you know roughly when it happened.
5. If no rows come back, do not guess. Retry without `since` and `until`, and confirm you are on the right project. Then say you found no traffic, rather than inventing a cause.
6. Read the rows oldest first, as one session. Find the first non-200. The calls before it show what the person was trying to do. Repeated calls after it show whether they got through on their own.
7. Open that failing request with `GET /api/v1/projects/{slug}/logs/{logId}`. Read three things: the response body for the error text, the request body for what was actually sent, and `errorFingerprint.key` for the identifier you need in step 10.
8. Decide where the fix belongs. If the error text already said exactly what to change, the caller missed it. If the error named a rule the caller had no way to know in advance, such as a size limit or a required field that is not in the spec, the API is at fault. Several retries with different shapes is a strong sign of the second.
9. Tell the user what you found, and stop. The next two steps change what live callers see, so get agreement before making them.
10. Attach guidance to the failure with `POST /api/v1/projects/{slug}/recovery`, using the `fingerprintKey` from step 7. Read `GET /api/v1/projects/{slug}/recovery` first, so you replace the right message instead of adding a duplicate. Write for every error that shares that fingerprint, not just this one.
11. Record the rule where it is read before a call is made. Use `POST /api/v1/projects/{slug}/context` for knowledge the docs never had, or `PATCH /api/v1/projects/{slug}/content` to correct existing copy.
12. Report in the order it happened: what the person was doing, what failed and why, whether they recovered, and what you changed. Name the request id so the user can open it.