AI Prompt Guide

/v1/ai is not a general chatbot. It answers currency conversion, FX rate, and PPP questions, and it calls deterministic tools for numbers. A good prompt names the currencies, the amount, the date or window, and the comparison set. This page shows prompts that map cleanly to the 12 current data shapes.

The response does not name the tool that ran. The “Expected result shape” column describes what you should see in data, not an internal tool name. See AI response schema for the full types.

Prompt patterns

Three patterns are worth calling out:

• A “rate” question can return either shape. The assistant usually calls the conversion path with amount: 1 for a single pair, but a multi-currency rate list returns a rates object. Check for rates before assuming result exists.
• A 200 is not always an answer. Clarifications, no-data explanations, upgrade prompts, and too-large notices all use 200 with data: []. See AI quickstart.
• One request can return several shapes. A question that asks for a conversion and a trend can produce a data array with a convert object and a history-analysis object. Render each entry by its fields, not by position.

Prompt anatomy

Use these six ingredients when a prompt is not behaving:

1. Name the currencies. ISO codes are the most reliable (USD, EUR, INR). Names, symbols, and countries usually resolve, but ambiguous names can trigger a clarification.
2. Give the amount. A salary or cost-of-living question without an amount is answered with a question, not a guess.
3. Name the date or window. Prefer an absolute date (2015-06-01) or a clear window (the last 10 years, since 2015). Named events such as COVID-19, Brexit, the 2008 financial crisis, the European debt crisis, and the dot-com bust resolve to documented windows.
4. Name the comparison set. “Which currencies?” is ambiguous. List the codes, or say “rank the liquid currencies” when you want a ranking.
5. State the base. “Against USD” removes doubt in a comparison, ranking, or correlation question.
6. Ask for one thing at a time. Multi-part questions can fan out into several tool calls and increase latency. Split unrelated questions across requests.

Bad prompt to better prompt

What a prompt cannot change

• No conversation memory. Every request is independent. If a follow-up needs prior context, repeat it in the new q.
• No streaming. The full JSON response arrives at once.
• No web browsing or news. The answer is based on the rate and PPP data in the tools, not on live news.
• No forecasts or financial advice. Prediction, recommendation, and trading signal questions are refused.
• No custom output format. answer is plain text, not Markdown or JSON. Use data for structured output.
• No instruction override. The prompt is treated as a question. Requests to change the rules or reveal the system prompt are refused.

When to use REST instead

Use the matching REST endpoint when you need:

• Exact control over every parameter, including intervals, limits, and sorting.
• Raw daily history rather than a downsampled series.
• A guaranteed single shape, without inspecting a dynamic data array.
• High-volume batch conversions, where one request per answer is wasteful.
• Per-number provenance. /v1/ai does not return citations today; REST responses are the canonical source you can cite.

Start with AI grounding for verification patterns, then AI response schema for the exact shapes.