How do you answer your own API questions instead of guessing?

There is a document that answers almost every question you will have about an API, and most people never open it. An OpenAPI specification is a machine-readable description of every path, every parameter, every legal value and every response shape the service offers. It is the contract. Prose documentation is a summary of it, written by a human, and summaries go stale.

What is in it

An OpenAPI document has a predictable skeleton. Under paths sits every endpoint. Under each endpoint sits the HTTP method, then parameters and responses.

Every parameter entry tells you four things:

• name — what to call it.
• in — path if it belongs in the address, query if it goes after the ?.
• required — true or false, and this one is worth checking every time.
• schema — the type, and often an enum listing the only values that are accepted.

A worked example, and why it settles an argument

Take /intraday/{ticker}. Reading the spec answers three things in about ten seconds.

First, interval is required: true. Almost every other query parameter in this API is optional; this one is not, so you must send it.

But be careful what you conclude from that flag, because here is the gap this lesson has to be honest about: a request without interval does not fail. Measured on 2026-09-15, it returns 200 and exactly the rows interval=5m returns — the server quietly picks a default. The spec says required; the server does not enforce it. That is worse than a failure: nothing in the response names the bar size, so code that meant to ask for 1m and dropped the parameter gets 5-minute bars and no signal at all.

Second, the enum for interval is exactly five values: 1m, 5m, 15m, 30m, 1h. Not three. A blog post that lists "1m, 5m and 1h" is not lying, it is incomplete — and if you needed 15-minute bars you would have concluded they did not exist.

Third, from and to on this endpoint are typed integer, not date. They are Unix timestamps in UTC; the spec's own example gives 1627896900 for 2021-08-02 09:35:00. On /eod/{ticker}, the parameters with the very same names are YYYY-MM-DD strings. Two endpoints, two parameter names in common, two different types. No amount of guessing gets you there; four seconds of reading does.

The most useful thing a spec tells you

Response schemas mark which fields can be null. The intraday response types volume as integer or null. The exchange list types OperatingMIC the same way.

That is a promise made in advance: a null is legal there, so your code must handle one. Discovering that from a spec costs nothing. Discovering it in production costs an incident.

What a spec will not tell you

Be honest about the limits of the format, because the interval case above is not a one-off. An OpenAPI document is a description written by the team, not a validator the server runs. It tells you what the service intends to accept, which is exactly what you need in order to construct a correct request — and it makes no promise that an incorrect one will be rejected. Read it to write good requests; never rely on it to catch bad ones.

Three places in this API where the document and the server disagree, all checked: interval is required and is not enforced; /ticks declares a response field called ex that never arrives; and the from/to parameters on the whole Treasury-rates family are documented and silently ignored, so a request for one day returns the whole year.

A spec also describes the contract, not the coverage. It will not tell you how far back history goes, which plan includes which endpoint, or that a dataset covers only one region — unless somebody wrote it into a description field.

Sometimes they did. The description on /symbol-change-history says "Only US exchanges are currently supported", which is a coverage fact hiding in a contract document and is exactly the sort of sentence that saves a day of debugging. So read the description fields, not just the schemas. And when the spec is silent about coverage, the answer comes from the product documentation or from a test call, not from assumption.

Try it now

1. Below is the spec entry for /intraday/{ticker}, as read on 28 September 2026, laid out as two tables: its query parameters, then the fields of its 200 response schema. Find the enum values of each parameter and check them against whatever you would send.

2. Find the field in that response schema typed as nullable, then find the line in your code that would break if it ever came back null.
3. Find the one required: true query parameter in the first table. Read on 28 September 2026, the whole spec outside the marketplace paths marks only the query parameters below required. Say which one of them this lesson has already shown the server not enforcing. There are few of them, which is precisely why they surprise people.