How-To API Ask a natural-language “how do I…” question and get a grounded, product-aware answer in one call.

Submit a single natural-language question about Fastio and receive a grounded, product-aware answer in a single call. The answer is generated by Fastio’s built-in AI over the product’s how-to knowledge, so you get usage guidance without having to parse these docs yourself. When a question is too vague to answer well, the endpoint asks you a short clarifying question instead of guessing.

This is a top-level, user-authenticated endpoint — there is no org in the URL. It is open access: any authenticated, available user may call it with no org-membership requirement, no AI Agent plan-feature gate, no active-subscription requirement, and no billable entity. How-to is free: no org, user, or any entity is ever charged. The only access bound is the per-user rate limit.

When to Use It

• An agent or integration hits an unfamiliar part of the platform and needs a quick, authoritative “how do I do X in Fastio?” answer at runtime.
• You want product guidance grounded in Fastio’s own documentation rather than a general-purpose model’s recollection.
• You are building a help or assistant surface on top of Fastio and want a single request/response rather than managing a chat session.

For document Q&A over your own files (RAG), use the AI chat endpoints instead — see the Ripley Agent & AI reference. The How-To endpoint answers questions about Fastio itself, not about your uploaded content.

Endpoint Summary

On the dedicated API hosts (api.fast.io), call https://api.fast.io/current/how-to/ with no /api prefix. From any other hostname (for example go.fast.io), include the /api prefix: https://go.fast.io/api/current/how-to/.

Ask a How-To Question

POST /current/how-to/

Submit a single natural-language question. The response is one of two shapes — a grounded answer, or a request for clarification — both returned with HTTP 200.

Auth: Bearer token required. Open access — any authenticated, available user may call it. No org-membership requirement, no ai_agent plan feature, no subscription requirement, and no pre-flight credit cap. How-to is free — no entity is charged. The only access bound is the per-user rate limit.

Request format: application/x-www-form-urlencoded.

Parameters

Request Example

curl -X POST "https://api.fast.io/current/how-to/" \
  -H "Authorization: Bearer {jwt_token}" \
  --data-urlencode "question=How do I create a Send share and put a password on the link?" \
  --data-urlencode "context=I already have a workspace with files in it and want to deliver a report to a client."

Response — Answer (200)

Returned when the question could be answered.

{
  "result": true,
  "status": "answer",
  "answer": "Create the share from your workspace with POST /current/workspace/{workspace_id}/create/share/ using a Send share type, then set a link password and an access option of \"Anyone with the link\" so recipients can open it with the password. You can update the password later via the share update endpoint.",
  "escalated": false,
  "topics_used": ["shares", "workspaces"]
}

Answer Response Fields

Response — Needs Clarification (200)

Returned when the question is too ambiguous to answer well. This is a normal, expected outcome — not an error — so the HTTP status is still 200. Surface the returned question(s) to the user, then resend with a more specific question (and optionally context).

{
  "result": true,
  "status": "needs_clarification",
  "questions": [
    "Are you trying to share a single file, or a whole folder of files?"
  ]
}

Needs Clarification Response Fields

Handling tip: branch on status first. If status is "answer", read answer. If status is "needs_clarification", surface questions to the user and ask again — do not treat it as a failure.

Error Responses

Errors use the standard envelope: {"result": false, "error": {"code": …, "text": …, "resource": …}}. See Error Codes in the overview for the envelope shape and the global code list.

Standard rate limits apply. See the overview for the global rate-limit header schema (x-ve-limit-avail, x-ve-limit-max, x-ve-limit-expires) and error code 10368.

Billing

How-to is free — no org, user, or any entity is ever charged. The LLM call runs with skip-billing; no credits are consumed. There is no billable entity and no billing of any kind.

• Answers are briefly cached. A repeat of a recently asked question can be served from cache, which involves no AI call and is also free.
• A clarifying response involves a normal AI call and is also free.
• There is no pre-flight credit cap — the only access / abuse bound is the per-user rate limit.

Notes

• MCP surface (surface=mcp). Passing surface=mcp makes the answer phrased in terms of the Fastio MCP server’s consolidated tools (<tool> action="…") instead of REST API endpoints — useful when the caller is an MCP client that only has access to those tools. The surface selects the phrasing: mcp → MCP-tool phrasing, code → code-mode execute-proxy phrasing, and an omitted or unrecognized value → the default REST-API phrasing. This parameter does not change the two HTTP-200 response shapes (answer / needs_clarification) or the error table. If the MCP tool catalog cannot be loaded server-side, the endpoint transparently falls back to REST-API phrasing. Fully backward-compatible — existing callers that do not send surface are unaffected.
• Code surface (surface=code). Passing surface=code makes the answer phrased for a code-mode AI agent that issues Fastio API calls through an execute proxy — each concrete step is written as an execute-proxy call (e.g. fastio.post('/current/<path>/', { …body… })) rather than naming REST endpoints by URL. Calls are form-encoded by default; the *Json methods appear only where an endpoint documents a JSON body, and query parameters go in the last argument. Useful when the caller is a code-mode agent operating through a Fastio execute proxy. An unknown or absent surface still falls back to the default REST-API phrasing.
• Single-shot, not a session. Each call is independent. There is no conversation state to manage — supply everything the question needs via question and context.
• Concurrency. Only one how-to request per user runs at a time; a second concurrent call returns 145858 / HTTP 429 immediately rather than queueing. Wait for the first to finish before retrying.
• context is data, not instructions. Anything you pass in context is treated as untrusted background information about the user’s situation; it cannot redirect the assistant.
• No events. This endpoint emits no platform activity events. Its only side effect is the brief answer cache.
• Timestamps. Where any Fastio API returns date/time values, they use the canonical format 'Y-m-d H:i:s UTC' (e.g. 2026-06-16 14:30:00 UTC). This endpoint’s responses do not themselves contain timestamps.
• Rate limiting. A per-user sliding window bounds how-to usage (over-limit → 10368 / 429), plus a fail-fast per-user mutex that returns 145858 / 429 if a second how-to call is already in progress for the same user. This per-user rate limit is the only access bound on the endpoint. Standard rate-limit headers apply — x-ve-limit-avail, x-ve-limit-max, and x-ve-limit-expires. On a 10368 response, back off until x-ve-limit-expires.