For anything past a first curl, start from a client library rather than assembling requests yourself: pagination, retries and the WebSocket handshake are already handled, and those are the three things people rewrite badly. Massive maintains libraries on GitHub, and the documentation carries a runnable sample for every endpoint.
Applies to
- Plans: every plan. The libraries authenticate with an ordinary API key.
- Endpoints: all of them, REST and WebSocket.
- Asset classes: all.
Where to look, in order
Look in this order:
- The documentation for the endpoint you need. Every page carries a sample request and a sample response, which is usually enough to see the shape before you write anything.
- The client libraries on GitHub. Use one if your language has one. They handle authentication, paging through next_url, and the connect-authenticate-subscribe sequence on the WebSocket.
- massive.com/docs/rest/llms.txt, a machine-readable index of every REST endpoint, which is the fastest way to find what exists without reading the whole site.
What the samples will not tell you
The samples will not tell you three things that regularly surprise people:
- Paging. Most list endpoints return a next_url and the sample shows one page. Follow the cursor rather than raising limit.
- The limit parameter on aggregates counts base units scanned rather than bars returned, so a sample with a small limit will quietly return fewer bars than you expect over a longer range.
- Entitlement is per asset class. A sample that works for stocks will return NOT_AUTHORIZED for options unless you hold that subscription too.
Why start from a library
Starting from a library saves you the parts of the integration that are the same for everyone and easy to get subtly wrong: cursor paging, retry behavior on a 429, and keeping a WebSocket read loop from blocking on parsing, which is the single most common cause of disconnects. None of that is difficult, but all of it is already written.
If you see an error
A sample that returns NOT_AUTHORIZED is usually the asset class rather than the code. Check which subscription the endpoint belongs to.
A sample that returns fewer results than the documentation shows is often paging or the limit semantics rather than missing data.
A library that fails to authenticate is nearly always the key rather than the library. Test the same key with a plain curl first.
