Making your first API request
Making your first request
Every request follows the same two steps: exchange your credential for a short-lived access token, then send that token with each data request. This page explains that process. This page assumes you already have a credential; if you do not, start with Creating a credential.
Try it live
The full API reference is interactive and public. It lists every endpoint with its parameters, responses and example payloads, and it lets you fire a real request from the browser:
Requests are answered in the region your account belongs to, and a credential issued in one region does not work in the other. Accounts in the EU region are served from within the EU; the endpoint for that region is provided when it is enabled for your account.
This guide describes the process. The interactive reference describes the current surface, endpoint by endpoint, and it is generated from the running service, so it is correct the moment anything changes. When the two appear to disagree, believe the reference.
The machine-readable OpenAPI document sits alongside it at /v1/schema on your
region's base URL. Point a client generator at it and most of the integration
writes itself, in whatever language your stack uses.
Step 1: exchange the credential for a token
Send your credential to the token endpoint and you get back a short-lived access token, the moment it expires, and the list of permissions it carries.
The credential travels in the request body, never a query string, so it
cannot end up in an access log, a proxy log, or a Referer header. Send it to
this one endpoint and nowhere else.
Check the permissions that come back. They are the ones on your credential, narrowed by what your account's grant allows, so if something you expected is missing then the grant does not include it.
Step 2: call the data endpoints
Every other request carries the token in an Authorization: Bearer header. The
reference lists what is available and what each call returns.
Reuse the token until it is close to expiring rather than requesting a fresh one per call. The token endpoint is rate limited, and a script that mints a token for every row will hit that limit; the response tells you how long to wait before retrying.
Paging through results
List endpoints return one page of results plus a cursor. Pass the cursor back to get the next page, and stop when it comes back empty. You can ask for a larger or smaller page; the reference gives the current default and maximum.
This is the pattern to reach for whenever you are pulling a whole study rather than a single record. It is stable under writes, unlike offset paging, so rows arriving mid-pull cannot cause you to skip or repeat one.
When a request is refused
Two behaviours are worth understanding before you start debugging, because both are deliberate and neither is a fault.
A refused credential never says why. Unknown, revoked, expired, or used from an address that is not on its allowlist all give the same answer. Telling an unauthenticated caller which gate refused them would turn the endpoint into a tool for probing credentials, so the specific reason goes to our audit log where an operator can look it up. When debugging your own integration, the usual cause is the address allowlist.
A record you cannot reach looks exactly like one that does not exist. A project belonging to another researcher returns what a fictional id returns. Any other answer would let a caller discover which records exist.
Everything else is an ordinary HTTP status, and the reference documents the codes each endpoint returns.
When something stops working
Every request is refused. Almost always the address allowlist. Check the address your script actually egresses from. A laptop on a VPN, a CI runner and a scheduled job on a server are usually three different addresses, and a cloud provider's egress can change without notice.
It worked yesterday and not today. Check whether the credential expired, whether somebody revoked it, or whether your team role changed. Roles are re-checked on every request, so a role change takes effect immediately.
A study is missing from the list. Archived and deleted projects are excluded, as are projects belonging to other researchers, even where you can see them in the dashboard through a team membership.
Keeping the credential safe
Read it from your environment or a secret manager. Never hard-code it into a script that lands in version control, and never paste it into a shared document, a ticket, a chat message, or a third-party AI tool. Anything holding it can read your study data from an allowed address.